Back to Details

claude-code-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Code Best Practices

Claude Code 最佳实践

Guidance for using Claude Code effectively and understanding its design philosophy, based on insights from Boris Cherny, the creator of Claude Code.
关于有效使用 Claude Code 并理解其设计理念的指导，内容基于 Claude Code 创作者 Boris Cherny 的洞见。

Core Philosophy

核心理念

Build for T+6 Months

面向 T+6 个月构建

Design and configure for the model six months from now, not today's limitations:
  • Avoid over-engineering workarounds for current model weaknesses
  • Expect model improvements to obsolete most scaffolding code
  • Treat compensatory instructions in CLAUDE.md as temporary
应针对六个月后的模型进行设计和配置，而不是受限于当前模型的能力：
  • 避免针对当前模型弱点过度设计变通方案
  • 预计模型改进会使大多数 Scaffolding 代码失去必要性
  • 将 CLAUDE.md 中用于弥补模型能力不足的指令视为临时措施

Blatant Demand Principle

显性需求原则（Blatant Demand）

Only optimize behaviors users already perform:
  • Observe what you do manually and repeatedly
  • Make existing workflows easier, don't invent new ones
  • If you're not already doing something manually, Claude Code won't magically make you do it
只优化用户已经在执行的行为：
  • 观察你反复手动执行的操作
  • 让现有工作流更轻松，不要发明新的工作流
  • 如果某件事不是你已经在手动做的，Claude Code 也不会神奇地促使你去做

Scaffolding is Tech Debt

Scaffolding 就是技术债

All code and configuration compensating for model limitations is temporary:
  • Expect to delete or rewrite within 6 months
  • Don't over-invest in workarounds
  • Model improvements typically provide 10-20% gains that obsolete previous scaffolding
所有用于弥补模型能力限制的代码和配置都是临时性的：
  • 预计在 6 个月内就会被删除或重写
  • 不要在变通方案上投入过多
  • 模型改进通常能带来 10%-20% 的提升，从而让之前的 Scaffolding 失去价值

CLAUDE.md Configuration

CLAUDE.md 配置

Keep It Minimal

保持精简

markdown
undefined
markdown
undefined

Project: [Name]

Project: [Name]

Context

Context

[One paragraph describing what this project does]
[One paragraph describing what this project does]

Key Patterns

Key Patterns

  • [Pattern 1]: [Brief explanation]
  • [Pattern 2]: [Brief explanation]
  • [Pattern 1]: [Brief explanation]
  • [Pattern 2]: [Brief explanation]

Preventable Mistakes

Preventable Mistakes

  • [Mistake to avoid]
  • [Another mistake to avoid]
  • [Mistake to avoid]
  • [Another mistake to avoid]

Commands

Commands

  • Build: 
    [command]
  • Test: 
    [command]
  • Deploy: 
    [command]
undefined
  • Build: 
    [command]
  • Test: 
    [command]
  • Deploy: 
    [command]
undefined

When to Delete and Start Fresh

何时删除并重新开始

Delete CLAUDE.md and restart when:
  • File exceeds ~500 lines
  • Instructions contradict each other
  • Many instructions address obsolete model limitations
  • You notice Claude ignoring parts of the file
出现以下情况时，删除 CLAUDE.md 并重新开始：
  • 文件超过约 500 行
  • 指令相互矛盾
  • 许多指令针对的是已经过时的模型能力限制
  • 你发现 Claude 忽略文件中的部分内容

What to Add Immediately

立即添加的内容

Add to CLAUDE.md when you notice:
  • Repeated mistakes in PR reviews
  • Project-specific conventions Claude keeps missing
  • Build or test commands that require explanation
发现以下情况时，将相关内容添加到 CLAUDE.md：
  • PR 审查中反复出现的错误
  • Claude 经常遗漏的项目特定约定
  • 需要额外说明的构建或测试命令

What to Avoid

应避免的内容

Do not add:
  • General coding best practices (Claude already knows these)
  • Verbose explanations of obvious patterns
  • Instructions for problems that newer models handle automatically
不要添加：
  • 通用编码最佳实践（Claude 已经了解这些）
  • 对显而易见模式的冗长解释
  • 针对较新模型可自动处理问题的指令

Plan Mode

Plan Mode

What It Is

它是什么

Plan mode is a single prompt instruction that prevents Claude from writing code immediately:
Please think through this problem step by step without writing code yet.
Plan Mode 是通过一条提示指令阻止 Claude 立即编写代码：
Please think through this problem step by step without writing code yet.

