Claude Code 初次任务 Runbook：安全提示词、diff 检查与提交前评审

第一个任务决定 Claude Code 是否值得信任

刚装好 Claude Code 后，很多人会直接说“把这个功能全部做完”“把整个项目重构一下”“把这个 repo 全部修好”。这正是第一次会话最容易失控的地方。通常问题不是 Claude Code 不能帮忙，而是范围、验证方式、权限和项目上下文还没有对齐。

这篇 Runbook 面向真实仓库里的第一个实用任务。Runbook 可以理解为可重复执行的操作清单。这里的第一个任务不是“完成一个大功能”，而是一个小流程：清楚地提出请求，先确认计划，只做一个受限修改，阅读 diff，并留下 handoff 备注。

如果基础操作还不熟，先读 Claude Code 入门指南。当你需要沉淀项目规则时，可以配合 Claude Code 的 CLAUDE.md 模板。官方资料以 Claude Code overview、memory 与 CLAUDE.md、permission modes、common workflows、CLI reference 为准。

flowchart LR
  A["读取仓库"] --> B["列出 3 个安全选项"]
  B --> C["选择 1 个任务"]
  C --> D["先评审计划"]
  D --> E["生成最小 diff"]
  E --> F["验证测试和 diff"]
  F --> G["写 handoff 备注"]

什么样的第一个任务才好

第一个任务不主要看产出有多大，而是看这个流程能不能继续被信任。好的初次任务有五个特征。

特征	简单解释	好例子
本地完成	不碰生产、客户数据或外部发送	检查 README 命令，或加一个 assertion
范围明确	文件和停止点都看得见	一个组件、一个测试、一个文档
可验证	命令、页面或 diff 能证明成功	npm.cmd run test、git diff --check
可回退	结果不好可以快速丢弃	普通源码文件，而不是生成导出
可解释	人能理解为什么要改	原因、风险、未确认点都有记录

“重做认证”“现代化整个代码库”“修 CI 并部署”都不是好的第一个任务。它们会把上下文不足、权限提示、测试薄弱和难以评审的 diff 混在一起。

安全的初次任务菜单

团队 onboarding 时，先从这个菜单里选。

任务	为什么有用	成功条件
画出仓库地图	修改前先测试理解力	识别 entry point、命令和风险区域
总结一个失败测试	看 debug 粒度	失败点、假设、下一步最小动作清楚
修一个过期 README 命令	尝试低风险真实编辑	命令能跑，diff 很小
给现有测试加一个 assertion	看意图理解和测试判断	assertion 保护明确行为
改一个 UI 文案	检查搜索和最小修改能力	只有目标组件变化
修一个 lint warning	看局部修改纪律	少一个 warning，行为不变
创建最小 CLAUDE.md	提升后续会话质量	命令、边界、评审规则写得简洁

重点是“小但真实”。这个任务应该连接 onboarding、bug 诊断、文档整理、测试增强或评审质量。

可以直接复制的提示词

一开始让 Claude Code 读取和提案，不要直接编辑。

请读取这个 repository，但暂时不要编辑。

请返回：
1. 主要 entry point
2. 常用 build/test/lint 命令
3. 风险目录或生成文件
4. 适合 30 分钟初次会话的 3 个安全任务
5. 每个任务如何验证以及如何回退

拿到候选项后，只选一个，并要求先写计划。

只继续候选 2。暂时不要编辑。
请先写出会触碰的文件、修改原因、预期 diff、验证命令和风险。
如果范围会变大，请提出更小的替代方案。

确认计划后再允许修改。

按已批准的计划执行，并保持最小 diff。
不要触碰请求范围外的文件。
编辑后请总结已执行的验证命令、失败或跳过的检查，以及剩余风险。

提交前评审使用单独提示词。

请做提交前评审。

1. 阅读 git diff，查找请求范围外的修改
2. 找出缺失测试或验证薄弱点
3. 检查安全、数据破坏和配置变更风险
4. 找出不应该进入 commit 的文件
5. 标出仍需要人判断的事项

结论只用三选一："可以 commit"、"先修再说"、"停止"。

30 分钟执行流程

前 5 分钟先固定当前状态，再交给 Claude Code。Windows PowerShell 可以直接使用：

Get-Location
git status --short
git branch --show-current
rg --files | Select-Object -First 40

macOS 或 Linux 使用：

pwd
git status --short
git branch --show-current
rg --files | head -n 40

如果 worktree 已经有未提交改动，要先说明哪些是人工改动，不能碰。否则最后很难判断 diff 哪些来自 Claude Code，哪些原本就存在。

接下来的 10 分钟只选择一个任务。过期 README 命令、一个测试 assertion、一个失败测试总结都是好选择。第一次会话先不要做新功能。

