1. 执行摘要

在分析了 12 个详细来源后，包括个人经验、Anthropic 官方指导以及社区见解，总结出三个关键要点：

核心要点

1. 上下文管理至关重要：最成功的 Claude Code 用户会通过 CLAUDE.md 文件、积极使用 /clear 命令、文档系统（开发文档、活文档计划）以及高效的工具设计来精心管理上下文。上下文退化是主要的失败模式。

2. 实施前的规划不可协商：每一个高质量的信息来源都强调在编码之前进行前期规划（Planning Mode 规划模式、书面计划、架构审查）。"凭感觉编码"可能适用于一次性的最小可行产品（MVP），但生产代码需要结构化思考、验证和文档记录。

3. 简单胜过复杂：最有效的工作流程避免过度工程化。简单的控制循环优于多智能体系统。低级工具（Bash、Read、Edit）加上选择性的高级抽象优于重量级的 RAG（检索增强生成）或复杂框架。大语言模型（LLM）是脆弱的，额外的复杂性会使调试难度呈指数级增长。

总字数：4,987 词

阅读时间：约 25 分钟（但本文更适合作为参考手册而非从头到尾阅读）

---

2. 信息来源

以下来源被用于创建这份综合指南：

| 标题 | 作者 | 发布日期 |

|------|------|----------|

| 6 Weeks of Claude Code（使用 Claude Code 的六周） | Puzzmo Blog | 2025-07-29 |

| Claude Code Best Practices（Claude Code 最佳实践） | @AnthropicAI | 官方文档 |

| Claude Code Is All You Need（你只需要 Claude Code） | 社区贡献 | 2025 |

| Getting Good Results from Claude Code（从 Claude Code 获得良好结果） | Chris Dzombak | 2025-08-08 |

| How Anthropic teams use Claude Code（Anthropic 团队如何使用 Claude Code） | @AnthropicAI | 官方文档 |

| The ULTIMATE AI Coding Guide for Developers（开发者终极 AI 编码指南） | Sabrina Ramonov | 2025-07-05 |

| 其他社区贡献与实践分享 | 多位贡献者 | 2025 年 |

---

3. 通用软件工程最佳实践

虽然这些不是 AI 编码特有的传统软件工程最佳实践，但在使用 AI 时变得更加关键，原因如下：

- 自主系统中的错误复合速度更快

- 当你没有编写代码时，代码审查更加困难

- 没有严格实践，技术债务会隐蔽积累

- AI 智能体缺乏人类判断力，会犯人类不会犯的错误

3.1 测试驱动开发（TDD）【高优先级】

为什么在 AI 中更重要

AI 生成的代码通常表面上"能工作"，但包含细微的错误。测试提供了唯一可靠的验证机制。

共识模式（4+ 个来源）：

1. 在实施之前编写测试

2. 确认测试失败（避免模拟实施）

3. 单独提交测试

4. 实施直到测试通过

5. 在实施过程中不要修改测试

示例工作流程：

```

qcode 指令：

"实施你的计划并确保新测试通过。

始终运行测试以确保没有破坏其他内容。

始终在新创建的文件上运行 prettier 格式化工具。

始终运行 turbo typecheck lint 进行类型检查和代码检查。"

```

3.2 持续质量门控【高优先级】

实施方式：使用钩子（Hooks）自动强制执行质量标准：

- 每次编辑后进行 TypeScript 类型检查和代码检查（Linter）

- 提交前进行构建验证

- 文件更改时执行测试

- 自动格式化（但请参见下面的注意事项）

钩子示例：

```

// Stop 钩子：在 Claude 完成响应时运行

1. 读取编辑日志以查找修改的仓库

2. 在每个受影响的仓库上运行构建脚本

3. 检查 TypeScript 错误

4. 如果错误 <5 个：向 Claude 显示错误

5. 如果错误 ≥5 个：推荐使用自动错误解决智能体

6. 记录所有内容

```

注意：自动格式化钩子可能会消耗大量上下文令牌（据报道在 3 轮中消耗了 160k）。考虑在会话之间手动格式化。

3.3 代码审查（包括 AI 自己的工作）【高优先级】

> "我相信我最终要对带有我名字的 PR（拉取请求）中的代码负责，无论它是如何生成的。" — Chris Dzombak

多层审查流程：

1. Claude 自我审查：要求 Claude 使用子智能体或新上下文审查自己的代码

