趁着过年假期，梳理下claude code的使用，做一个回顾，分享一下

一、代码编写规范与最佳实践

在基于Claude Code的协作开发中，代码编写规范与最佳实践主要通过 规则（Rules） 与 技能（Skills） 两类配置文件进行系统性定义与管理。这套机制旨在将个人或团队的编码习惯、质量标准和安全要求固化，并被AI自动加载和应用，从而实现代码质量的一致性，并从根本上解决“每次都要重复解释规则”的问题。

1.1 通过规则（Rules）与技能（Skills）定义规范

代码规范的管理存在两种核心模式：

• 规则（Rules）：位于项目根目录的 .claude/rules/ 文件夹下，是项目级的强制性或指导性约束。它们定义了适用于整个代码库的通用标准。

• 技能（Skills）：位于 skills/ 目录下，是可复用的知识模块，封装了特定技术栈的最佳实践或个人/团队的工作流程与习惯。

一个典型的规范定义层级如下：

层级	配置文件示例	作用与内容
项目通用规则	.claude/rules/coding-style.md	定义全项目遵守的缩进（如2个空格）、文件组织方式、不可变性要求等基础风格。
项目特定规则	CLAUDE.md (项目根目录)	项目级别的具体规范文件，可包含如变量命名使用驼峰命名法等要求。
多语言最佳实践	skills/coding-standards/	封装了针对多种编程语言的编码标准和最佳实践。
特定语言技能	skills/go-style/, skills/python-best-practices/	提供Go、Python、TypeScript等特定语言的高级指导和惯例。
个人/团队习惯	skills/my-coding-style/ 或 skills/team-workflow/	固化个人或团队独有的编码风格、注释习惯和错误处理模式。

通过配置上述文件，Claude在编写或审查代码时会自动遵循这些内置规则，无需开发者额外提醒，确保了自动化与一致性。

1.2 命名规范（Naming Conventions）

命名规范是代码可读性的基石。在自定义的技能（如my-coding-style）中，可以明确以下规则：

1. 变量（Variables）：使用驼峰命名法（camelCase）。例如：userName, dataList, orderTotal。

2. 函数/方法（Functions/Methods）：以动词开头，清晰表达其行为。例如：getUserData(), calculateTotal(), validateInput()。

3. 类（Classes）：以大写字母开头，通常使用名词。例如：UserService, DataProcessor, PaymentGateway。

将这些规则写入 SKILL.md，Claude便会永久记忆并应用。

1.3 文件组织结构最佳实践

清晰、一致的文件结构是维护大型项目的关键。对于**技能（Skills）**本身的组织，文档中强调了以下必须遵守的规范，这些思想同样适用于普通项目模块的组织：

1. 核心文件命名必须精确：

   • 技能的核心指令文件必须命名为 SKILL.md（大小写敏感）。

   • 不接受任何变体，如 SKILL.MD、skill.md、Skill.md 等都是无效的。

2. 目录命名使用 kebab-case：

   • 技能文件夹的名称必须使用短横线连接的小写单词（kebab-case）。

   • 正确示例：notion-project-setup, api-client-generator

   • 错误示例： Notion Project Setup（包含空格） notion_project_setup（使用下划线） NotionProjectSetup（驼峰命名）

3. 推荐的文件结构范例： 一个结构清晰的技能目录示例如下，体现了“渐进式披露”原则，以优化上下文使用：

skills/
├── your-skill-name/          # 使用 kebab-case 命名
│   ├── SKILL.md              # 核心指令与概览（必须）
│   ├── sub-skill.md          # 子技能或进阶指南（可选）
│   ├── scripts/              # 存放可执行的工具脚本
│   │   └── setup.js
│   └── assets/               # 参考资料、模板等静态资源
│       └── reference.pdf

这种结构将复杂的知识按场景拆分，仅在需要时动态加载相关文件，避免了污染主上下文。

1.4 代码风格与格式（Code Style & Formatting）

代码风格规范通过规则文件和技能共同定义，以确保自动化执行。

1. 基础格式规则（通常在 coding-style.md 或 CLAUDE.md 中定义）：

   • 缩进：统一使用 2个空格。

   • 行宽：建议设置最大行宽限制（如80或120字符）。

   • 引号：统一使用单引号或双引号。

   • 句尾分号：明确是否要求使用。

2. 自动化保障：

   • 通过 Git Hooks 或 Claude Code 的 Hooks 机制，可以配置在文件保存或提交前自动运行代码格式化工具（如 Prettier、Black、gofmt）。

   • 例如，可以设置一个 Hook，在编辑任何 JavaScript/TypeScript 文件后自动执行 prettier --write，确保格式即时统一。

1.5 注释规范（Commenting Conventions）

有效的注释能极大提升代码的可维护性。应在自定义技能中明确注释的原则与格式。

1. 核心原则：

   • 解释“为什么”这么做，而非“做了什么”（代码本身应体现逻辑）。

   • 针对公共接口、复杂算法、关键业务逻辑和非直观的代码进行注释。

