最佳实践与工作流
Claude Code 官方最佳实践、常见 prompt recipes、探索-计划-实现、验证、上下文管理、子代理、worktree、headless 和 review 流程。
这页把官方 Best practices、Common workflows 和 How Claude Code works 合并成可执行工作流。它不是命令清单,命令细节看 命令大全。
如果你想先理解 Claude Code 的 agentic loop、工具、上下文加载和扩展能力分工,看 工作原理与扩展地图。如果你要直接复制 prompt 给团队用,看 Prompt 模板与团队推广。
#工作方式总览
Claude Code 的核心循环是:读上下文,决定下一步,调用工具,观察结果,继续迭代。你的提示越能给它验证路径和边界,结果越稳定。
| 阶段 | 你给什么 | Claude 做什么 |
|---|---|---|
| 探索 | 目标、相关目录、不要改文件 | 读代码、画依赖、找风险 |
| 计划 | 约束、验收标准、测试命令 | 产出步骤和取舍 |
| 实现 | 明确允许改哪些文件 | 小步修改 |
| 验证 | lint、typecheck、test、build、截图 | 运行证据并修回归 |
| Review | 让它按 code review 姿态找问题 | 排 bug、风险、测试缺口 |
#给 Claude 可验证路径
不要只说“修好”。给它能判断成败的命令:
修复登录页移动端布局。
完成后运行:
- npm run lint
- npm run typecheck
- npm run build
- 用 390px 和 1440px 视口检查按钮不重叠如果没有测试,让 Claude 先找最接近的验证方式:
这个仓库没有明确测试。先找 package scripts、CI 配置和 README 里的验证命令,再决定最小验证集合。#探索先于实现
适合复杂任务的提示:
先只读探索这个模块。找出数据流、关键文件、现有测试和风险。
不要修改文件。最后给我一个不超过 6 步的实现计划。如果你已经授权它继续:
按你刚才的计划执行。每完成一块就运行相关验证,不要改无关文件。#提供具体上下文
好提示通常包含:
- 目标用户和场景。
- 允许改的目录。
- 不允许碰的文件或行为。
- 现有错误日志或截图。
- 验收标准。
- 回滚或兼容要求。
示例:
把 docs 站的搜索弹层改到手机可用。
范围: src/components/DocsClientControls.tsx 和 src/app/globals.css。
要求: 320px 宽不溢出,Esc 能关闭,Tab 不跑出弹层,浅暗色都可读。
完成后运行 lint/typecheck/build。#写好 CLAUDE.md
CLAUDE.md 适合写新同事需要知道的稳定知识。
# 项目约定
- 使用 npm,不要引入 pnpm lockfile。
- 文档内容在 content/docs。
- 修改 UI 后运行 npm run lint、npm run typecheck、nice -n 10 npm run build。
- 本地 3017 是静态预览服务,不要重启,构建会刷新 out。
- 不要把 API Key 写入 .claude/settings.json。不适合放进 CLAUDE.md 的内容:
- 一次性任务说明。
- 过期 bug 记录。
- 需要强制执行的安全规则。安全边界用 permissions 或 Hooks。
- 大段复制的日志。
#权限、Hooks 和环境
| 需求 | 推荐 |
|---|---|
| 常用测试免确认 | permissions allow 精确命令 |
| 永远禁止读密钥 | permissions deny + Hook 双保险 |
| 改文件后自动 lint | PostToolUse hook |
| 控制网络访问 | Bash deny、Hook 或沙箱 |
| 团队共享规则 | .claude/settings.json |
| 个人 Key | 用户环境变量或 ~/.claude/settings.json |
权限详情看 权限与模式,Hook 看 Hooks 自动化,沙箱看 沙箱与隔离环境。
#子代理和并行
子代理适合“可独立完成的探索或审查”,不要把当前关键路径完全交出去。
好用法:
让一个 subagent 只读审计移动端样式问题。
主线程继续修文档内容。
子代理最终只输出文件/行号和建议,不要改文件。可写子代理要给清楚所有权:
Worker A 只改 content/docs/claude-code/*.mdx。
Worker B 只改 src/app/globals.css。
不要互相回滚对方改动。并行工作区用 Worktrees 并行工作区 隔离。
#管理上下文
| 现象 | 做法 |
|---|---|
/context 显示很满 | /compact 或开新会话 |
| 反复贴大日志 | 先过滤错误关键词 |
| 代码库太大 | 让 Claude 先 rg 定位,再读文件 |
| 多轮偏离目标 | 用短提示重申验收标准 |
| 需要回到旧状态 | 用 /rewind 或 Git |
缓存相关:
- 保持模型和 effort 不变,更容易命中 5m/1h 前缀缓存。
- 大幅改
CLAUDE.md、MCP、skills 或 output style 会改变前缀。 /compact能降上下文,但摘要替换后缓存形状也变。
#常见工作流
#了解新代码库
只读探索这个仓库。输出:
1. 技术栈
2. 入口文件
3. 主要数据流
4. 测试和构建命令
5. 高风险区域
不要修改文件。#修 bug
复现并修复这个 bug。
先找相关测试或最小复现,再改代码。
完成后运行最小相关测试和全局 lint/typecheck。#重构
重构这个模块但保持行为不变。
先列出当前外部接口和测试覆盖,再小步改。
每一步都说明行为为什么没变。#写文档
根据当前实现更新文档。
不要猜 API 行为,从源码、测试和官方文档核对。
保留链接到权威来源。#创建 PR
总结当前 diff,生成 PR 描述:
- 背景
- 主要改动
- 验证命令
- 风险和回滚#Headless 脚本
claude -p "Review this diff for bugs. Return JSON with severity, file, line, finding." \
--output-format json脚本里要限制输入规模,避免把整个仓库和长日志塞进去。
#反模式
| 反模式 | 后果 | 改法 |
|---|---|---|
| “把项目优化一下” | 范围失控 | 写清目标、指标和允许范围 |
| 不给验证命令 | 容易只做表面改动 | 给 lint/test/build 或让 Claude 找 |
| 让多个 agent 改同一文件 | 冲突和覆盖 | 拆所有权或用 worktree |
| 把秘密放进 prompt | 进入上下文和日志 | 用 env、secret manager、deny rules |
| 长时间不清上下文 | 成本高、注意力下降 | /context、/compact、新会话 |
| 只靠 CLAUDE.md 做安全 | 无强制力 | permissions、Hooks、sandbox |
#官方参考
Support / 支持
Need help? / 需要帮助？
接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.
也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right
