/zh/posts/claude-code-notes

Claude Code 使用心得

EN

Claude Code 最适合被当成一个 agentic development environment，而不是一个更聪明的自动补全工具。它可以读文件、运行命令、修改代码，并且在我监督的同时持续推进问题。这让它很强，但也意味着它比普通聊天机器人更需要一套有纪律的工作流。

Anthropic best practices 里对我最有价值的观点是：Claude 需要反馈闭环。如果我只说“把页面做得更好”，那我就成了唯一的验收者。如果我给它测试、截图、命令输出、约束和完成标准，它就能自己检查结果，并在交还给我之前修复失败。

1. 给 Claude 一个验证方式

验证是最有价值的习惯。Claude 能运行命令、比较输出或检查截图时，表现会比单纯猜测“是否正确”稳定得多。

对于这个博客，普通内容或样式修改应该以这个命令结束：

npm run clean && npm run build

如果修改了 JavaScript 行为，我还希望运行：

node --check themes/kaomoji-pixel/source/js/home.js

对于 UI 修改，请求里应该说明视口和需要检查的行为：

Change the mobile article layout.
Verify it at 400px wide.
The page shell must fit the viewport.
Long code blocks should scroll inside the block, not stretch the window.
Run the build after fixing it.

重点不是某一条具体命令，而是给 Claude 一个客观终点。“看起来不错”很弱。“构建通过，并且移动端代码块不再撑破窗口”就明确得多。

2. 先探索，再规划，再编码

Claude Code 修改代码很快，但改得快不等于改得对。对于不清晰的工作，我更喜欢三步节奏：

1. Explore the relevant files without editing.
2. Explain the existing behavior and propose a plan.
3. Implement only after the plan is clear.

一个好的规划提示是：

Inspect the article layout and CSS first.
Do not edit files yet.
Identify which templates, styles, and scripts are involved.
Then propose a short implementation plan and call out risks.

这在修改路由、页面外壳、音乐播放、响应式布局或部署时尤其有用。它能避免 Claude 很自信地写出一个解决错问题的 patch。

对于小改动，可以跳过规划。如果我能用一句话描述 diff，我通常会让 Claude 直接做：

Remove code block line numbers from Hexo output and keep the terminal-style copy button.
Run the build and commit the change.

关键是根据风险选择合适的流程厚度。

3. 提供具体上下文

Claude 可以推断很多东西，但精确上下文仍然能节省大量时间。我会尽量包含：

  • 可能相关的文件或目录
  • 当前症状
  • 期望行为
  • 不能改变的约束
  • 如何证明任务完成

不好的提示：

Fix the blog layout.

更好的提示：

Fix the mobile layout for /zh/posts/codex-notes/.
The code block currently overflows the window at 400px width.
Keep the desktop layout unchanged.
Do not re-add article navigation.
Run npm run clean && npm run build.

Claude 也适合处理更丰富的上下文。我可以粘贴截图、日志、URL 或具体错误输出。对于代码库引用，直接说真实文件名，比模糊描述更有效。

4. 让 CLAUDE.md 短而有用

CLAUDE.md 是项目记忆。它应该记录 Claude 无法稳定从代码里推断出来的规则：

# Workflow

- Run `npm run clean && npm run build` after content or theme changes.
- Run `node --check themes/kaomoji-pixel/source/js/home.js` after JavaScript changes.
- Commit after each completed small feature loop.
- Do not restart the audio player during local navigation.
- Keep the page shell fixed; long content scrolls inside `.window-content`.

我不希望这个文件变成一本手册。如果某一行不能阻止真实错误，它可能就应该被删掉。过长的指令文件很容易让重要规则被埋没。

对于这个项目，Codex 侧的等价物是 AGENTS.md 和 .spec/README.md。原则相同：长期规则应该进入版本化的项目说明，而不是每次都写在 prompt 里。

5. 根据可信度配置权限

Claude Code 在写文件、运行 shell 命令、调用 MCP 工具或执行其他副作用操作前，经常会请求权限。对于陌生项目这很有用，但对于可信的重复性工作会拖慢节奏。