2. 具体规则示例（可定义在 my-coding-style 技能中）：

   • 函数/方法注释：位于声明上方，说明功能、参数、返回值和异常。

   • 复杂逻辑注释：在复杂代码段前用一行注释说明意图或策略。

   • TODO/FIXME 注释：使用统一格式，如 // TODO [责任人]: [描述]。

   • 避免事项：禁止注释对代码的直译；确保注释及时更新；保持注释语言与项目主要语言一致。

3. 最佳实践：在技能文件中，结合具体代码示例来说明良好的注释风格，这比抽象的描述更有效。

1.6 错误处理规范（Error Handling）

健壮的错误处理是高质量代码的标志。其最佳实践贯穿于代码编写和架构设计。

1. 结构化错误处理：

   • 在代码中，使用明确的错误类型和清晰的错误信息。

   • 在技能文档中，设立 # Troubleshooting 或 # Common Issues 章节，以标准格式系统化记录常见错误、原因和解决方案：

# Common Issues
## Error: Connection refused
**Cause:** MCP server is not running or API key is invalid.
**Solution:** 
1. Verify server status in Settings > Extensions.
2. Check and update the API key.
3. Attempt to reconnect.

2. 程序化错误回退机制：

   • Claude Code 的执行环本身内置了容错设计：当一个工具（如执行 Shell 命令）失败时，不会导致整个进程崩溃，而是会将详细的错误信息（堆栈、上下文等）封装并反馈给 AI 模型。模型能据此分析并尝试替代方案或提供修复指导，实现一定程度的自我修正。

3. 智能体协作中的错误兜底：

   • 在复杂工作流中，借鉴多智能体协作思想，将错误处理职责分离。例如，创建专门的 build-error-resolver 或 security-reviewer 子代理。当构建失败或发现安全漏洞时，主代理可将问题委托给这些专门处理的子代理，实现问题领域的隔离与高效解决，而非主模型盲目尝试。

1.7 安全编码规范（Security Practices）

安全规范应作为强制性规则融入开发全流程，其核心是 “最小权限” 和 “默认拒绝” 原则。

1. 核心安全规则：

   • 制定 security.md 规则文件，明确规定禁止硬编码密钥、证书等敏感信息。

   • 在代码风格规则中，可以加入禁止提交用于调试的 console.log 语句，防止敏感信息泄露。

2. 严格的权限控制：

   • 在 Claude Code 的 permissions 配置中，使用 allowedTools 白名单，明确只允许使用必要的工具（如 Read， Write， Edit）。

   • 结合黑名单进行细粒度控制，例如，允许使用 git 命令，但明确禁止 rm -rf * 等危险操作。

   • 为不同职责的子代理配置不同的工具集。例如，一个只读的代码审查代理，可能只被赋予 Read 和 Grep 权限。

3. 自动化安全检查：

   • 利用 Hooks 在开发阶段进行实时拦截。例如，配置一个 Hook，在编辑任何文件后自动扫描是否有硬编码的密码或密钥模式，并发出警告。

   • 通过安全审查专用技能或子代理，系统性地检查认证缺陷、SQL注入、XSS漏洞、不安全的依赖等问题。

---

二、开发流程与团队协作指南

基于前序章节建立的规范化规则与可复用技能体系，本节将围绕**“流程标准化”与“协作自动化”**两大核心，构建高效、可控的AI辅助开发循环。我们将定义一个融合了代码提交、分支隔离、团队分工与知识固化的系统化工作流，确保AI（Claude Code）能像一名专业的团队成员一样协作。

2.1 开发流程标准化：从构思到交付

一个稳定的AI开发流程，关键在于将不可预测的生成转化为可管理的阶段，并为每个阶段设置明确的“质量锚点”和“安全边界”。

1. 结构化工作流与迭代优化

开发工作应遵循 “三步方法论” 并持续迭代优化：

• 规划（Plan）：任何非琐碎任务开始前，优先进入Plan模式。花少量时间与Claude共同理清实现路径、定义接口、识别依赖，形成任务清单。这能有效避免执行过程中的目标漂移和来回修改。

• 执行与审查（Execute & Review）：基于规划，在开发沙箱（功能分支）中执行。代码变更须经过自动化代码审查（触发/code-review或由code-reviewer子代理执行），审查标准自动加载.claude/rules/（如testing.md, security.md）中定义的强制性规范。

• 交付与复盘（Deliver & Retrospect）：通过预定义的Git流程合并代码。事后，可提示Claude “Update your claude.md”，将本次纠错或学到的经验固化到项目知识库中，实现工作流的持续进化。

2. 核心流程：分支管理与代码提交

为驾驭AI编程的不可预测性，必须严格执行基于Git的分支管理与提交规范。

📁 分支管理策略：主分支保护与功能分支实验

• 核心目标：保护主分支（main）的稳定性，为AI的大幅修改或实验性功能提供安全的沙箱环境。

• 标准操作程序（SOP）：

  1. 创建功能分支：进行任何存在风险的修改前，立即从main分支创建新分支。

