AI Agent 协作开发工程治理模板:文档闸门、增量任务卡与版本闭环
这个系列介绍我开源的 AI 协作开发治理模板 moqian-ai-template。这篇是概览:先说痛点、它是什么、客观优劣;目录结构与五道闸门、八个阶段的实际操作各单独一篇,按需读。
一、先说痛点:直接让 AI 从零写代码,会发生什么
我自己用 Claude Code、Codex、DeepSeek Harness 这类 Agent 写项目很久了。最开始的用法很简单:开个新会话,把需求一段话丢进去,让它"直接给我搭一个完整项目"。跑过几个项目之后,踩的坑高度一致:
- 需求越做越偏:AI 聊着聊着自己加功能、改边界,等你发现的时候,代码已经长成你没要的样子。
- 上下文随会话丢失:换一个新对话,之前定过的架构取舍、接口约定全没了,AI 又从零理解一遍,前后说法还可能打架。
- 任务一次性炸开:一句"把这个项目做完",它一口气拆出几十上百个任务,做到一半发现方向错了,推倒重来成本极高。
- 决策无从追溯:当时为什么选这个库、为什么接口这么设计,没留下记录。几周后回头看,自己都想不起来。
- 没有验收闸门:AI 说"完成了"就算完成了,没有可判定的验收标准,也没有评测环节,质量全靠你肉眼抽查。
这些问题的根源不在模型能力,而在缺少一套约束 AI 协作的工程流程。模型很擅长连续输出,但它不会主动替你设闸门、留文档、控范围。这套 moqian-ai-template 就是我把自己踩坑后沉淀的治理流程,固化成一个可以克隆即用的仓库骨架。

二、它是什么,核心理念是什么
一句话定位:它不是代码框架,也不是某个可运行的库,而是一套"AI 协作开发的流程骨架"——你把它克隆成新项目,里面的目录、文档模板、提示词、规则和 CI 就把整个工作方式规定好了。
仓库基本信息:
| 项 | 内容 |
|---|---|
| 仓库 | zhaoxuejie/moqian-ai-template |
| 协议 | MIT(可商用、可二次改造) |
| 面向场景 | AI Agent、LLM 应用从 0 到 1 的开发治理 |
| 配套技能 | moqian-project-scaffold,一键初始化新项目 |
三条核心理念,理解了这三条,后面所有目录和规则就都顺了:
- 全部规范纳入 Git 本地托管:流程、文档模板、启动提示词、阶段指令、决策记录都在仓库里,不依赖任何云端对话记忆。新会话只要读仓库文档就能恢复完整上下文。
- 严格顺序推进:骨架初始化 → PRD → 架构 ADR → 接口契约 → 增量任务卡 → 逐任务开发验收 → 版本发布 / MAJOR 归档,一步都不能跳。
- 每个阶段都有人工审阅闸门:上一阶段文档没经你确认,不允许进入下一阶段;禁止跳流程、禁止一次性全量生成任务、禁止无文档直接写代码。
三、系列导读:两篇专题各讲什么
| 篇目 | 讲什么 | 什么时候读 |
|---|---|---|
| (一)目录结构与五道治理闸门 | 仓库目录逐个讲、AGENTS.md 与 prompt.md 的分工、五份阶段文档、五个痛点对应五道闸门 | 想知道这套模板到底管什么、凭什么管得住 |
| (二)从克隆到发布,八个阶段走一遍 | 两种启动方式、每个阶段的现成指令、任务卡模板、MAJOR 归档、发布打 tag、日常规范 | 准备把它套到自己的新项目上 |
四、客观优劣
✅ 优势
- 把 AI 协作最容易失控的环节全部前置成闸门:需求边界、架构决策、接口约定先文档确认,代码在后,跑偏成本被压到文档层就拦截。
- 上下文彻底本地化:换会话、换工具、几周后回看,靠仓库文档恢复,不依赖聊天历史。
- 任务粒度可控:增量拆卡 + 前置依赖 + 验收评测,杜绝"一口气做完一个项目"的失控模式。
- 决策和版本都留痕:ADR 只追加、archive 冻结快照、CHANGELOG 与 tag 闭环,项目长期可维护。
- 轻量、语言无关:模板本身是 Markdown + 一个 shell 脚本 + CI,不绑定任何技术栈,Python、Node、全栈项目都能套。
- MIT 协议:可直接 fork 改造成自己团队的规范。
⚠️ 局限
- 前期文档开销不小:PRD、架构、接口没写完不能动代码,急着出 demo 的人会觉得慢——这套模板天生不适合"先跑起来再说"的探索性实验。
- 规范需要你本人守住闸门:AI 会按规则走,但如果审阅时你轻易放过、跳过确认,整套流程就形同虚设。
- 任务卡状态、索引需要人工同步:状态流转和索引表主要靠流程约束,没有强制程序校验。
- 单人小脚本、一次性工具套这套流程偏重,更适合有长期维护预期的 Agent / LLM 项目。
五、结尾
moqian-ai-template 解决的不是"怎么写出代码",而是怎么让 AI 在你的项目里不失控:需求有边界、上下文不丢失、任务分批可控、决策留痕、版本可追溯。
如果你也在用 AI Agent 做长期项目,反复经历"做着做着跑偏、新会话前后打架",可以把这套骨架克隆下来试一轮。规则都写在 prompt.md、AGENTS.md 和 stage-prompts.md 里,套用成本主要是习惯改变,不是技术学习。
快速上手:
bash
git clone https://github.com/zhaoxuejie/moqian-ai-template.git my-project
cd my-project && rm -rf .git && git init -b main