Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems while you watch, redirect, or step away entirely. This changes how you work: instead of writing code yourself and asking Claude to review it, you describe what you want and Claude figures out how to build it.
Claude Code 是一个 Agentic 编程环境。不像聊天机器人那样回答问题然后等待，Claude Code 可以读取你的文件、运行命令、做出修改，在你观看、纠正或离开时自主解决问题。这改变了你的工作方式：不是自己写代码然后让 Claude 审查，而是描述你想要什么，Claude 自己想办法实现。
这段话定义了"Agentic 编程"的核心范式转变——从"人写代码、AI 辅助"到"人描述意图、AI 实现"。Claude Code 不是 Copilot 那种补全工具，而是一个能独立工作的工程师。关键区别在于"自主性"：它能探索代码库、规划方案、编写代码、运行测试、修复 bug——整个闭环不需要人类干预。这篇最佳实践适用于所有 Agentic 编码工具（包括 Cursor、Windsurf 等），核心原则是通用的。
Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens. When context is getting full, Claude may start "forgetting" earlier instructions or making more mistakes.
大多数最佳实践基于一个核心约束：Claude 的上下文窗口会快速填满，性能随填满而下降。一次调试或代码探索可能消耗数万 token。当上下文接近满时，Claude 可能开始"忘记"早期指令或犯更多错误。
上下文窗口是 Agentic 编码的第一性原理。所有技巧都围绕这一点展开——怎么让有限的上下文空间装下最有价值的信息。记住：上下文里每多一个不相关文件的内容，Claude 对你真正关心的问题的注意力就少一分。这就像人类工程师——同时看太多文件会分散注意力。策略：频繁清理（/clear）、用子代理分担探索（不污染主上下文）、保持会话聚焦。
Claude stops when the work looks done. Without a check it can run, "looks done" is the only signal available. Give Claude something that produces a pass or fail—tests, a build, a screenshot to compare—and the loop closes on its own. Claude does the work, runs the check, reads the result, and iterates until the check passes.
Claude 在工作"看起来完成"时就停。没有可运行的检查，"看起来完成"是唯一的信号——你变成了验证环节。给 Claude 一个能产生通过/失败结果的检查——测试、构建、截图对比——闭环就自动闭合了。Claude 做工作、运行检查、读取结果、迭代直到通过。
Evidence over assertions: Have Claude show the test output, the command it ran and what it returned, or a screenshot. Reviewing evidence is faster than re-running verification yourself.
证据胜于断言：让 Claude 展示测试输出、运行的命令及其返回值、或截图。审查证据比自己重新验证更快。
这是让 Agentic 编码从"需要盯着"变成"可以离开"的关键。没有自动化验证 = 你就是验证环节 = 你无法离开。好的验证手段：①测试套件（最理想） ②构建/lint 通过 ③截图对比（UI 任务）。更好的是，Claude Code 支持 /goal 条件和 Stop Hook——让验证变成确定性门控，不依赖 Claude 自己判断"看起来好了"。
Letting Claude jump straight to coding can produce code that solves the wrong problem. Use plan mode to separate exploration from execution. Four phases: (1) Explore—read files, understand; (2) Plan—create detailed implementation plan; (3) Implement—code against the plan; (4) Commit—descriptive message and PR.
让 Claude 直接开始编码可能产生解决错误问题的代码。使用 plan 模式将探索和执行分离。四个阶段：（1）探索——读文件、理解问题；（2）规划——创建详细实现计划；（3）实现——按计划编码；（4）提交——描述性消息和 PR。
Plan mode is useful, but also adds overhead. For tasks where the scope is clear and the fix is small, ask Claude directly. Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code. If you could describe the diff in one sentence, skip the plan.
Plan 模式有用但也有开销。范围清晰、修改小的任务可以直接做。规划在不确定方法、修改涉及多文件、或不熟悉代码时最有用。如果你能用一句话描述改动，跳过规划。
"探索 → 规划 → 实现 → 提交"四步法是 Agentic 编码的黄金工作流。核心洞察：把"理解问题"和"解决问题"分开。在 plan 模式中 Claude 只读不写，避免在理解不充分时就匆忙修改代码。对于复杂任务，先让 Claude 读完相关代码、制定方案、你审核方案后再执行——这比让它直接干要好得多。对于简单任务（改错字、加日志），直接做。
The more precise your instructions, the fewer corrections you'll need. Strategies: Scope the task (specify file, scenario, testing preferences); Point to sources (direct Claude to git history, relevant code); Reference existing patterns (point to patterns in your codebase); Describe the symptom (provide symptom, likely location, what "fixed" looks like).
指令越精确，需要的修正越少。策略：限定范围（指定文件、场景、测试偏好）；指向来源（让 Claude 看 git 历史、相关代码）；引用现有模式（指向代码库中的范例）；描述症状（提供症状、可能位置、"修复后"的样子）。
Use @ to reference files instead of describing where code lives. Paste images directly. Give URLs for documentation. Pipe in data with cat error.log | claude. Let Claude fetch what it needs using Bash commands, MCP tools, or reading files.
用 @ 引用文件而非描述代码位置。直接粘贴图片。给出文档 URL。用 cat error.log | claude 管道传入数据。让 Claude 用 Bash、MCP 工具或读文件来自己获取所需信息。
CLAUDE.md is read at the start of every conversation. Include Bash commands, code style, and workflow rules. Keep it concise—for each line, ask: "Would removing this cause Claude to make mistakes?" If not, cut it. Bloated CLAUDE.md files cause Claude to ignore actual instructions!
CLAUDE.md 在每次对话开始时被读取。包含 Bash 命令、代码风格、工作流规则。保持精炼——对每一行问："删掉这行会让 Claude 犯错吗？"如果不会，删掉。臃肿的 CLAUDE.md 会让 Claude 忽略真正的指令！
✅ 应包含：Claude 猜不到的 Bash 命令、与默认不同的代码风格、测试说明、PR 规范、架构决策、环境怪癖、常见陷阱
❌ 不应包含：Claude 能从代码推断的信息、标准语言惯例、详细 API 文档（链接代替）、频繁变化的信息、逐文件描述、"写干净代码"这种废话
CLAUDE.md 就是给 AI 的"项目说明书"。最大的错误是写太多——当 Claude 的上下文被 CLAUDE.md 占满时，真正重要的规则反而被淹没。铁律：只写"Claude 不从代码中读出来的信息"。如果 Claude 已经做对了，不需要写规则。另一个关键点：CLAUDE.md 可以用 @path/to/file 导入其他文件，实现模块化配置。这和 Hermes 的 skill 系统是同样的设计理念。
Three ways to reduce interruptions: Auto mode (classifier reviews commands, blocks risky ones), Permission allowlists (permit specific safe tools like npm run lint), Sandboxing (OS-level isolation restricting filesystem and network access).
减少中断的三种方式：自动模式（分类器审查命令、阻止高风险操作）、权限白名单（允许特定安全工具如 npm run lint）、沙箱（操作系统级隔离，限制文件系统和网络访问）。
• CLI 工具：安装 gh、aws 等让 Claude 直接与外部服务交互
• MCP 服务器：连接 Notion、Figma、数据库等外部工具
• Hooks：确定性执行的脚本——不依赖 Claude 自觉，保证每次都执行（如编辑后自动 lint）
• Skills：领域知识和可复用工作流，Claude 按需加载
• 子代理：独立上下文窗口的专门助手（如安全审查员）
Hooks 和 Skills 的区分很关键：CLAUDE.md 是建议性的，Hooks 是确定性的。如果你绝对需要某个操作每次都发生（比如"每次编辑后运行 ESLint"），用 Hook 而不是写在 CLAUDE.md 里。同样，Skills 适合"偶尔需要"的领域知识——它们不占每次对话的上下文，只在相关时按需加载。这种设计哲学和 Hermes 的 skills 系统完全一致。
When onboarding to a new codebase, ask Claude questions you'd ask another engineer: How does logging work? How do I make a new API endpoint? What edge cases does CustomerOnboardingFlowImpl handle? Why does this code call foo() instead of bar()?
入职新代码库时，向 Claude 提问你会问另一位工程师的问题：日志怎么工作？怎么建新的 API 端点？CustomerOnboardingFlowImpl 处理了哪些边界情况？为什么这里调 foo() 而不是 bar()？
For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you about technical implementation, UI/UX, edge cases, and tradeoffs. Keep interviewing until everything is covered, then write a complete spec to SPEC.md.
对于较大的功能，先让 Claude 采访你。从一个最小化的提示开始，让 Claude 就技术实现、UI/UX、边界情况和权衡进行提问。持续采访直到覆盖所有内容，然后写一份完整规格说明到 SPEC.md。
"让 AI 采访你"是一个非常实用的技巧——把需求定义的负担从人转移到 AI。人会遗漏边界情况，但 AI 受过训练知道该问什么。流程：最小提示 → AI 提问 → 你回答 → AI 追问 → 生成 SPEC.md → 新会话执行。为什么要新会话？因为采访过程会消耗大量上下文，而执行时不需要这些对话——干净的上下文专注于实现。
The best results come from tight feedback loops. Correct Claude as soon as you notice it going off track. If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh with a better prompt. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.
最佳结果来自紧密反馈循环。一旦发现 Claude 偏离方向就立即纠正。如果在同一会话中对同一问题纠正了两次以上，上下文已被失败方案污染。运行 /clear 并用更好的提示重新开始。干净会话 + 更好提示 几乎总是优于 冗长会话 + 累积纠正。
这是 Agentic 编码中最重要的元规则：/clear 是你最好的朋友。很多新手以为"更多上下文 = 更好"，但对 LLM 来说更多上下文 = 更多噪音 = 更差表现。特别是在纠正 Claude 时——每次失败的尝试都留下"痕迹"，Claude 可能被之前的错误方案干扰。两次纠正不行就重来——这不是放弃，而是把学到的教训融入到更精确的新提示中。
Since context is your fundamental constraint, subagents are one of the most powerful tools. When Claude researches a codebase it reads lots of files, consuming your context. Subagents run in separate context windows and report back summaries. Use them for investigation and verification after implementation.
上下文是根本约束，因此子代理是最强大的工具之一。Claude 研究代码库时会读大量文件，消耗你的上下文。子代理在独立上下文窗口中运行，只返回摘要。用于代码调查和实现后的验证。
Every prompt creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint. Instead of carefully planning every move, tell Claude to try something risky—if it doesn't work, rewind. Checkpoints persist across sessions.
每次提示都会创建检查点。你可以恢复对话、代码或两者到任何检查点。不必精心计划每一步——让 Claude 尝试有风险的操作，不行就回退。检查点跨会话持久化。
Use claude -p "prompt" in CI, pre-commit hooks, or scripts. Add --output-format stream-json for streaming JSON output. This is how you integrate Claude into automated workflows.
在 CI、pre-commit 钩子或脚本中使用 claude -p "prompt"。加 --output-format stream-json 获取流式 JSON 输出。这就是将 Claude 集成到自动化工作流的方式。
Claude Code scales horizontally. Use worktrees for isolated git checkouts, or the desktop app for visual session management. A fresh context improves code review since Claude won't be biased toward code it just wrote. Writer/Reviewer pattern: Session A implements, Session B reviews.
Claude Code 可以水平扩展。用 worktree 做隔离的 git 检出，或用桌面应用做可视化会话管理。新鲜上下文改善代码审查——因为 Claude 不会偏袒自己刚写的代码。写手/审查者模式：会话 A 实现，会话 B 审查。
Writer/Reviewer 模式是 Agentic 编码的高阶技巧：写代码的 AI 和审查代码的 AI 必须是不同会话。原因：同一个会话中的 Claude 对自己刚写的代码有"确认偏误"——它会倾向于认为自己的实现是对的。但在新鲜上下文中，审查者 Claude 不知道实现者的推理过程，只看到代码和需求——这更接近真正的代码审查。甚至可以进一步：一个会话写测试，另一个写实现代码来通过测试。
For large migrations, distribute work across parallel invocations: Have Claude list all files that need migrating, write a script to loop through and call claude -p for each, test on a few files first then run at scale. Use --allowedTools to restrict permissions for batch operations.
大规模迁移时，将工作分配到并行调用中：让 Claude 列出所有需迁移的文件，写脚本循环调用 claude -p，先测试几个文件再大规模运行。用 --allowedTools 限制批量操作的权限。
• 大杂烩会话：在同一个会话中做不相关的任务 → /clear 分隔
• 反复纠正：纠两次还不对就重来，别在同一上下文死磕
• 过度膨胀的 CLAUDE.md：太长 → Claude 忽略一半规则
• 信任但不验证：Claude 产出看起来合理但没处理边界情况 → 始终提供验证手段
• 无限探索：让 Claude "调查"而不限定范围 → 上下文被文件读取塞满
这 5 个失败模式几乎覆盖了所有 Agentic 编码的常见坑。最常见的是"反复纠正"——用户在同一个会话中反复纠正 Claude，上下文越来越脏，Claude 表现越来越差，陷入恶性循环。解决方案只有两个：①/clear 重来 ②把纠正过的教训写进新提示。记住：两次纠正不行 = 上下文已废。另一个关键陷阱是"信任但不验证"——Claude 的输出看起来总是很合理，但"看起来合理"不等于"正确"。没有自动化验证的 Agentic 编码等于盲飞。
The patterns in this guide aren't set in stone—they're starting points that work well in general. Sometimes you should let context accumulate because you're deep in one complex problem. Sometimes you should skip planning. Sometimes a vague prompt is exactly right because you want to see how Claude interprets the problem before constraining it. Pay attention to what works. Over time, you'll develop intuition that no guide can capture.
本指南中的模式不是金科玉律——它们是一般情况下有效的起点。有时候你应该让上下文积累，因为你正深入一个复杂问题；有时候应该跳过规划；有时候模糊的提示恰好正确——因为你想在约束之前看看 Claude 如何理解问题。注意什么有效。随着时间推移，你会发展出任何指南都无法替代的直觉。
最后这段是全文的哲学总结：所有最佳实践都有适用场景，没有万能公式。真正的高手不是记住所有规则，而是理解每条规则背后的原因，然后根据具体情况灵活运用。上下文管理是核心约束——理解了这一点，其他所有规则都是这个约束的推论。Agentic 编码是一种新的人机协作模式，需要全新的直觉。最好的学习方式就是大量实践、注意什么有效、持续调整。