2. 人工审查：手动验证行为和测试覆盖率

3. 多个 Claude 实例：让一个 Claude 编写，另一个审查（新上下文 = 更好的批评）

审查重点：

- 意大利面条式代码（难以理解的逻辑）

- 大量的 API 或后端更改

- 不必要的导入、函数、注释

- 缺失的错误处理

- 安全漏洞

3.4 增量提交与清晰的消息【高优先级】

模式：尽早、频繁地提交，并使用有意义的消息

- 使用约定式提交（Conventional Commits）格式

- 每次提交都应该能够编译并通过测试

- 避免在消息中引用"Claude"或"AI 生成"

- 在与计划或任务检查点相关的阶段提交

示例：

> "一个重要的指令是让 Claude 在每个任务步骤中编写提交。这样，Claude 或我都可以在出现问题时恢复到之前的状态。"

3.5 单体仓库架构【中等优先级】

使用 Claude Code 的六周、是什么让 CC 如此出色、我如何使用每个功能

为什么重要：单体仓库（Monorepo）在一个地方为 AI 提供全面的上下文

- 架构（Schema）、API 定义、实施都可访问

- 单个 PR 可以跨越全栈

- 减少上下文收集开销

> 来自 Puzzmo 博客的引用："单体仓库非常适合与大语言模型一起工作，因为它可以读取代表我们架构的文件，可以读取定义公共 GraphQL API 的 SDL 文件，读取每个屏幕的请求并弄清楚你想要做什么。"

---

4. Claude Code 专属最佳实践

4.1 上下文管理（最关键）

4.1.1 CLAUDE.md 文件结构【高优先级】

所有 12 个来源都提到这一点

频率：一致共识

结构最佳实践：

根目录 CLAUDE.md（最多 100-200 行）：

- 关键的通用规则

- 快速命令参考

- 测试说明

- 仓库礼仪

- 指向特定仓库文件的指针

子目录 CLAUDE.md 文件（50-100 行）：

- 项目特定的上下文

- 本地命令和特性

- 架构指针

要避免的反模式（来自《我如何使用每个功能》）：

```

不要：@-文件文档（每次运行时嵌入整个文件）

应该：关于复杂用法或 FooBarError，请参阅 path/to/docs.md

不要："永远不要使用 --foo-bar 标志"（智能体会卡住）

应该："永远不要使用 --foo-bar；而应使用 --baz"

不要：编写综合手册

应该：记录 Claude 出错的地方

```

令牌效率：

- 一个团队在他们的单体仓库中报告了 20k 基线令牌（200k 上下文的 10%）

- CLAUDE.md 总共保持在 2000 个令牌以下

- 使用 CLAUDE.md 作为"强制函数"来简化工具

4.1.2 积极清除上下文【高优先级】

如果你不使用这些、我如何使用每个功能、

规则：

- 在 60k 令牌或 30% 上下文时清除（不要等到达到限制）

- 使用 `/clear` + `/catchup` 模式进行简单重启

- 对复杂任务使用"文档并清除"

文档并清除模式：

1. 让 Claude 将进度写入 .md 文件

2. 使用 `/clear` 清除上下文

3. 启动新会话并读取 .md 文件

4. 继续工作

避免 /compact："自动压缩是不透明的、容易出错的，并且没有很好地优化。" — Shrivu Shankar

4.1.3 文档系统【高优先级】

开发文档系统（来自 设计合作伙伴）：

三文件模式：

```

~/dev/active/[任务名称]/

├── [任务名称]-plan.md   已接受的计划

├── [任务名称]-context.md  关键文件、决策

└── [任务名称]-tasks.md   工作清单

```

活文档方法（来自设计合作伙伴）：

- 在实施过程中更新计划

- 计划文档揭示变更的需求

- 每次提交前检查计划是否最新

- 使新对话能够准确地从你离开的地方继续

4.2 规划与架构

4.2.1 规划模式是强制性的【高优先级】

、如果你不使用这些、设计合作伙伴

共识：编码之前的规划对于生产工作是不可协商的

规划工作流程（从多个来源综合）：

步骤 1：初始规划

1. 进入规划模式（Planning Mode）

2. 提供高级描述 + 指向现有代码的指针

3. 让 Claude 研究并提出方法

4. 彻底审查（尽早发现误解）

步骤 2：计划验证