git checkout -b feature/your-feature-name

2. 在分支上开发：在新分支上，可让Claude自由探索和修改，所有变更与主线隔离。

3. 成功则合并：验证通过后，切换回main并合并分支。

git checkout main
git merge feature/your-feature-name

4. 失败则丢弃：若实验不理想，直接丢弃分支，主分支不受影响。

git checkout main
git branch -D feature/your-feature-name

✅ 代码提交流程：“存档两连”与黄金铁律

• 基础操作：高频使用git add . + git commit -m “<清晰信息>”（“存档两连”）创建安全锚点。提交信息应遵循团队规范（如Conventional Commits）。

• Vibe Coding 强化铁律：

环节	铁律	说明
提交时机	高频提交	每完成一个小功能点或AI完成一轮重要修改（约每10-15分钟）就提交一次。
提交前置	重构前必提交	黄金法则：在让AI进行任何重构或重大修改之前，必须先提交当前稳定状态。
错误处理	3次失败即回滚	若AI连续修复同一Bug 3次未果，立即用git reset或git revert回滚到上一个正常提交，换个思路重来。
云端备份	每日推送	工作结束前，使用git push将提交同步到远程仓库（如GitHub），实现云端备份。

2.1 团队协作模式化：智能体分工与并行

Claude Code 支持两种核心的团队协作模式，用于将复杂任务分解并由多个“智能体”并行处理。

模式	核心区别	适用场景	优点
🤝 Agent Teams	队友（Teammates）之间可以直接沟通，无需通过项目经理（Team Lead）中转。	复杂的、子任务间需要紧密配合的大任务（如从设计到开发的全流程）。	并行协作效率高，模仿真实团队互动。
🔀 Subagent (委派)	子代理之间不能直接通信，所有工作由主代理（Main Agent）“委派-返回”。	独立的、无需交互的子任务，或作为标准化工具链的一部分（如代码审查流水线）。	节省Token，架构清晰可控，适合自动化流水线。

1. Agent Teams 使用指南

Agent Teams 模拟了一个真实的项目团队，包含 Team Lead 和多个具有独立上下文的 Teammates。

• 启用配置：在Claude Code的settings.json中设置 “experimental”: { “agentTeams”: true }。

• 创建团队：

  • 详细指定：用自然语言明确每个队友的职责。

指令示例：“创建一个Agent Team来开发产品介绍页：队友「文案」负责撰写内容；队友「设计师」负责HTML/CSS实现；队友「市场」负责竞品分析。”

• 自动拆分：仅说明目标，让Claude自行规划分工。

21. 高级技巧：

    • 委托模式（Delegate Mode）：使用 Shift+Tab 强制 Team Lead 只做协调和分工，不执行具体任务。

    • 状态查看：使用 Shift+↑/Shift+↓ 在终端中切换查看不同队友的工作状态。

2. Subagent 委派模式

Subagent 适合构建专业化的工具链，将特定任务委派给专用智能体。

• 工作模式：主代理识别任务 → 调用特定Subagent（如code-reviewer）→ Subagent在独立上下文执行并返回精炼总结 → 主代理整合结果。

• 链式调用示例：对于“研究->实现->测试”工作流，主代理可以依次委派给Explore、Implementer、Test-runner三个Subagent，形成高效流水线。

• 常用模式：

  • 代码审查流水线：并行调用style-checker、security-scanner、test-coverage三个Subagent审查PR。

  • 大型重构：将需修改的文件分组，为每个组启动一个Subagent并行修改。

2.3 团队最佳实践与效率引擎

1. 规划先行，交叉审核

• 强制规划：复杂任务务必从Plan模式开始。若执行中发生偏离，立即切回Plan模式重规划，而非反复修补。

• 交叉审核：使用两个Claude实例，一个负责编写计划，另一个负责审查，以规避思维盲区，提升计划质量。

2. 最大化并行处理

• 多开实例：避免任务串行。通过多开终端窗口或Claude Code实例，并行处理多个独立任务。

• 使用 Git Worktrees：创建多个独立的worktree，每个运行完全隔离的功能开发，并通过快捷键快速切换。

• 工具链集成：通过MCP连接Figma、Linear、Slack等服务，实现“设计-任务管理-沟通”的自动化交接，消除上下文切换。

3. 固化团队知识：claude.md 与技能仓库

• 维护单一真理源：将项目级的claude.md文件作为团队的**“项目宪法”**提交到仓库，全体成员共同维护，积累所有纠正AI的规则和经验。

• 让AI自我进化：纠正Claude的错误后，指令其 “Update your claude.md, so you don‘t make that mistake again”，让它自己编写和更新规则，效果更持久。

• 共享项目级Skills：在.claude/skills/目录下创建团队共享的技能（如team-code-review、git-commit-standards），通过Git实现协作规范的版本化与一键复用。

4. 沟通规范与安全边界