When to Use Plan Mode

何时使用 Plan Mode

Use for approximately 80% of sessions, especially:
  • Complex tasks with multiple components
  • Tasks requiring architectural decisions
  • Debugging sessions where root cause is unclear
  • Unfamiliar codebases or domains
约 80% 的会话都应使用，尤其是：
  • 涉及多个组件的复杂任务
  • 需要作出架构决策的任务
  • 根因尚不明确的调试会话
  • 陌生的代码库或领域

When to Skip Plan Mode

何时跳过 Plan Mode

Skip for:
  • Trivial changes (typo fixes, simple renames)
  • Well-defined tasks with clear implementation
  • Follow-up work where plan already exists
以下情况可以跳过：
  • 琐碎变更（拼写修正、简单重命名）
  • 定义明确且实现路径清晰的任务
  • 已有计划的后续工作

Implementing Automatic Plan Mode

自动启用 Plan Mode

Add to CLAUDE.md for complex projects:
markdown
undefined
对于复杂项目，将以下内容添加到 CLAUDE.md：
markdown
undefined

Default Behavior

Default Behavior

For any task involving more than a single file change, start by outlining the approach before writing code.
undefined
For any task involving more than a single file change, start by outlining the approach before writing code.
undefined

Sub-Agent Workflows

Sub-Agent 工作流

Calibrating Agent Count

校准 Agent 数量

Match parallelism to task difficulty:
Task TypeAgentsExample
Simple lookup1"What does this function do?"
Moderate research3-5"Find all usages of this API"
Complex debugging5-10"Why is this test flaky?"
Broad codebase analysis10+"Audit all authentication flows"
让并行程度与任务难度相匹配：
任务类型Agent 数量示例
简单查询1“这个函数有什么作用？”
中等程度调研3-5“找出这个 API 的所有使用位置”
复杂调试5-10“为什么这个测试会偶发失败？”
全面代码库分析10+“审查所有身份验证流程”

Uncorrelated Context Windows

互不相关的上下文窗口

Sub-agents provide value through fresh, independent context:
  • Each agent starts without pollution from other agents' reasoning
  • Enables parallel exploration of different hypotheses
  • Reduces anchoring bias from early incorrect conclusions
Sub-Agent 通过提供独立且不受干扰的上下文来创造价值：
  • 每个 Agent 启动时都不会受到其他 Agent 推理过程的干扰
  • 支持并行探索不同假设
  • 减少因早期错误结论产生的锚定偏差

Prompting Sub-Agents

提示 Sub-Agent

The parent Claude instance (Mama Claude) spawns sub-agents with specific, focused prompts:
Investigate whether the database connection pool is exhausted during peak load.
Focus only on connection lifecycle and pool configuration.
Report findings without implementing fixes.
父级 Claude 实例（Mama Claude）会使用具体且聚焦的提示来派生 Sub-Agent：
Investigate whether the database connection pool is exhausted during peak load.
Focus only on connection lifecycle and pool configuration.
Report findings without implementing fixes.

Productivity Patterns

效率提升模式

Observed Gains

观察到的提升

Anthropic engineers report 150% productivity improvement - unprecedented compared to typical developer tooling improvements of 2%.
Anthropic 工程师报告称生产力提升了 150%——相比开发者工具通常约 2% 的提升，这一增幅前所未有。

Maximizing Effectiveness

最大化效果

  1. Start sessions with context: Brief project description before diving into tasks
  2. Iterate rapidly: Prototype 20 variations quickly instead of 3 polished ones
  3. Let Claude explore: Remove barriers rather than constraining to predefined APIs
  4. Review output critically: Productivity gains come from faster iteration, not blind acceptance
  1. 以上下文开启会话：投入任务前先简要介绍项目
  2. 快速迭代：快速制作 20 个变体，而不是精雕细琢 3 个版本
  3. 让 Claude 探索：消除障碍，而不是将其限制在预定义的 API 中
  4. 批判性审查输出：生产力提升源于更快迭代，而不是盲目接受结果

Common Anti-Patterns

常见反模式

Avoid these behaviors that reduce effectiveness:
  • Over-specifying implementation details in prompts
  • Interrupting Claude mid-task with corrections
  • Accumulating stale instructions in CLAUDE.md
  • Fighting the model instead of working with its tendencies
避免以下会降低效果的行为：
  • 在提示中过度指定实现细节
  • 在 Claude 执行任务途中通过纠正不断打断它
  • 在 CLAUDE.md 中不断堆积陈旧指令
  • 与模型的倾向对抗，而不是顺应其工作方式

