给 Claude Code 的第一份任务说明书怎么写

“这个仓库，把 README 那一块帮我顺手收拾一下。”

装好 Claude Code 半小时，我扔给它的第一个任务就是这句话。结果回来的差异里，本来只想改 README，连 package.json 里的脚本名都被改了。东西是能跑，可它动的三个文件，跟我真正想修的地方完全是两码事。我盯着屏幕愣住：这玩意儿，我敢提交吗？

照理说挺聪明的 Claude Code，为什么连我没让它碰的地方都动了？这不是能力问题。是我从头到尾没说过一句”哪些能动、哪些不能动”。就像跟新来的店员说一句”店里你看着收拾收拾”就出门，回来发现整面货架都被重新排过了。

这篇文章讲的，就是怎么把那个”到哪为止”写到一张纸上。我管它叫任务说明书,也就是第一个任务的委托文。

本文要点

• 第一个任务翻车，是因为没定目标、可碰范围、验证和回滚，就一句”看着办”丢过去了。
• 说明书里写 9 项:目标／读者状态／可读／可改／可执行／禁碰／验证／回滚／下一步。
• 交给 Claude Code 的只到”读、改、跑验证命令”为止;删除、上线、扣费由人来拍板。
• 文末给了可直接复制的说明书模板,还有一段自动检查说明书是否漏项的 JavaScript。
• 先挑一个”就算失败也能用 git 一键还原的小任务”,这是最快拿到成功体验的路。

为什么第一个任务最容易翻车

刚装上 Claude Code,很多人第一反应都是丢一个”大任务”:“把仓库整理一下""把 README 修一修”。这心情我懂,谁不想先试试它到底能干啥。

可一旦扔出大任务,头十分钟全耗在它瞎逛上了。Claude Code 会到处翻文件,顺手改一堆看起来”相关”的地方,最后甩给你一句”应该能跑”的含糊汇报。然后你只能把所有差异重新读一遍,读完心想:还不如我自己来得快。

根子不在模型聪不聪明,而在你没给它目标和边界。换成一个真实的新人,上班第一天你说”你随便发挥”,他要么手足无措杵在那,要么一路狂奔闯祸。先把边界划清楚,这类事故基本就没了。

如果连基本操作都还没摸熟,建议先扫一遍Claude Code 入门指南再回来,这篇说明书的逻辑会顺很多。

说明书要写的 9 个栏位

我每次都会在一页纸上写下这 9 项。不用什么高深词,每行填一个答案就行。

栏位	写什么	反例 → 正例
目标	做完后达到什么状态算成功	”修 README”→“让 README 步骤对齐 package.json”
读者状态	这是给谁做的	(空着)→“新手,只想稳稳成功一次”
可读	允许参考的文件	(全部)→“只有 README.md 和 package.json”
可改	允许改写的文件	(全部)→“只有 README.md”
可执行	允许跑的命令	(随便跑)→“只跑 npm run build”
禁碰	绝对不许动的地方	(没写)→“package-lock、部署配置、价格”
验证	成功的证据是什么	”能跑就行”→“build 通过／差异只在 README”
回滚	失败了怎么还原	(没有)→“用 git 还原 README”
下一步	给读者指一个去向	(并排放 3 个)→“先只发免费入门资料”

关键是”禁碰""验证""回滚”这三栏。写下它们的那一刻,这份委托就从一句”拜托了”变成了一件”能放心交出去的活儿”。

可以直接复制的说明书模板

下面这份雏形可以照搬。之所以放进代码块,是为了能整段粘贴给 Claude Code。把仓库名和要修的位置换成你自己的就行。

# 第一个任务的说明书

目标: 让 README 的环境配置步骤对齐 package.json 的内容。
读者状态: 新手,只想稳稳成功一次。
可读:
- README.md
- package.json
可改:
- 只有 README.md
可执行:
- npm run build
禁碰:
- package-lock.json
- 部署配置(环境变量、发布设置)
- 价格和报名链接
验证:
- npm run build 能通过
- git diff 只显示 README.md 的改动
回滚:
- 验证失败就用 git 把 README.md 还原
下一步:
- 先只引导到免费入门资料

拿真实任务举例:如果只是让 README 步骤对齐 package.json,那么可读的是 README 和 package.json,可改的只有 README,证据是 npm run build。这个粒度下,失败了 git checkout -- README.md 一行就能还原。第一次就该这么窄。反过来说,越窄,你自己越容易判断到底成没成功。

哪些交给 Claude Code,哪些自己拍板

写说明书时,我脑子里始终划着这条线。边界一模糊,Claude Code 就会”出于好心”越线。

可以交给 Claude Code	由人来拍板(不自动化)
读取指定文件	决定让它碰哪些文件
只改指定文件	删除文件
跑 npm run build 等验证命令	上线、部署
返回差异摘要	会产生扣费的操作
汇报失败原因	git push --force 等不可逆操作

左边的交出去,右边的一开始全设成”执行前先问人”。等哪个操作确认安全了,再一点点挪到自动那一侧。光是守住这个顺序,半夜被吓出冷汗的次数就会骤减。

把任务递过去时,我会附上这么一句:

请只在这份说明书的范围内,执行一个很小的任务。
凡是你判断超出范围的事,不要执行,只给出建议。

请先返回这 5 项:
1. 接下来要读的文件
2. 接下来要改的文件
3. 作业前后要跑的验证命令
4. 改动差异的摘要
5. 失败时的还原方法

诀窍是”动手之前,先把计划和验证返回来”。一旦返回的计划超出说明书范围,你当场就能叫停。在它动手之前拦下来,就不用收拾烂摊子。

自动检查说明书漏项的脚本

