KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA

06 · 可直接复用的工作流与模板 — keel 龙骨

这一章回答：明天早上开工，具体要说什么、做什么、Checklist 是什么。

这一章回答：明天早上开工，具体要说什么、做什么、Checklist 是什么。

这一章把前面所有原则固化成可以直接复制粘贴的东西。个人层面的度量与团队级的门禁在下一章。

6.1 项目常驻约定：`AGENTS.md` 模板

# AGENTS.md

## 项目
- 技术栈：<语言 / 框架 / 版本>
- 目的：<一句话>

## 命令（照抄执行，不要自己发明）
- 安装：<命令>
- 启动：<命令>
- 测试：<命令>
- 构建：<命令>
- 发布：<命令>（含必要的环境变量，例如 XXX_BASE_PATH=...）

## 不可违反的原则（每条都必须写明代价）
- <原则 1>：<它禁止什么>，代价是 <付出什么>
- <原则 2>：<它禁止什么>，代价是 <付出什么>
- 例：金额一律用 Decimal，不用 float —— 代价是编码稍繁琐，收益是精度有保证

## 目录约定
- `<目录>`：<职责>
- `<目录>`：<职责>

## 编码约定
- 命名：<包/类/函数/字段各自的风格>
- 错误处理：<用哪种异常类型，在哪一层捕获>
- 日志：<格式与级别约定>
- 注释与文档语言：<中文 / 英文>
- 严禁：升级依赖、重命名无关文件、大范围格式化、删除未确认的代码

## 验收标准
每次改动结束必须：
1. 列出改动文件清单及原因
2. 跑 <lint> 和 <test>
3. 跑 <项目自有校验脚本>
4. 说明本次改动的影响面
5. 指出未完成项或风险点，不许留隐形 TODO

注意第二栏：原则必须写明代价。 写不出代价的，都是口号，而口号对 AI 没有任何约束力。

6.2 任务单模板

【目标】一句话说清要什么，能怎样验证
【背景】为什么需要 / 现在的问题是什么
【上下文】相关文件路径（file:line）、参照的现有实现
【范围】只允许改：<文件清单>
【禁止】不要动：<…>；不要升级依赖；不要重构无关代码
【约束】性能 / 兼容 / 边界要求；失败路径如何处理
【验收】跑什么命令、看到什么算完成
【回退】出问题怎么还原（分支 / 备份 / 上一个发布版本）
【其他】不确定就先问，不要猜

6.3 开工三问（动代码前必答）

落在哪：这件事应该发生在哪个文件的哪个函数？给 file:line。
影响谁：改了之后哪些调用点、哪些对外行为会变？
怎么验：一条可以复现的命令，能证明改动生效且没坏。

三问答不上来，就不许开始写代码。

6.4 Git 节奏

开工前：确认工作区干净；有历史未提交改动就先单独提一笔再开始。
一个意图一个 commit：新功能和顺手的修复分开提，回滚时才有粒度。
改动后立即 git diff --stat：文件数量和行数超出预期就是信号。
适当分批：每完成一个可验证的小步就提交，不要攒一个大 commit。

6.5 回退策略（按代价从小到大）

单文件撤销 → 编辑器 undo / 丢弃该文件的改动
一步改动回滚 → git checkout -- <file> 或 revert 那个 commit
整轮迭代回滚 → 切回改动前的分支/commit
已发布到线上 → 切换回上一个发布版本/备份目录（所以发布前必须有备份）

原则：在任何不可逆动作（发布、删除、迁移）之前，先确认"怎么回来"。

6.6 收尾自检清单

改动范围没超？
依赖没动？（动了就单独说明理由）
lint / 构建通过？
项目自带的校验脚本通过？
主链路手工跑通？
边界与失败路径处理了？
日志/文档里没有敏感信息？
AGENTS.md 需要更新吗（学到的新约定）？

最后一条常被忽略、却决定长期效率：每轮协作结束时，把新学到的项目约定写回 AGENTS.md。 vibe coding 不是一次次从零开始，是把教训变成下次的默认上下文。

动手：可观察结果

这周之内，在你的主项目里完成三件事：

产出	判断标准
`AGENTS.md`	已提交；至少 5 条带代价的原则；新会话只读它就能上手
任务单模板	存成代码片段 or issue 模板，本周至少用 3 次
收尾自检清单	贴在工作区可见处；本周每次改动的 PR 描述里都出现过它的条目

完成标志：一个从没见过这个项目的人（或一个新会话的 AI），读完 AGENTS.md 就能独立改一个 bug 且不违反约定。

故障注入

注入方式	观察
把 `AGENTS.md` 里的严禁项删掉后再改同一个需求	对比两次 diff 的无关改动数量
故意不写回退路径就执行发布	出事时你要花多久才能恢复
让 AI 在不读 `AGENTS.md` 的情况下开工	数一数它违反了几条约定
在原则里写一条口号（如"代码要优雅"）	看它是否产生任何实际约束效果

自测题

为什么 AGENTS.md 里的原则必须写明代价？举一条你项目里的真原则。
任务单里"禁止"一栏为什么要单独写，而不是写进"范围"里？
你的 8 条收尾自检清单里，哪一条最容易被跳过？跳过的代价历史上发生过吗？
回退策略的四档，你最近一次改动能用哪一档？为什么更高一档不可用？
如果不允许你在 AGENTS.md 里写超过 100 行，你会删掉哪部分？这个取舍说明了什么？

进入 keel 阅读