• 沟通自动化：将团队沟通规范（如代码审查要点、周报格式）编写成Skill，Claude会在对应场景（如审查PR时）自动加载应用，减少重复解释。

• 安全策略：当AI助手接入团队沟通平台（如飞书）时，必须配置安全策略：

  • 私聊：采用配对（Pairing）策略，用户需申请并经管理员批准后方可对话，防止信息泄露。

  • 群聊：强制开启提及回复（requireMention），机器人只回复@它的消息，避免干扰群聊。

2.4 核心协作原则总结

1. 流程优于猜测：通过规划（Plan）、分支隔离、提交锚点构建可预测、可回滚的开发流程，而非依赖AI的随机生成。

2. 模式匹配场景：紧密协作选Agent Teams，独立任务用Subagent委派，合理选择工具以平衡效率与资源。

3. 知识需要固化：将团队智慧沉淀于claude.md和项目Skills中，让AI成为团队规则的忠实执行者与传承者。

4. 并行提升吞吐：积极采用多实例、Git Worktrees和自动化流水线，最大化利用AI的并行处理能力。

5. 安全划定边界：在流程中嵌入自动化审查（Rules），在协作中设定沟通权限，确保开发既高效又可控。

通过将上述流程、模式与实践内化为团队习惯，Claude Code将从一个强大的代码生成工具，演进为真正融入团队文化、驱动项目高效交付的智能协作系统。

---

三、项目初始化与环境配置

项目的顺利启动和开发环境的正确配置是后续高质量、高效率协作的基础。本节将梳理从零开始搭建一个规范化的、适用于团队协作的开发环境，并初始化项目结构。

3.1 基础环境准备

在开始任何项目之前，确保你的本地开发环境满足基础要求。

• 系统与Node.js：Claude Code支持Windows 10/11、macOS 10.15+及主流Linux发行版。Windows用户强烈建议使用WSL2以获得最佳体验。运行Claude Code需要Node.js作为基础，要求版本为v22.x.x或更高。

  • 在终端输入 node --version 和 npm --version 进行检查。

  • 如需安装或升级，可通过系统包管理器（如macOS的Homebrew brew install node）或前往nodejs.org下载LTS版本。

• 安装Claude Code：通过npm进行全局安装。

npm install -g @anthropic-ai/claude-code

安装完成后，使用 claude --version 验证安装成功。

• 配置模型API密钥：Claude Code需要大模型API驱动，支持Anthropic Claude以及国内主流模型（如MiniMax、GLM、Kimi等）。

  • 获取密钥：根据你选择的模型提供商，前往其官方平台注册、认证并获取API Key。例如，对于MiniMax，需访问其平台订阅Coding Plan并创建API Key。

  • 配置方式：将获得的API Key及相关环境变量（如 ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL）配置在Claude Code的设置中，或使用如 CC Switch 等图形化工具进行便捷管理。

3.2 项目初始化核心步骤

当基础环境就绪后，即可进入具体的项目目录进行初始化。此过程旨在为项目注入结构化的AI协作能力。

1. 进入项目根目录：打开终端，cd 到你的项目文件夹。

2. （强烈推荐）初始化Git仓库：在开始任何AI辅助开发前，先执行 git init 初始化Git版本控制。这是实施 存档两连 等安全开发实践的前提。

3. 运行 /init 命令：在项目根目录的终端中，输入 /init 并按Enter。

   • 作用：此命令会自动在项目根目录创建一个名为 .claude 的隐藏文件夹，并生成一个初始的 CLAUDE.md 文件。它帮助Claude分析你的代码库结构。

   • 时机：第一次在项目中使用Claude Code时执行，或希望AI持久记忆项目背景时执行。

4. 理解并编辑 CLAUDE.md：CLAUDE.md 文件是项目的“宪法”，它为Claude Code提供了持续的上下文，防止其在长期、复杂的任务中目标漂移。

   • 核心作用：Claude会在每次对话开始时自动读取此文件，获取从代码中无法推断的项目规范、规则和偏好。

   • 应包含的内容：

     • 项目规范：如代码组织结构（前端/后端目录分离）。

     • 代码风格：如缩进使用2个空格、采用驼峰命名法。

     • 工作流程：如要求所有代码修改后必须经过审查。

     • 任何你希望Claude持续记住的Bash命令、Agent规则或团队约定。

3.3 配置结构详解：.claude 目录

/init 命令创建的 .claude 目录是配置的核心。一个成熟的配置结构（可参考官方社区方案如 Everything Claude Code）通常包含以下组件：