Building AI Coding Tools

构建 AI 编程工具

Product Overhang

产品外延（Product Overhang）

Model capabilities often exist before products harness them:
  • Observe what the model tries to do naturally
  • Remove barriers to those behaviors
  • Build interfaces that expose existing capabilities
模型往往先具备某项能力，而产品尚未提供接口来利用它：
  • 观察模型自然而然会尝试做什么
  • 消除这些行为面临的障碍
  • 构建能够呈现现有能力的界面

The Bitter Lesson Applied

应用“苦涩的教训”（The Bitter Lesson）

More general approaches beat specialized ones:
  • Don't over-engineer for specific edge cases
  • Trust model improvements to handle current weaknesses
  • Avoid betting against improving model capabilities
更通用的方法胜过专门化的方法：
  • 不要针对特定边缘情况过度设计
  • 相信模型改进能够处理当前弱点
  • 不要押注模型能力不会继续提升

Rapid Prototyping

快速原型

When building features:
  1. Build minimal version in hours, not days
  2. Get to users immediately
  3. Observe actual usage patterns
  4. Iterate based on real feedback
Example: Plan mode shipped in 30 minutes after observing user patterns.
构建功能时：
  1. 用几小时而不是几天做出最小版本
  2. 尽快让用户用起来
  3. 观察实际使用模式
  4. 根据真实反馈迭代
例如：在观察到用户使用模式后，Plan Mode 仅用 30 分钟便完成发布。

Workflow: Starting a New Coding Session

工作流：开启新的编程会话

  1. Assess task complexity
    • Trivial: Skip to step 4
    • Moderate to complex: Continue to step 2
  2. Enter plan mode
    • Describe the task clearly
    • Ask Claude to outline approach before coding
    • Review and refine the plan
  3. Decide on parallelism
    • Single-focus task: Proceed with one context
    • Research/debugging: Spawn appropriate sub-agents
  4. Execute with iteration
    • Let Claude work through the plan
    • Provide feedback on output
    • Iterate until complete
  5. Capture learnings
    • Add preventable mistakes to CLAUDE.md
    • Remove obsolete instructions
    • Note patterns for future sessions
  1. 评估任务复杂度
    • 琐碎：跳至第 4 步
    • 中等到复杂：继续第 2 步
  2. 进入 Plan Mode
    • 清晰描述任务
    • 要求 Claude 在编码前概述方案
    • 审查并完善计划
  3. 决定是否并行
    • 单一焦点任务：在一个上下文中继续推进
    • 研究或调试：派生数量适当的 Sub-Agent
  4. 迭代执行
    • 让 Claude 按计划推进工作
    • 对输出提供反馈
    • 持续迭代直至完成
  5. 沉淀经验
    • 将可预防的错误添加到 CLAUDE.md
    • 删除过时指令
    • 记录可供未来会话参考的模式

Workflow: Maintaining CLAUDE.md

工作流：维护 CLAUDE.md

  1. Weekly review
    • Scan for instructions no longer needed
    • Check for contradictions
    • Verify commands are current
  2. Post-PR review
    • Add any repeated mistakes immediately
    • Update patterns that Claude missed
  3. Monthly reset evaluation
    • If file exceeds 500 lines, consider fresh start
    • Archive old version for reference
    • Rebuild with only essential instructions
  1. 每周审查
    • 检查是否还有不再需要的指令
    • 检查是否存在矛盾
    • 确认命令是否仍为最新
  2. PR 审查后
    • 立即补充任何反复出现的错误
    • 更新 Claude 容易遗漏的约定
  3. 每月重置评估
    • 如果文件超过 500 行，考虑重新开始
    • 归档旧版本以供参考
    • 仅保留必要指令重新构建

Key Predictions and Context

关键预测与背景

Based on Claude Code's development trajectory:
  • Terminal interface continues to work despite being "accidental"
  • GUI versions (Claude Code Work) extend capability to non-technical users
  • Expect significant capability improvements every 3-6 months
  • Most valuable engineering skills shifting to product sense and user research
基于 Claude Code 的发展轨迹：
  • 尽管终端界面是“偶然”产物，但它仍会继续可用
  • GUI 版本（Claude Code Work）将把能力扩展到非技术用户
  • 预计每 3-6 个月都会有显著的能力提升
  • 最有价值的工程技能正转向产品思维和用户研究