- 提出澄清问题

- 挑战假设

- 请求 2-3 种替代方法及其优缺点

- 使用"think"、"think hard"、"think harder"、"ultrathink"进行更深入的分析

步骤 3：文档记录

- 退出计划模式并创建开发文档

- 或使用 `/dev-docs` 斜杠命令

- 存储在版本控制的位置

步骤 4：实施

- 使用计划启动新上下文

- 分阶段实施（一次 1-2 个部分）

- 在各阶段之间进行审查

- 在进行过程中更新计划

> 来自设计合作伙伴的引用："有时，我对建议的实施不满意。在这种情况下，我不更新计划，而是告诉它为什么错了，期待它改变方法。"

4.2.2 探索、规划、编码、提交【高优先级】

、Anthropic 团队如何使用

工作流程：

1. 探索：读取相关文件、图像、URL（明确告诉它暂时不要编码）

2. 规划：使用子智能体验证细节，使用"think"模式创建计划

3. 编码：使用明确的验证步骤进行实施

4. 提交：更新 README 或更新日志，创建 PR

关键见解："步骤 #1-#2 至关重要 — 没有它们，Claude 倾向于直接跳到编码"

4.3 工具使用与自动化

4.3.1 技能系统（AI 专用）【高优先级】

我如何使用每个功能、

关键发现：技能需要自动激活才能可靠工作

问题：手动技能约 90% 的时间被忽略

解决方案：基于钩子的自动激活

自动激活模式：

UserPromptSubmit 钩子（在 Claude 看到消息之前）：

```

1. 分析提示中的关键词/意图

2. 检查哪些技能相关

3. 注入" 技能激活检查 - 使用 X 技能"

4. Claude 在阅读问题之前看到提醒

```

Stop Event 钩子（响应后）：

```

1. 分析编辑的文件

2. 检查风险模式（try-catch、数据库操作、异步）

3. 显示温和的自我检查提醒

4. 非阻塞意识

skill-rules.json 模式：

{

"backend-dev-guidelines": {

"type": "domain",

"enforcement": "suggest",

"priority": "high",

"promptTriggers": {

"keywords": ["backend", "controller", "API"],

"intentPatterns": ["(create|add).*(route|endpoint)"]

},

"fileTriggers": {

"pathPatterns": ["backend/src//*.ts"],

"contentPatterns": ["router\\."]

}

}

}

```

技能结构（Anthropic 最佳实践）：

- 主 SKILL.md：少于 500 行

- 使用资源文件进行渐进式披露

- 重组前：1,500+ 行文件

- 重组后：300-400 行主文件 + 10-11 个资源文件

- 令牌效率提高 40-60%

4.3.2 质量控制钩子【高优先级】

我如何使用每个功能、如果你不使用这些

共识钩子类型：

1. 提交时阻止钩子（主要策略）：

```

包装 Bash(git commit) 的 PreToolUse 钩子

→ 检查 /tmp/agent-pre-commit-pass 文件

→ 如果缺少则阻止提交

→ 强制"测试并修复"循环直到通过

```

2. 提示钩子（非阻塞反馈）：

```

如果检测到次优模式，提供即发即忘的指导

```

关键见解："不要在写入时阻止 — 让智能体完成其计划，然后检查最终结果"

常见钩子：

- 构建检查器（TypeScript/代码检查器错误）

- 测试运行器（确保通过测试）

- 错误处理提醒（温和的理念）

- 技能自动激活（上面已介绍）

4.3.3 简单控制循环【高优先级】

是什么让 CC 如此出色、我如何使用每个功能

> 关键见解："可调试性 >> 复杂的手工调整多智能体 lang-chain-graph-node 混合体"

Claude Code 架构：

- 一个主线程（平面消息列表）

- 最多一个分支（子智能体结果添加到主历史记录）

- 没有复杂的多智能体系统

- 大多数任务采用简单的迭代工具调用

> 引用："尽管多智能体系统风靡一时，Claude Code 只有一个主线程……我高度怀疑你的应用需要多智能体系统。"

理由：

- 每个抽象层都使调试难度呈指数级增长

- 偏离一般模型改进轨迹

- 大语言模型是脆弱的；增加的复杂性会不可预测地中断

4.4 工作流程优化

4.4.1 指令的具体性【高优先级】

、

共识：模糊的指令产生模糊的结果

不好的示例：

