AI Agent 协作开发工程治理模板(二):从克隆到发布,八个阶段走一遍
上一篇讲了模板里有什么,这一篇讲怎么用:从克隆仓库开始,按八个阶段走一遍,每个阶段发什么指令、产出什么、什么时候才能进下一步。
一、手把手怎么用:从克隆到发布走一遍
1.1 两种启动方式
方式一:手动克隆(最直接)
git clone https://github.com/zhaoxuejie/moqian-ai-template.git my-project
cd my-project
rm -rf .git
git init -b main克隆后删掉模板自带的 .git 历史,重置成你项目独立的 Git 仓库,再把 README.md 标题换成项目名、清空 CHANGELOG.md 的发布记录。
方式二:配套技能一键初始化(推荐)
安装配套的 moqian-project-scaffold Agent Skill,只要给项目名,它自动完成:克隆模板 → 删除模板 .git → 清理示例任务卡 → 重置 README 与 CHANGELOG → git init 独立历史 → 恢复发布脚本可执行位 → 首次提交并校验必要文件。项目名要求小写 kebab-case,比如 knowledge-agent。
1.2 标准工作流程:八个阶段,每道闸门人工确认
docs/stage-prompts.md 已经把每个阶段可直接复制的指令写好了。新会话先粘贴 prompt.md 基座规则,再按阶段追加对应指令;一个阶段做完人工确认,才进下一个,不要一次性全发。
| 阶段 | 产出物 | 进入下一阶段的前提 |
|---|---|---|
| 0 初始化骨架 | 目录结构与初始文件 | 骨架就绪,等待需求 |
| 1 编写 PRD | docs/prd.md | PRD 人工审阅通过 |
| 2 架构 + ADR | docs/architecture.md | 架构方案人工审阅通过 |
| 3 接口契约 | docs/api-contract.md | 接口文档人工审阅通过 |
| 4 增量拆任务卡 | 第一批 3~5 张任务卡 + 更新索引 | 任务卡人工审阅入库 |
| 5 逐任务开发验收 | 代码 + 配套测试,任务卡标记 done | 验收标准与评测方案全部通过 |
| 6 MAJOR 升级 | docs/archive/ 快照 + 更新文档 + 新增 ADR | 发生不兼容破坏性变更时触发 |
| 7 版本发布 | 更新 CHANGELOG.md,执行发布脚本打 tag | 当前里程碑任务全部 done |