到第 20 分钟左右，优先证明正确，而不是继续扩大修改。一个正确且能解释的改变，比三个没有验证的改变更有价值。

git diff --stat
git diff --check
git diff
git status --short

最后 5 分钟写 handoff 备注。handoff 备注是给下一个人或下一次 Claude Code 会话的短说明。长对话可能会丢失最初的边界，下一次会话需要一个干净的起点。

四个具体使用场景

场景 1：新开发者 onboarding

第一天不要直接给新人一个大 issue。让 Claude Code 生成 repo 地图、关键命令、危险目录和最先阅读的文件。

提示词：“为新开发者写一份 onboarding note。把事实和猜测分开。能提供命令输出时请附上。” 成功标准是，这份笔记能补充 README 之外的实践信息，比如生成文件、本地 setting、CI 与本地差异。

场景 2：可见 bug 的复现备注

如果 bug 是“偶尔坏”，不要先要求修复。先让它整理条件、预期结果、实际结果、相关文件和缺失日志。这和 Claude Code bug report 模板 很搭。

成功不是 patch，而是人能验证的备注。如果无法复现，输出应该明确说明，并列出下一步需要的日志或数据。

场景 3：文档或 UI 文案修改

营销网站、管理工具、内部 dashboard 常适合作为第一次会话，因为文案修改可见且容易回退。但范围要窄：一个 CTA、一段设置说明或一个段落。

成功意味着只有目标文件变化，语义不变，并且可以本地查看结果。多语言网站还要检查是否只改了一种语言而让其他语言不一致。

场景 4：小幅测试增强

如果项目已有测试，加一个 assertion 比加新功能更安全。可以加边界值、错误消息期望，或空列表场景。

测试通过还不够。Claude Code 应该解释这个 assertion 保护了什么行为。无法解释的 assertion 以后会变成维护噪音。

commit 前的 diff 评审

Claude Code 编辑后，要回到人工评审。第一次任务避免自动 commit 和自动 push。permission modes 本质是在便利和监督之间做取舍，所以初次使用建议从普通评审或 plan mode 开始。除非在隔离环境里，否则不要轻易使用 bypass permissions 这类强权限模式。

commit 前 checklist

[ ] 只有请求的文件发生变化
[ ] 没有混入生成文件、secret 或本地 setting
[ ] 已记录测试或替代验证结果
[ ] 失败或跳过的检查已说明
[ ] 没有无法解释的 diff
[ ] handoff 备注包含下一个 TODO

先用 git diff --stat 看范围。再用 git diff --check 查 whitespace 和 patch 基本问题。最后阅读 diff 本身，寻找意外 refactor、命名变化、没有测试的行为变化。

常见失败

第一个失败是范围太大。说“用一个测试验证 login error message”，不要说“修好 login”。在小任务上建立信任后，再给更多自主空间。

第二个失败是没有证据就接受“完成了”。如果没有测试，就先定义替代证据：渲染页面、type check、git diff --check、日志对比或 README 命令。

第三个失败是随手批准 permission prompt。出现提示时，要看清运行什么命令、触碰哪些路径、是否包含网络访问或删除。如果提示太频繁，应该批准少量明确命令，而不是放开全部权限。

第四个失败是上下文丢失。长对话会让最初边界变模糊。把任务边界、执行过的命令和剩余风险写进 handoff 备注。不要把永久规则 CLAUDE.md 和本次会话备注混在一起。

第五个失败是破坏已有未提交工作。共享 repo 里可能已经有其他开发者或其他 agent 的改动。先运行 git status --short，并明确保护无关改动。

handoff 备注模板

在第一个任务结束时直接粘贴这个模板。

## Handoff note

- Task:
- Changed files:
- Verification run:
- Verification not run:
- Important diff points:
- Remaining risks:
- Do not touch next time:
- Suggested next smallest task:

这份备注比 commit message 更宽。提交前，它可以成为 PR 描述草稿。不提交时，它就是下一次会话的起点。

下一步和付费路径

第一个任务成功后，要建立可重复性。个人使用者可以把反复出现的规则整理进 CLAUDE.md 模板。如果 approval 和 sandbox 还不清楚，阅读 Claude Code approval and sandbox guide。

如果需要可直接使用的模板、checklist 和 onboarding 材料，请看 /products/。如果要做团队 rollout、按仓库定制 onboarding、权限设计和 review workflow，请使用 /training/。一个安全的初次任务可以靠本文完成。团队推广前，需要先准备规则、证据和培训。

在 Masa 的实际试用中，最稳定的模式是：先读 repo，只改一个文件，一起看 git diff，并留下 handoff 备注。以大请求开场的会话，产生的 review 工作比节省的时间更多。成功完成一个 30 分钟小任务后，第二个任务更容易定范围，也更容易向团队解释。