• agents/****（子智能体）：存放定义了特定角色的子代理文件。这些子代理可被主会话委派任务，用于专业化分工。

  • 示例：planner.md（规划师）、architect.md（架构师）、code-reviewer.md（代码审查员）。

• skills/****（技能）：存放封装了常见工作流和领域知识的技能。技能是可复用的、复杂的提示模板。

  • 目录结构：每个技能是一个文件夹，使用 kebab-case 命名（如 tdd-workflow），其核心文件必须命名为 SKILL.md。

  • 层级：技能可以分层加载。SKILL.md（Level 1）包含核心指令，SKILL_2.md（Level 2）包含详细说明，具体代码或数据可作为外部文件（Level 3）。

  • 分类：

    • 项目级技能（.claude/skills/）：存放团队共享标准，如team-code-review（团队代码审查清单）、git-commit-standards（Git提交规范）。这些应提交到Git仓库，实现团队共享。

    • 个人级技能（~/.claude/skills/）：存放个人工作习惯和偏好。

• rules/****（规则）：存放定义了必须始终遵循的强制性开发规范和流程的文件。

  • 核心规则文件：security.md（安全规范）、coding-style.md（代码风格）、testing.md（测试规范，例如要求遵循TDD并确保至少80%测试覆盖率）、git-workflow.md（Git工作流）。

• hooks/****（钩子）：用于配置基于事件（如工具调用前/后）触发的自动化脚本。可通过配置 settings.json 实现提交前自动格式化、Lint检查或运行测试。

• MCP（模型上下文协议）配置：用于连接GitHub、数据库、浏览器等外部服务，通常在全局或项目配置文件中设置。

3.4 最佳实践与案例

一个高效的初始化不仅是运行命令，更是建立一套可持续的工作系统。

• 实践：首次引导（可选但推荐）：在更广义的“初始化”中，可以进行一次详细的引导对话，将你的身份、时区、期望AI扮演的角色、工作偏好和边界（如“哪些操作必须确认”）等信息保存到 BOOTSTRAP.md 或 IDENTITY.md 文件中，以定制更稳定的AI助手。

• 案例：初始化一个规范的Web项目

  1. cd my-web-project

  2. git init

  3. 执行 /init。

  4. 编辑生成的 CLAUDE.md，写入：

# 项目：My Web App
- **技术栈**：React 18, TypeScript, Vite。
- **代码风格**：使用2空格缩进，组件使用PascalCase，函数使用camelCase。
- **重要规则**：所有UI组件必须放在 `src/components/` 下，并使用 `*.tsx` 后缀。
- **流程**：新增功能前，请在 `feature/` 分支开发，并通过 `/code-review` 命令审查。

5. 创建团队技能：在 .claude/skills/ 下新建 team-frontend-guide/ 目录，创建 SKILL.md 文件，写入团队的前端代码审查清单。

6. ⚠️ 配置黄金法则：保持轻量化：上下文窗口是“硬通货”。你可以引入很多配置（如20-30个MCP服务器），但单个项目同时启用的应少于10个，保持活跃工具总数在80个以下。切勿全盘照搬复杂配置，只选用对当前项目有用的部分，并在项目配置中用 disabledMcpServers 字段禁用不需要的服务。

---

四、代码提交与分支管理

为安全、高效地驾驭AI辅助编程的不可预测性，团队必须遵循一套结构化的版本控制实践。本章将详细阐述代码提交与分支管理的核心策略与标准操作程序。

4.1 核心策略：主分支保护与功能分支实验

本策略的核心目标是：保护主分支（main）的稳定性，同时为任何可能存在风险的、由AI驱动的大规模重构或功能开发提供一个安全的实验沙箱。主分支应始终代表项目可运行的稳定状态。

其实施基于一个标准的Git工作流，下图清晰地展示了从创建功能分支到合并或丢弃的完整闭环：

1. 创建功能分支

当需要执行一项不确定性较高的任务时，应立即从当前的 main 分支创建一个新的功能分支进行隔离。

git checkout -b feature/your-feature-name

建议使用 feature/__、fix/、hotfix/ 等前缀清晰标识分支目的，分支名采用 kebab-case。

2. 在功能分支上进行开发

在新分支上，可以安全地进行任何代码修改和实验。此时的所有变更都与 main 分支隔离。

3. 分支合并（实验成功）

如果功能分支上的改动达到预期且运行正常，可将其合并回主分支。

git checkout main          # 切换回主分支
git merge feature/your-feature-name  # 合并功能分支

合并前，应确保主分支是最新状态（git pull）。建议在合并后删除已合并的本地功能分支以保持整洁。

4. 分支丢弃（实验失败）

如果功能分支上的改动结果不理想，可以直接丢弃该分支，而 main 分支将保持原状。

git checkout main          # 切换回主分支
git branch -D feature/your-feature-name  # 强制删除未合并的功能分支

4.2 代码提交流程标准程序 (SOP)

标准提交流程融合了 Git 操作与 AI 编程的最佳实践，其核心是 “存档两连” 高频提交。

标准提交操作

1. 暂存更改：在项目根目录执行 git add .，将所有变更放入暂存区。

2. 创建提交：紧接着执行 git commit -m “<清晰的提交信息>”，将暂存内容正式保存为一个“存档”。

3. 提交信息规范：提交信息应清晰有意义，遵循团队约定（如 Conventional Commits 格式 type(scope): description），避免使用“update”、“fix”等无信息量的描述。这对未来追溯历史至关重要。

Vibe Coding 强化实践与铁律

在AI辅助编程中，提交不仅是记录，更是核心的防御性工程实践。

实践环节	具体操作与铁律	原因与说明
高频提交	每完成一个小功能、AI完成一轮重要修改，或代码能正常运行后（约每10-15分钟）就执行一次“存档两连”。	创造更多安全锚点，便于随时回滚到上一个可用状态。
提交前置	黄金铁律：在让AI进行任何重构或重大修改之前，必须先提交 (commit) 当前稳定状态。	为AI高度不确定的重构操作提供最关键的“后悔药”。
错误回滚	判断标准：如果AI连续修复同一个Bug 3次以上仍未成功，应立即回滚到上一个正常的提交，让AI换个思路重新开始。	防止陷入“打地鼠”式的无效循环，避免代码被越改越乱。
云端备份	日常保险：每天结束工作前，使用 git push 将本地提交同步到远程仓库（如GitHub）。	防止本地数据丢失，实现代码的云端备份。

4.3 知识固化与团队协同

所有与提交、分支相关的团队规范（如提交信息格式、分支命名规则、合并前检查清单）都应通过项目级 Skill 进行固化。这些 Skill 存放于 .claude/skills/ 目录（例如 git-commit-standards/），并提交至项目仓库，确保团队成员共享同一套标准，减少沟通成本。

在合并完成后，可以通过指令 “Update your claude.md” 提示Claude，将本次分支策略或钩子优化等经验写入项目的 CLAUDE.md 文件，实现团队知识的持续沉淀与迭代。

---

五、代码审查与质量保障

在 Claude Code 项目的开发实践中，代码审查是一个自动化、结构化且标准化的核心流程。它旨在通过预定义的规则和技能确保代码质量，而不仅依赖人工的随机抽查，从而高效、一致地发现问题并推动代码改进。

5.1 结构化审查操作流程

代码审查主要通过专门的智能体（Agents）、技能（Skills） 和命令（Commands） 来实现一个三步走的闭环流程。

1. 触发审查

   • 使用斜杠命令：开发者可直接在 Claude Code 中键入 /code-review 命令来手动发起审查请求。

   • 智能体委派：在主会话（扮演协调器角色）中，可以将审查任务正式委派给专门的 code-reviewer.md 智能体执行。

   • Hooks 自动触发：通过配置 hooks.json，能在特定条件（如使用 Edit 工具修改关键文件后）下自动启动审查，实现“提交前检查”。

2. 执行审查

   • 审查专用智能体：code-reviewer.md 被设计为“高级代码审查者”，专注于检查质量、安全与可维护性。它通常配备 Read、Grep、Glob 等只读工具进行深度代码分析。

   • 并行流水线模式：对于复杂或高标准要求的场景，可采用 多智能体并行流水线。例如，同时启动 style-checker（代码风格）、security-scanner（安全扫描）、test-coverage（测试覆盖率）三个子代理并行审查一个 PR。各代理用一致格式返回发现，由主代理综合成完整意见。

   • 逻辑深度审查：审查不仅停留在语法层面。在功能开发的“质量审查（Quality Review）”阶段，code-reviewer 子代理会执行逻辑审查，确保业务逻辑的正确性与健壮性。

3. 输出审查结果 审查结果以结构化格式清晰呈现，便于定位和处理。标准输出格式通常包含：

   • 严重性（Severity）：High / Medium / Low

   • 位置（Location）：文件路径:行号

   • 建议（Suggestion）：具体的代码修改或优化建议

5.2 基于规则与技能的审查质量标准

审查并非基于主观判断，而是严格遵循项目内固化的、可版本控制的强制性规范和最佳实践清单。

1. 规则（Rules）文件：强制执行的底线 在项目 .claude/rules/ 目录下的规则文件定义了必须遵守的质量底线，审查时会自动引用并强制执行：

规则文件	核心质量标准要求
testing.md	遵循测试驱动开发（TDD），并确保至少达到 80% 的测试覆盖率。
coding-style.md	规定代码风格，如不可变性原则、文件组织、函数行数限制（如不超过50行）、嵌套深度控制（如避免超过3层）等。
security.md	强制进行安全检查，例如禁止硬编码密钥、必须进行输入验证、防范常见注入攻击等。
git-workflow.md	规定提交信息必须遵循 Conventional Commits 等格式规范。

2. 技能（Skills）：封装团队最佳实践 团队将特定的审查标准和检查清单封装成可复用的 Skills，实现知识的共享与自动化应用：

   • 团队审查清单 Skill：例如 team-code-review-checklist，其中定义了团队共识，如“可读性优于性能（非关键部分）”、“错误处理必须完整”等。

   • 安全审查 Skill：专门的 security-reviewer Skill 会指导审查者按 OWASP Top 10 等清单系统检查认证授权、注入风险、敏感数据暴露等问题，并按严重性分级。

   • 语言专用 Skill：项目为 Go、Python、TypeScript 等语言提供了针对性的审查技能和智能体，确保符合该语言生态的最佳实践。

5.3 实战效果与总结

这套将自动化流程与明文标准相结合的质量保障体系在实践中效果显著。根据黑客松的实战数据，采用此配置后，代码审查问题减少了75%，PR的平均问题数从 12.3 个降至 3.1 个。这证明，通过 /code-review **命令、**code-reviewer 智能体及规则技能文件的协同，能够系统性地将高质量的开发标准融入日常流程，而非依赖偶然的人工检查，从而持续、稳定地提升代码库的整体质量与安全性。

---

六、团队协作与沟通规范

建立在完备的项目配置（CLAUDE.md、.claude/rules/、.claude/skills/）与成熟的开发流程（分支管理、代码审查）之上，团队的高效协作依赖于明确的操作模式、固化的沟通规范以及精细的资源管理。本节梳理定义团队协作的核心模式、沟通规范的制定与执行标准，以及确保协作安全、高效的最佳实践。

6.1 核心协作模式：Agent Teams 与 Subagent 委派

前面介绍了Claude Code 的两种核心的团队协作功能，Agent Teams 与 Subagent ，适用于不同复杂度的任务场景。正确选择模式是高效协作的第一步。

选择与配置指南：

• 启用 Agent Teams：在 Claude Code 的配置文件（如 settings.json）中，启用试验性功能。

"experimental": {
  "agentTeams": true
}

• 使用模式：

  • 详细分工指令：直接指定队友数量及职责。例如：“创建一个 Agent Team 来完成这个功能：队友「后端」负责 API 接口，队友「前端」负责页面组件，队友「测试」负责编写测试用例。”

  • 委托模式：使用 Shift+Tab 开启，强制 Team Lead 只做协调和分工，不执行具体任务，确保工作被合理分配。

15. Subagent 链式调用：对于多阶段工作流，主代理可以串联调用多个 Subagent。例如：主代理 ->（委派研究给 Explore）->（委派实现给 Implementer）->（委派测试给 Test-runner）。每个 Subagent 应返回精炼的总结，而非倾倒全部对话历史。

6.2 沟通规范的制定与固化

团队沟通规则（如代码审查清单、提交信息格式、周报模板）必须被文本化、结构化并版本化，通过 Claude Skills 实现自动化执行，避免依赖口头传达或临时提醒。

1. 规范结构：Skills 的三级加载范式 为提高加载效率和清晰度，复杂的团队规范 Skill 应采用三级结构：

   • Level 1 (SKILL.md)：核心规则摘要和触发条件。必须包含清晰的 YAML frontmatter，description 字段用于定义自动应用场景。

name: 团队代码审查标准
description: Apply our team‘s code review checklist when reviewing PRs, suggesting improvements, or executing `/code-review`.

• Level 2 (SKILL_2.md)：详细的规则解释、示例和背景说明。

• Level 3 (外部文件)：具体的检查清单、模板代码、数据等支撑材料。

4. 职责分离：项目级 vs 个人级 Skills

   • 项目级 Skills (./.claude/skills/)：存放团队共享、必须遵守的规范，如 code-review-checklist、git-commit-standards。这些 Skills 必须提交到项目 Git 仓库，确保所有成员使用同一套标准。

   • 个人级 Skills (~/.claude/skills/)：存放个人工作习惯、快捷键偏好等，不应提交到团队仓库，避免与团队规范冲突。

5. 执行自动化

   • 在理想状态下，Claude 会根据 Skill 的 description 自动识别场景并应用相应规则。例如，当用户提出“帮我审查这段代码”时，Claude 会自动加载 code-review-checklist Skill。

   • 用户也可通过“请使用 [技能名称] skill”等指令，强制 Claude 按既定规范执行。

**6.3 团队知识固化：**claude.md 与经验回流

CLAUDE.md 是团队协作的“项目宪法”和“唯一准则”。其核心作用是持续积累和固化团队在协作过程中达成的共识与修正。

1. 共同维护：CLAUDE.md 应提交到版本控制系统，由全团队共同维护。任何成员发现 Claude 对项目规则理解有误或提出优化建议时，都应更新此文件。

2. 让 AI 自我更新：当纠正 Claude 的错误后，应提示它 “Update your claude.md, so you don‘t make that mistake again.” 让 AI 自己将教训编写成规则写回文件，此方式生成的规则通常更精确、更符合 AI 的认知模式，效果优于人工直接编写。

3. 项目级 Skills 作为扩展：将成熟的、可复用的工作流程（如 TDD 流程、上线检查清单）封装成项目级 Skill，作为对 CLAUDE.md 的补充和具体化。

6.4 连接管理与权限控制

高效的团队协作需要连接众多外部服务（如 Git、Figma、Slack），但必须精细化管理以保障安全和性能。

1. MCP 连接管理（上下文窗口保护）

   • 黄金法则：上下文窗口是稀缺资源。可以配置多个 MCP 服务器，但单个项目同时启用的数量应少于10个，保持活跃工具总数在80个以下。

   • 按需启用：不要在全局或所有项目中启用全部 MCP。在项目配置文件（settings.json）中，使用 disabledMcpServers 字段禁用当前项目不需要的 MCP 连接器。

   • 流程化集成：将跨工具的工作流标准化。例如，设计交接流程：Figma MCP（导出资产）-> Google Drive MCP（上传）-> Linear MCP（创建开发任务）-> Slack MCP（通知团队）。

2. 安全沟通策略（适用于接入聊天平台的场景，如飞书/Slack机器人）

   • 私聊策略：严禁使用 all**（允许所有人私聊）**。推荐采用以下安全策略：

     • pairing （配对，推荐）：用户需先私聊机器人发送申请码，管理员批准后（命令：openclaw pairing approve - <channel> <CODE>）方可对话。

     • allowlist （白名单）：仅允许预先加入名单的用户私聊。

   • 群聊策略：在任何群聊中，必须强制开启 requireMention，确保机器人只在被@时才会响应，避免在群聊中无差别回复造成干扰或信息泄露。同时，应配置群聊白名单，仅将机器人添加到必要的协作群组。

6.5 高效协作实践技巧

1. 最大化并行处理：

   • 使用 Git Worktrees：为不同的功能分支创建独立的工作树，实现物理隔离的并行开发环境。

   • 多实例操作：在安全的情况下，多开终端窗口运行多个 Claude Code 实例处理独立任务。

2. 交叉审核与质量内建：

   • 在规划阶段（Plan Mode），可使用两个 Claude 实例交叉审核计划，一个负责编写，另一个负责审查，以规避单一视角的盲区。

   • 赋予执行 Agent 质量门禁责任，明确指令：“代码必须通过你的审查后才能提交或创建 PR”，让 AI 在开发过程中自行进行一轮质量过滤。

3. 敢于中断与重定向：

   • 如果 Agent Teams 或 Subagent 的执行明显偏离预期，应立即使用主会话中断并重塑指令，或切回 Plan Mode 重新规划，而非在错误的方向上反复修补。

---

七、学习资源

收集了不少学习claude code的资源，之前一直放在收藏中吃灰，也趁机梳理下，分享下

7.1 官方核心资源

Claude Code官方文档

• 总览与入门： https://docs.claude.com/en/docs/claude-code/overview

• 设置指南： https://docs.anthropic.com/en/docs/claude-code/setup

• 快速入门： https://docs.anthropic.com/en/docs/claude-code/quickstart

• 最佳实践： https://www.anthropic.com/engineering/claude-code-best-practices

核心功能文档

• MCP（模型上下文协议）： https://docs.anthropic.com/en/docs/claude-code/mcp

• 命令行参考： https://docs.anthropic.com/en/docs/claude-code/cli-reference

• 设置： https://docs.anthropic.com/en/docs/claude-code/settings

• 钩子指南： https://code.claude.com/docs/en/hooks-guide

GitHub官方仓库

• 核心项目仓库： https://github.com/anthropics/claude-code

• 官方Skills仓库： https://github.com/anthropics/skills/tree/main

7.2 第三方社区与开源配置

• “Everything Claude Code”：Anthropic黑客松冠军推出的完整配置体系

  • 特点：经过10个月高强度使用和真实产品打磨

  • 效果：功能完成速度提升65%，代码审查问题减少75%，测试覆盖率提升34%

  • 构成：Agents、Hooks、Rules、Commands、Skills和MCP Configs的组合

• Awesome Claude Code： https://github.com/hesreallyhim/awesome-claude-code

• Awesome Claude Skills： https://github.com/travisvn/awesome-claude-skills

7.3 中文学习平台

Learn OpenCode（强烈推荐）

• 网址： https://learnopencode.com/

• 特点：

  1. 中文友好：结构化中文讲解，非简单机翻

  2. 国内网络友好：无需科学上网

  3. 支持国产模型：智谱、DeepSeek、MiniMax等

  4. 完全免费开源：课程和工具开源

• 内容结构：“OpenCode是什么”、“核心概念”、“常用用法”、"配置与实践"等模块

• 目标用户：想系统了解OpenCode、希望降低英文文档阅读负担的国内开发者

7.4 相关开源项目

OpenViking

• 项目地址： https://github.com/volcengine/OpenViking

• 开发方：字节跳动火山引擎

• 核心思路：采用文件系统范式管理AI Agent上下文

• 官方定义：“极简上下文交互范式”

• 优势：无需理解复杂的向量数据库操作，像管理本地文件一样管理AI记忆

7.5 关键技巧点

• Git版本控制（首要原则）

  • 铁律：AI重构前必须先提交当前稳定状态

  • 高频提交：每10-15分钟提交一次

  • 回滚策略：AI连续修复3次未果 → 立即回滚重来

• 工作流优化技巧

  • 规划模式：按Shift+Tab让AI先输出实施计划

  • 分段工作：明确告诉AI"只实现第X部分"

  • 提示工程：拒绝"超级提示词"，建立提示词链

  • 多智能体：采用PM+架构师+开发多角色协作