给 coding agents 的“使用说明书”（译）

最新推荐文章于 2025-10-08 19:12:53 发布

原创最新推荐文章于 2025-10-08 19:12:53 发布 · 541 阅读

CC 4.0 BY-SA版权

原文标题：Onboarding for coding agents
原文链接：https://www.fuzzycomputer.com/posts/onboarding

最近我一直在折腾各种 AI 编程小助手：Claude Code、Cursor、Codex、Jules …… 真香归真香，但它们都一个臭脾气—— 你给多少上下文，它们就做多大事，而且每个家伙要的格式还不一样。

Cursor 要 .cursor/rules，Claude Code 找 CLAUDE.md，Codex 和 Jules 又想读 AGENTS.md，还有 .windsurfrules、.clinerules、.github/copilot-instructions.md…… 头都大了。

以前我把几百行提示全塞进 CLAUDE.md，最近我换了个懒人打法：

1. 所有上下文直接写 README（谁都看得懂）。
2. 规矩别写嘴里，全扔给工具（类型检查、linter、formatter、测试）。

结果我的 CLAUDE.md 从几百行缩到 13 行，爽翻。

README 就是宇宙通用说明书

README 这玩意儿都活了 50 年，早就成了开发者默认“入口”。
于是我把各种提示从工具专属文件搬到 README，但又不想搞成一篇大作文，就整了个简单命名套路，按领域拆文件：

• README.md —— 项目或模块的大图。
• README.<领域>.md —— 某个具体方向的说明书。

比如：

• README.architecture.md：
- • 项目怎么搭的
- • 关键架构决定
- • 数据怎么在客户端和服务端跑
- • 加新功能该按啥套路来
• README.commands.md —— 常用命令/脚本
• README.design.md —— 设计系统、组件、视觉规范
• README.testing.md —— 测试套路大全

📚 新员工入职包

这么拆完，上下文既模块化又不重复。
问题是：到底写哪些 README？

我的土办法就是把它当成给新人写的入职包——不管来的是真人同事还是 AI 小助手，都当他们啥都不懂。
你就想：明天组里来了一位新工程师/设计师，你得让他先读啥再动手？
把那堆东西统统写 README 里。

每一次新的 Cursor 或 Claude Code 会话，都相当于一个零背景的新同事空降。
你不先让他补课，他怎么干得漂亮？

于是我现在的 CLAUDE.md 只剩两行 onboarding 指令：

# CLAUDE.md

给 Claude Code 的小抄：

## 📚 入职第一步  
开干前先把下面全看一遍：
1. 所有 `**/README.md`  
2. 所有 `**/README.*.md`

** 会把子目录里的 README 也一起捞进来。
上下文都在 README 里，以后换啥工具都能直接复用。

✅ 质量闸门

入职包给了 AI 背景，那怎么保证它不写烂代码？

以前我把各种“规矩”贴在 .cursorrules 或 CLAUDE.md，现在懒得写，直接把规矩写进环境——
让工具当坏人，AI 当苦力，跑不过就别想交卷。

我叫它“质量闸门”：就是你能放心让新人 push 到生产前的那套检查。

最近一个 NextJS/TS 项目的例子：

## ✅ 质量闸门

Claude 写完代码必须跑完下面全部，一个不过就修，修完再跑，循环到全绿：

1. `pnpm type-check`  
2. `pnpm format`  
3. `pnpm lint`  
4. 单测全过 (`pnpm test:run`)

大模型对空格、import 排序、Tailwind 类顺序这些细节很容易翻车，
但它们擅长跑命令看报错再修，循环几次就全绿了。

具体用啥工具看你技术栈：TS 用 ESLint/Prettier，Python 用 ruff/pytest，Go 用 go fmt/vet/test……
总之把规矩往死里严就对了。

有了这两节（📚 入职包 + ✅ 质量闸门），我的 CLAUDE.md 现在真就 13 行。

软件也学会了 OODA 循环

为啥这套“质量闸门”最近突然这么好用？

一年前还不行，现在新模型（比如 Sonnet 4）+ 新工具（Claude Code）让小助手能一口气迭代好几分钟甚至几小时，直到所有约束全绿。

拔高视角：代码小助手现在能跑自己的 OODA 循环（观察-判断-决策-行动）。
以前只能按指令敲 token，现在能看结果、改代码、再跑检查，跟人类小菜鸟用 IDE 报错修 bug 一个路数。

人类几千年都是自己跑 OODA，现在工具也长了个初级版 OODA。

我心情复杂——
乐观面：老子当 builder 的杠杆感爆棚，复杂任务说甩就甩。
焦虑面：万一哪天工具把我们踢出循环，自己跑去追目标怎么办？

现在这 AI OODA 在软件工程最灵光，但别的领域只要能验证输出，估计也能套“质量闸门”。

你先定好“物理定律”

“氛围编程”（vibe coding）——你只喊需求，AI 全包办——确实爽又快。
但没规矩的话，分分钟给你整成屎山。

所以我给自己立了条铁律：绝不把“环境”交给 AI 氛围定。

我先定好“物理定律”：技术栈、组件、库、数据库、部署、设计系统……
这些改起来贵得离谱，还决定了项目的大部分约束。
定完后，让 AI 在笼子里随便飞。

真要加新库？我会让 Claude 给选项和利弊，但决定权在我，必须自己翻完文档再拍板。
一个烂依赖能毁项目，好抽象才让人爽到飞起。

严丝合缝的“物理定律”让我对 AI 产出更有底，Code Review 也轻松。
速度其实更快，因为我再也不用去 review 一堆半成品，等闸门全绿一次过。