Skip to content

AI Agent 协作开发工程治理模板:文档闸门、增量任务卡与版本闭环 ​

这个系列介绍我开源的 AI 协作开发治理模板 moqian-ai-template。这篇是概览:先说痛点、它是什么、客观优劣;目录结构与五道闸门、八个阶段的实际操作各单独一篇,按需读。

一、先说痛点:直接让 AI 从零写代码,会发生什么 ​

我自己用 Claude Code、Codex、DeepSeek Harness 这类 Agent 写项目很久了。最开始的用法很简单:开个新会话,把需求一段话丢进去,让它"直接给我搭一个完整项目"。跑过几个项目之后,踩的坑高度一致:

  • 需求越做越偏:AI 聊着聊着自己加功能、改边界,等你发现的时候,代码已经长成你没要的样子。
  • 上下文随会话丢失:换一个新对话,之前定过的架构取舍、接口约定全没了,AI 又从零理解一遍,前后说法还可能打架。
  • 任务一次性炸开:一句"把这个项目做完",它一口气拆出几十上百个任务,做到一半发现方向错了,推倒重来成本极高。
  • 决策无从追溯:当时为什么选这个库、为什么接口这么设计,没留下记录。几周后回头看,自己都想不起来。
  • 没有验收闸门:AI 说"完成了"就算完成了,没有可判定的验收标准,也没有评测环节,质量全靠你肉眼抽查。

这些问题的根源不在模型能力,而在缺少一套约束 AI 协作的工程流程。模型很擅长连续输出,但它不会主动替你设闸门、留文档、控范围。这套 moqian-ai-template 就是我把自己踩坑后沉淀的治理流程,固化成一个可以克隆即用的仓库骨架。

裸奔式开发的失控点 vs 模板五道闸门(示意)

二、它是什么,核心理念是什么 ​

一句话定位:它不是代码框架,也不是某个可运行的库,而是一套"AI 协作开发的流程骨架"——你把它克隆成新项目,里面的目录、文档模板、提示词、规则和 CI 就把整个工作方式规定好了。

仓库基本信息:

项内容
仓库zhaoxuejie/moqian-ai-template
协议MIT(可商用、可二次改造)
面向场景AI Agent、LLM 应用从 0 到 1 的开发治理
配套技能moqian-project-scaffold,一键初始化新项目

三条核心理念,理解了这三条,后面所有目录和规则就都顺了:

  1. 全部规范纳入 Git 本地托管:流程、文档模板、启动提示词、阶段指令、决策记录都在仓库里,不依赖任何云端对话记忆。新会话只要读仓库文档就能恢复完整上下文。
  2. 严格顺序推进:骨架初始化 → PRD → 架构 ADR → 接口契约 → 增量任务卡 → 逐任务开发验收 → 版本发布 / MAJOR 归档,一步都不能跳。
  3. 每个阶段都有人工审阅闸门:上一阶段文档没经你确认,不允许进入下一阶段;禁止跳流程、禁止一次性全量生成任务、禁止无文档直接写代码。

三、系列导读:两篇专题各讲什么 ​

篇目讲什么什么时候读
(一)目录结构与五道治理闸门仓库目录逐个讲、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
本文阅读--次|全站访问--次|访客--人