就算你自以为写全了,漏栏的情况照样常见。我干脆让机器来查有没有漏。下面是一段可直接复制运行的 JavaScript,用 Node.js 跑 node check-brief.mjs 就行。

// 机械地检查说明书里该有的栏位是否都齐了
const requiredFields = [
  "目标",
  "可读",
  "可改",
  "可执行",
  "禁碰",
  "验证",
  "回滚",
  "下一步",
];

export function validateFirstTaskBrief(markdown) {
  // 找出没出现的栏位
  const missing = requiredFields.filter((field) => !markdown.includes(field));

  // 顺便看看验证命令(这里是 npm run build)有没有写到
  const hasProofCommand = markdown.includes("npm run build");

  return {
    ok: missing.length === 0,
    missing,
    readyForClaudeCode: missing.length === 0 && hasProofCommand,
  };
}

// 跑一下试试
const sample = `
目标: 让 README 对齐 package.json
可读: README.md
可改: README.md
可执行: npm run build
禁碰: package-lock.json
验证: npm run build 能通过
回滚: 用 git 还原 README.md
下一步: 免费入门资料
`;

const result = validateFirstTaskBrief(sample);
console.log(result);
// → { ok: true, missing: [], readyForClaudeCode: true }

养成”过了这道检查再把说明书递出去”的习惯,“禁碰”和”回滚”漏写的情况就消失了。光靠人眼盯,赶上忙的那天,总会有一处被落下。机器能查的事,交给机器才省心。

这些场景特别管用(3 个)

1. 改 README 或操作手册 “把文档更新到最新”——范围是无限大的。换成”只改 README 的环境配置那一章,对齐 package.json 里的脚本名”,差异就收在一个文件里,还能用 npm run build 验。这是最适合当第一个任务的活儿。

2. Pull Request 的初步审查 别说”看看这个 PR”,而是说:“改动文件里只读 src/ 下面的,指出可能让测试挂掉的地方。别改代码,只指出问题。“读交给它,改不改的判断留给人。这样就能避免”它自作主张一改、又造出新 bug”的事故。

3. 替换 CTA(读者下一步的引导按钮) 哪怕只是把热门文章底部的一个按钮换掉,“找到相关组件改一下”也太宽了。先在说明书里定好”可碰文件""要确认的线上 URL""要替换的链接”。作业后的检查,就从”感觉差不多”变成了”凭这个证据就能交”。

我亲手踩过的 3 个坑

老实说,用上说明书之前,我同一个坑反复掉。

第一个,没写”禁碰”。明明只让它改 README,Claude Code 出于好心连 package.json 一起”收拾”了,结果 build 跑不过了。我只是补了 禁碰: package-lock.json, 部署配置 这三行,这事就再没发生过。

第二个,验证只写了”能跑就行”。到底凭什么算”能跑”我没定,所以每次都得用眼睛把差异从头追到尾。改成 验证: npm run build 能通过／差异只在 README 这种具体命令后,确认 10 秒就搞定。

第三个,“下一步”并排放了 3 个。文章末尾资料、教材、咨询全贴上,读者的反应反而散了。按读者状态收成一个,最后那一个才会被认真点开。该写什么、定哪些项目规约,可以参考CLAUDE.md 写法最佳实践固定下来,每次就不会跑偏。

常见问题

Q. 每次都把这 9 项全写一遍,不嫌麻烦吗? 只有头几次麻烦。做一份模板存成 first-task-brief.md,以后每次只换其中 3、4 行内容就行。写说明书花的时间,远比读那一堆失控差异花的时间短得多。

Q. 很简单的活儿也需要说明书吗? “改一个文件里的错别字”这种级别,口头说一句就够了。说明书真正管用的,是那些可能碰多个文件,或者沾上线、扣费、删除的活儿。拿不准就写,不亏。

Q. 该用英文栏位名(Goal、May edit 之类)吗? 团队里要把多条日志排在一起对比,英文键名整齐会方便些;一个人用,中文足够。Claude Code 两种都懂。重点不在语言,在于栏位别漏。

Q. 不写代码的人也能用吗? 能用。写文章、整理资料也一样,“可读、可改、禁碰”这套思路是通的。非工程师的入门口子,我整理在非工程师也能用的 Claude Code里。

Q. 要是 Claude Code 无视说明书、碰了范围外怎么办? 先用”动手之前先返回计划和验证”,在它动手前拦住,这是基本操作。要是这样还越线,八成是说明书里的”禁碰”写得不够具体。把文件夹名、文件名都点明,就管用了。

我实际试下来的结果

这份说明书,我拿”让 README 对齐 package.json”这个小活儿试,效果最直观。先写好 可改: 只有 README.md,Claude Code 想伸手去碰 package-lock 或配置文件的那股劲,在”执行前的计划”阶段就被挡住了。重读差异的那道功夫,直接没了,这点最值。

验证里同时塞进 npm run build 和 git diff 两条,也很顶事。作业后的判断,从”凭感觉觉得行”变成了”build 是绿的、差异只在 README,所以能交”这种笃定的结论。反过来,有一次我把 下一步 留空,自己都犯嘀咕”接下来该引导去哪来着”,文末的导流就糊了。

说到底我明白了一件事:把巨大的自由交给 Claude Code,本身并不值钱。把第一个任务切小,让成功、失败、下一步动作都能用自己的眼睛看清楚,这才是最快的路。写一页边界那点麻烦,跟事后重读一堆失控差异的麻烦比起来,几乎可以忽略不计。

想把外层机制再抠细一点的人,去 Anthropic 的Claude Code 官方文档确认一下权限设置的行为,说明书和配置各管什么,就一目了然了。如果是想把 Claude Code 引入公司业务、连运营规则一起理顺,可以通过培训与咨询从贴合实际作业的说明书模板开始,我们一起推进。