```

"添加一个用户设置页面"

```

好的示例：

```

"在 /settings 创建一个用户设置页面，包含：

- 个人资料部分（姓名、电子邮件、头像上传）

- 通知偏好（电子邮件/推送的复选框）

- 使用现有的 UserProfile 组件模式

- 遵循 MUI v7 布局网格系统

- 为表单验证添加测试"

```

> 引用："Claude 可以推断意图，但不能读心术。具体性导致与期望更好的对齐。"

4.4.2 视觉参考【高优先级】

、海报制作示例

方法：

- 粘贴截图（macOS：cmd+ctrl+shift+4 → ctrl+v）

- 拖放图像

- 提供图像文件路径

- 设计模型作为 UI 参考

迭代模式：

```

1. 给 Claude 视觉模型

2. 用代码实施

3. 截取结果截图

4. 与模型比较并迭代

5. 通常 2-3 次迭代即可获得良好匹配

像人类一样，Claude 的输出往往会随着迭代而显著改善。虽然第一个版本可能不错，但经过 2-3 次迭代后，它通常看起来会好得多。

4.5 生产代码质量

4.5.1 错误处理标准【高优先级】

获得良好结果

模式：带有监控的显式错误处理

最佳实践：

javascript

// 来自终极 AI 编码指南try{awaitprismaOperation()}catch(error){//  必须：捕获到 Sentry（错误监控工具）Sentry.captureException(error)//  包括用于调试的上下文thrownewCustomError('描述性消息',{context })}

理念："快速失败并使用描述性消息。永远不要默默地吞下异常。"

4.5.2 测试标准【高优先级】

Anthropic 团队如何使用

测试清单：

1.应该参数化输入（没有魔法数字或字符串）

2.不应添加测试，除非它可能因真实缺陷而失败

3.应该确保描述与期望断言匹配

4.应该与独立期望进行比较，而不是函数输出

5.应该遵循与生产代码相同的代码检查和类型安全

6.应该表达不变量或公理（使用 fast-check 进行属性测试）

7.单元测试在 describe(functionName) 下分组

8.对可变参数使用 expect.any(...)

9.始终使用强断言（toEqual vs toBeGreaterThanOrEqual）

10.应该测试边缘情况、真实输入、边界

11.不应测试由类型检查器捕获的条件

测试类型：

单元测试：在同一目录中并置的 *.spec.ts

集成测试：与单元测试分开（不模拟数据库）

基于属性的测试：使用 fast-check进行不变量测试

5. 矛盾与权衡

5.1 技能 vs 上下文膨胀

立场 A（）：创建许多专业技能

frontend-dev-guidelines（398 行 + 10 个资源）

backend-dev-guidelines（304 行 + 11 个资源）

workflow-developer、notification-developer 等

立场 B（如果你不使用这些）：保持技能最小化

"如果它们超过 100 行，你就处于危险区域"

上下文效率至关重要

解决方案：

使用渐进式披露（主文件 <500 行 + 资源文件）

无论哪种方式，自动激活钩子都是必不可少的

令牌预算决定技能数量

测量基线上下文成本并调整

5.2 自定义子智能体 vs 克隆模式

立场 A（）：构建专业子智能体

code-architecture-reviewer（代码架构审查员）

build-error-resolver（构建错误解决器）

strategic-plan-architect（战略计划架构师）

清晰、具体的角色

立场 B（我如何使用每个功能）：避免自定义子智能体

它们限制上下文访问

它们强制人类工作流程

改用 Task(...) 生成智能体克隆

让智能体管理编排

解决方案：

两者在实践中都有效

自定义子智能体：高度专业化、狭窄的任务

克隆模式：保留上下文，更灵活

上下文可用性是决定因素

大多数用户应从克隆模式开始，仅在出现明确需求时添加专业智能体

5.3 自动格式化钩子

立场 A（最初 ）：编辑后自动格式化

无需手动干预的一致性

文件始终正确格式化

立场 B（更新建议）：不要在钩子中自动格式化

文件修改触发系统提醒

可以在 3 轮中消耗 160k 令牌

边际便利性不值得令牌成本

解决方案：

在会话之间手动运行 Prettier（代码格式化工具）

当你手动编辑文件时也进行格式化

避免为边际便利性支付令牌成本

5.4 规划模式 vs 手动计划

立场 A：使用内置的规划模式

专用模式获得更好的代码库研究

结构化的计划输出

立场 B：使用自定义提示的手动规划

规划模式看不到智能体输出

如果你说"不"而不是继续，会杀死智能体

自定义斜杠命令提供更多控制

解决方案：

从研究阶段的规划模式开始

退出并从结果创建手动开发文档

使用自定义斜杠命令进行计划细化

两全其美

5.5 文档数量

立场 A（）：广泛的文档

850+ 个 markdown 文件

多个级别（广泛架构 → 具体实施）

详细的 API 参考

立场 B（多个来源）：最小、有针对性的文档

技能用于操作方法模式

仅针对项目特定架构的文档

避免膨胀上下文

解决方案：

数量取决于代码库大小

使用技能进行可重用模式（如何构建）

使用文档进行项目特定架构（存在什么）

渐进式披露是关键

指向文档而不是嵌入

附录

A. 实践优先级总结

实践 来源数量 优先级

CLAUDE.md 文件 全部 12 个来源 高

编码前规划 8 个来源 高

上下文清除 6 个来源 高

测试驱动开发 5 个来源 高

带自动激活的技能 4 个来源 高

代码审查（自我+人工） 5 个来源 高

质量门控钩子 4 个来源 高

开发文档系统 4 个来源 高

简单控制循环 3 个来源 高

大语言模型搜索优于 RAG 2 个来源 中

Git 工作树（Worktrees） 3 个来源 中

无头模式（Headless Mode） 2 个来源 中

B. 快速入门工作流程

对于刚接触 Claude Code 并希望获得生产质量结果的工程师：

第 1 周：基础

1.创建包含项目命令和测试说明的 CLAUDE.md

2.练习规划模式 → 审查 → 实施 → 提交工作流程

3.在 60k 令牌时开始清除上下文

4.手动审查所有 AI 生成的代码

第 2 周：质量系统

1.设置测试驱动开发工作流程（先测试，单独提交）

2.为常见任务创建 2-3 个自定义斜杠命令

3.实施基本构建检查器钩子

4.将视觉参考添加到 UI 工作

第 3 周：高级上下文

1.实施开发文档系统（计划/上下文/任务文件）

2.为最常见的模式创建 1-2 个技能

3.为技能添加自动激活钩子

4.练习使用子智能体进行代码审查

第 4 周：优化

1.审核上下文使用情况（会话中期的 /context）

2.优化 CLAUDE.md（删除冗余，添加指针）

3.添加质量门控钩子（测试、代码检查）

4.尝试 git 工作树进行并行工作

C. 应避免的实践

自动格式化钩子（消耗过多令牌）

大量使用 MCP（>20k 令牌会削弱上下文）

复杂的多智能体系统（调试噩梦）

用于代码搜索的 RAG（大语言模型搜索更简单更好）

模糊的指令（导致模糊的结果）

跳过规划（直接跳到代码）

让上下文填充到限制（质量下降）

D. 成功衡量标准

上下文效率指标

基线上下文成本：<20k 令牌（200k 的 10%）

CLAUDE.md 大小：<2000 令牌

MCP 工具总计：<20k 令牌

上下文清除频率：每 60k 令牌或更少

代码质量指标

测试覆盖率：新代码 >80%

TypeScript 错误：提交前为零（由钩子强制执行）

代码审查发现：跟踪常见问题，更新 CLAUDE.md

来自 AI 代码的生产错误：应随时间减少

生产力指标

从计划到 PR 的时间：跟踪并优化

计划迭代次数：应稳定在 1-3 次

需要的上下文压缩：应随着更好的实践而减少

使用工作树的并行任务：可以同时扩展到 3-4 个

10. 结论

Claude Code 是一个强大的工具，它放大了好的和坏的实践。最成功的用户会：

1.痴迷于上下文管理— 这是主要的失败模式

2.在编码前严格规划— 凭感觉编码会产生技术债务

3.保持系统简单— 复杂性使大语言模型的调试难度呈指数级增长

4.实施质量门控— 钩子和审查可以尽早捕获错误

5.持续迭代— 根据 Claude 出错的地方完善 CLAUDE.md、技能和工作流程

挫折和生产力之间的区别不在于工具本身，而在于你如何使用它。在你的基础设施（CLAUDE.md、技能、钩子、文档）上投入时间，你将能够自信地构建生产质量的代码。