我的实用规则是：

  • 陌生仓库使用更严格的权限
  • 个人项目可以允许已知安全的命令
  • 破坏性命令仍然手动确认
  • 工作流里的验证命令可以更自由地运行

例如，允许这些命令通常是合理的：

npm run build
npm test
git status
rg

但对于部署、凭据修改、生产数据库命令、重写 git 历史这类操作，我仍然希望它保持谨慎。

6. 用 CLI 和 MCP 获取外部上下文

Claude Code 最强的时候，是它能使用和我一样的工具。如果任务涉及 GitHub、云资源、日志或文档，CLI 往往比让 Claude 凭记忆推理更高效。

例如：

gh issue view 123
gh pr diff 456
aws logs tail /service/api --since 30m

当外部上下文会重复使用时，MCP 很有价值：issue tracker、文档、仪表盘、数据库、Figma 文件或可观测性工具都适合。但我不会默认连接所有东西。只有当 MCP 能消除一个真实的手工循环时，我才会添加它。

7. 用 Hooks 固化必须执行的规则

项目说明是建议性的，hooks 是确定性的。

如果一件事每次都必须发生，它更适合成为 hook 或脚本。例如：

  • 文件编辑后运行 formatter
  • 阻止写入生成文件
  • 修改某个 package 后运行局部 linter
  • 阻止测试失败时提交

我会先从说明开始，等工作流稳定后，再把重复检查变成 hooks。

8. 谨慎使用 Skills 和 Subagents

Skills 适合那些可复用、但又太具体而不适合放进通用说明里的工作流。一个 skill 应该范围很窄：

review a PR against this team's checklist
write release notes from commits
triage a production log bundle
apply this service's API conventions

Subagents 适合会消耗大量上下文的调研任务。例如：

Use a subagent to inspect how authentication handles token refresh.
Summarize reusable utilities and edge cases.
Do not modify files.

这样主会话可以继续聚焦实现。我会把 subagents 用在调研、review 或并行探索上，而不是需要持续协调的紧耦合修改。

9. 主动管理上下文

上下文是一种资源。长会话会积累文件内容、命令输出、错误尝试和旧需求。到一定程度，Claude 会背着太多历史继续工作。

我现在的习惯是：

  • 一个连贯任务使用一个会话
  • 无关任务之间使用 /clear
  • 任务仍在继续但上下文变长时使用 /compact
  • 方案走偏时使用 /rewind 或 checkpoints
  • 回到同一工作流时恢复命名会话

如果我在同一个问题上纠正 Claude 两次，我通常会停下来，用新信息重写提示。一个干净会话加精确提示，往往比满是纠错历史的长会话更好。

10. 手动流程稳定后再扩展自动化

Claude Code 可以非交互运行，也可以分发到很多文件上，但自动化应该放在最后。

一个简单的非交互命令可能很有用：

claude -p "Explain what this project does"

对于脚本，结构化输出更重要：

claude -p "List API endpoints as JSON" --output-format json

对于大型迁移，我会先在两三个文件上测试提示，修正提示后，再扩大范围。并行会话和 worktrees 很强，但也会带来协调成本。更稳妥的顺序是：

manual workflow -> stable prompt -> small batch -> broader automation

11. 常见失败模式

我想避免的问题很固定：

  • 一个永不结束的会话混入无关任务
  • 没有验证步骤的模糊提示
  • 过度膨胀的 CLAUDE.md
  • 因为生成代码看起来合理就直接相信
  • 让 Claude 在没有明确问题的情况下探索整个代码库
  • 手动流程还没跑顺就开始自动化

这些大多是流程问题。只要流程给 Claude 边界、上下文和反馈，它就会可靠很多。

我现在的规则

我希望 Claude Code 处理机械性的闭环：

inspect -> plan -> edit -> verify -> fix -> summarize

产品方向仍然由我负责。Claude 可以快速穿过实现细节，但我需要决定什么应该存在、哪些取舍可以接受，以及什么时候结果已经足够发布。

来源

这篇文章总结并改写自 Anthropic 的 Claude Code best practices：

https://code.claude.com/docs/en/best-practices