下面把每个阶段实际怎么操作拆开讲。
1.3 阶段 0:初始化骨架
新会话粘贴 prompt.md 后,发送阶段 0 指令:
请基于本工程框架,输出完整的项目骨架目录和初始文件内容,严格遵循目录规范、命名规范。
初始产出:README.md、AGENTS.md、CONTRIBUTING.md、CHANGELOG.md、.env.example、
docs/readme.md、docs/prompt.md、docs/stage-prompts.md、空的 prd.md、architecture.md、
api-contract.md、docs/tasks/readme.md、空 archive 目录。
不要写业务代码,只输出框架骨架。骨架生成完成后通知我,等待我给出项目需求,再进入 PRD 阶段。这一步不写任何业务代码,只搭框架。
1.4 阶段 1:写 PRD
骨架就绪后,在阶段 1 指令里先填你的真实需求(项目名称、要做什么、目标用户、核心功能、约束偏好),再发给 AI。指令明确要求:现阶段只产出 prd.md,不做架构、不拆任务、不写代码;需求模糊处主动反问,不脑补。初稿交你审阅,通过才进架构阶段。
1.5 阶段 2:架构 + ADR
PRD 通过后进入。AI 依据已确认的 prd.md 输出总体架构、模块划分、数据流、依赖、技术选型、风险,并用 ADR 记录每个关键决策。同样只产出 architecture.md,不碰接口和代码。
1.6 阶段 3:接口契约
架构通过后,基于 PRD 和架构输出 api-contract.md:路径、请求参数、响应体、错误码、版本状态、deprecated 预留和迁移指引。评审通过后,才允许开始拆任务。
1.7 阶段 4:增量拆任务卡(最核心的一道闸门)
现在进入任务拆分阶段。遵循增量拆分规则:禁止一次性拆完全部里程碑任务。
先输出【顶层第一批任务】,控制在 3~5 个以内。
每张任务卡严格使用 task-00x-xxx.md 模板,包含:编号、里程碑、前置依赖、优先级、
来源、执行步骤、验收标准、评测方案。
输出任务卡草稿之后,等待我人工审阅、修改确认。
我确认这批任务入库、更新 tasks/readme.md 索引之后,才可以开始开发,或者继续拆解下一批任务。一张任务卡长这样(模板 docs/tasks/task-00x-xxx.md):
# TASK-001 任务标题
里程碑:
前置依赖:无
优先级:⚪ P2
状态:⬜ todo
## 来源
关联文档:
## 执行步骤
1.
2.
3.
## ✅ 验收标准(全部满足才算完成)
- [ ]
## 🧪 评测方案
- 评测类型:单元测试 / 契约测试 / LLM评估集 / 人工验证
- 评测入口:
- 通过判定:
## 关联
- 关联PR:
- 子任务:状态和优先级在索引看板里统一用"图标 + 词",一眼可辨:
- 状态:⬜ todo | 🟡 doing | 👀 review | 🧪 evaluating | ✅ done | 🚫 abandoned
- 优先级:🔴 P0 阻塞 | 🟠 P1 核心 | ⚪ P2 可选
编号全局唯一,废弃任务标 abandoned,不删文件、不回收编号。
1.8 阶段 5:逐任务开发验收
一次只处理一张前置依赖全部 done 的任务卡:
现在进入开发阶段,只处理 TASK-{{编号}} 这一张任务卡。
严格以这张任务卡的【验收标准】和【评测方案】作为唯一目标。
开发完成后,输出代码、配套测试用例,并且对照验收标准做自检说明。
产出完成后,等待我执行评测验收;评测不通过,继续修复,直到全部验收项满足。
本任务验收标记 done 之后,我们再看是否继续拆解后续任务或者开发下一个任务。
禁止主动开发其他任务。1.9 阶段 6:MAJOR 破坏性升级
要做 v1 → v2 这类不兼容变更时,先归档旧版快照,再改文档、补 ADR、拆升级任务卡:
- 把当前稳定版全套 docs(含 tasks)复制归档到
docs/archive/; - 更新
prd.md、architecture.md、api-contract.md,填变更摘要、废弃清单、迁移指引; - 在架构文档新增一条 ADR,记录升级决策、取舍、风险;
- 增量生成升级任务卡,分批拆解。
MINOR / PATCH 兼容迭代不用动 archive,直接改活跃文档。
1.10 阶段 7:发布与打 tag
里程碑任务全部 done 后,更新 CHANGELOG.md,执行发布脚本:
bash scripts/release.sh 1.0.0脚本先校验版本号必须是 x.y.z,检查 tag 是否已存在,然后在 CHANGELOG 的 Unreleased 区块下插入新版本条目,最后给出提交和打 tag 的命令:
git add CHANGELOG.md
git commit -m "chore(release): v1.0.0"
git tag v1.0.0
git push && git push --tags1.11 阶段 8:随时可用的评审模式
改文档、改代码过程中,随时可以进入评审修正模式,你指出问题,AI 只针对问题修改,不扩大范围、不新增功能、不新拆任务,改完列改动清单等你确认。
二、日常工程规范要点
除了阶段闸门,模板在 CONTRIBUTING.md 里固定了协作规范:
- 分支:Trunk-Based 主干开发,
main随时可发布、保持稳定,禁止直接 push main;改动走分支 + PR,分支名feat/xxx、fix/xxx、docs/xxx、refactor/xxx。 - 提交信息:
类型(范围): 简短描述,类型含feat / fix / docs / refactor / test / chore。textdocs(prd): 补充用户场景表格 feat(retrieve): 增加向量检索接口 fix(task): 修正任务卡评测判定逻辑 - 代码变更必须关联 TASK-XXX 任务卡;文档类 PR 只含对应文档,不混代码;任务卡变更同步更新
tasks/readme.md索引。 - 文件命名:顶层文件首字母大写;
docs内文档与任务卡统一小写 kebab-case,禁止驼峰、中文、空格。