开发了一个治理ai写代码的小工具
我本地有一个自己维护的工具箱项目，主要放些自用的脚本和自动化功能。前阵子想往里面加几个新模块，偷懒全权交给了 AI。
刚开始一切正常：我把项目架构、技术栈、命名风格交待清楚，AI 几分钟就能吐出一段能跑的代码。但聊到三十轮往后，灾难开始了。
AI 开始严重的上下文遗忘。
前面千叮咛万嘱咐“这个是核心配置不要动”，几轮之后它反手就给你重写；我提醒一句，它滑跪道歉改回去，再聊几句又犯。原因也很现实：几十轮对话下来，滑动窗口早就把最早的 System Prompt 和约束规则截断或压缩得稀碎了。
换 Agent 的时候更痛苦。任务卡住换个新会话，前一个 Agent 建立起来的背景约束瞬间清零，新来的 Agent 就像一个新入职且完全不看文档的实习生，上来就按自己的野路子写。
来回折腾了几天，整个项目彻底沦为屎山。到处都是 AI 临时糊上的补丁，逻辑盘根错节。最后只要一加新功能，老逻辑必然连锁崩溃，review diff 时连 AI 自己都解释不清楚某一行代码当初是为什么加的。
最后没办法，我只能把核心模块整个删了重写。
尝试用 Markdown 管规矩，为什么失败了？
重构时我第一反应是：把上下文持久化到文件里，不能只留在随时会丢的聊天记录里。
最开始我写了几个 Markdown 文件当任务卡：列出当前需求、改动文件白名单、验收标准，动手前让 AI 先读文档。但实操下来踩了三个坑：
- 格式根本控不住：AI 往 Markdown 回写内容时随心所欲，今天排版成 Table，明天写成无序列表，后天又多造两个 H3 标题，跑两次文档结构就烂了；
- 长文档依然会漏读：一旦 Markdown 稍长，AI 在检索时经常只摘取中间一段，选择性忽略后面的约束；
- 软约束没有任何强制力：文档里写了“修改前必须先确认 Scope”，AI 常常直接装看不见，抬手就开写。
说白了，文档是给人看的，指望 AI 靠自律去遵守纯文本规范，基本等于买彩票。
自己搓了个轮子：ai-board
既然纯文档靠不住，我干脆写了个叫 ai-board 的本地 CLI 工具。
思路很简单：把任务状态和作用域（Scope）收拢成结构化数据。
- 机器读 JSON，人看 Markdown：状态单源化，底层全走 JSON 存取。状态更新时，自动同步渲染出一份排版干净的 Markdown 给人 review。
- 文件落盘保护：给状态读写加了文件锁（Filelock），落盘时走“写临时文件 + 原子替换（atomic rename）”，防止并发或者中断把状态文件写坏。
第三件事是提交拦截：在 Git pre-commit 钩子上做校验，如果 AI 改动的文件超出了当前任务声明的路径范围，直接打断提交。
当然，它也不是什么银弹。比如目前校验只卡在 Git 提交阶段，AI 在本地乱改文件的时候它是拦不住的；另外 Scope 目前只做到目录/文件路径级别，跨文件的逻辑引用冲突依然需要人肉看 diff。但至少，它能让 AI 每次改代码时有个明确的锚点，知道现在在跑哪个任务、动了哪几个文件。
撞车 GSD 后的思考
做完这套东西，后来在社区里刷到了很多人推荐的 GSD（给 Claude Code 用的项目治理框架）。
点进去一看，核心思路几乎一模一样——拆分任务、锁 Scope、防止 AI 随地大小便。而且 GSD 成熟得多，好几万 Star，把讨论、计划、执行、验证分成了专门的阶段和子 Agent。
当时确实有一种“早知道别人造好了我就不折腾了”的感觉。但我拿它跑了几天之后，还是切回了自己这个简陋的脚本。
原因在于 GSD 对我的日常小项目来说太重了。它的多阶段 Agent 带来了大量的概念、命令和提示词注入，一次简单改动要消耗大量 Token。我的需求不是搭建一套企业级的研发管理规范，我只是想管住 Claude Code，让它别在我的几十个小脚本里乱改而已。
如果你做的是复杂大工程、需要完整的 multi-agent 交付流程，直接去用 GSD，不用自己造轮子；但如果你也是个人本地开发，只想要个轻巧、不抢注意力、能把任务改动范围卡住的本地小本子，可以试试这个小工具：
pipx install ai-boardai-board onboard --init-if-missing文章分享
如果这篇文章对你有帮助，欢迎分享给更多人！