AI Agent 协作开发工程治理模板(一):目录结构与五道治理闸门
这是治理模板系列的第一篇,讲模板里有什么、每样东西管什么:先把仓库目录逐个讲清楚,再看五个最常见的失控点,分别由模板里的哪道闸门拦住。
一、目录结构逐个讲清楚
克隆下来之后,整个仓库长这样。我按"它管什么"分组说明,比 README 里的纯目录树更好理解。
text
moqian-ai-template/
├── README.md # 项目说明
├── AGENTS.md # 给 AI Agent 的运行约束(开发全程生效)
├── CONTRIBUTING.md # 分支、提交信息、PR 评审、命名规范
├── CHANGELOG.md # 版本变更日志(Keep a Changelog + 语义化版本)
├── LICENSE # MIT
├── .env.example # 环境变量样例,复制为 .env 填写,禁止提交真实密钥
├── .gitignore # 忽略密钥、依赖、构建产物、日志、编辑器文件
├── .gitattributes # 统一 LF 换行,保证跨平台与 Linux CI 一致
├── .markdownlint.json # Markdown 静态检查规则
├── .github/workflows/ci.yml # CI:markdownlint + shellcheck
├── docs/
│ ├── readme.md # docs 目录索引与语义化版本规则
│ ├── prompt.md # 全局基座提示词:新会话首段粘贴,恢复全套规则
│ ├── stage-prompts.md # 分阶段指令库:初始化/PRD/架构/接口/拆任务/开发/升级/发布/评审
│ ├── prd.md # 产品需求文档模板
│ ├── architecture.md # 架构方案 + ADR 决策记录模板
│ ├── api-contract.md # 接口契约模板
│ ├── tasks/
│ │ ├── readme.md # 任务索引看板(只登记索引,不放正文)
│ │ └── task-00x-xxx.md # 单任务卡模板
│ └── archive/ # MAJOR 破坏性版本冻结快照归档目录,归档后只读
├── scripts/
│ └── release.sh # 语义化版本发布脚本:更新 CHANGELOG 并给出打 tag 指引
└── tests/ # 单元测试、契约测试、LLM 评估集存放目录1.1 两份最关键的规则文件
AGENTS.md 是开发全程给 AI 看的运行约束。它和 prompt.md 的分工是:
prompt.md:会话启动文案,新开会话时全文粘贴,告诉 AI 整套框架是什么;AGENTS.md:开发过程中的常驻约束,AI 在写代码、拆任务时持续遵守,内容覆盖任务拆分规则、文档规范、任务卡执行规则、AI 工作模式四条。
里面硬性规定了:先文档后代码;任务增量拆分,前置依赖不 done 不许启动;只处理依赖全部 done 的任务;不自行新增范围外功能。
1.2 docs 里的五份阶段文档
prd.md:项目目标、In/Out 范围、用户场景、功能清单、非功能需求、里程碑、变更摘要、废弃清单、评审记录。边界(Out of Scope)单独列出,这是防需求蔓延的关键。architecture.md:架构概述、模块划分、数据流、技术选型、部署结构、风险约束,外加 ADR 决策记录区。api-contract.md:接口路径、参数、响应体、错误码、状态标记(draft / stable / deprecated)和迁移指引。tasks/:一任务一文件的任务卡体系,readme.md只做索引看板。archive/:大版本不兼容升级时,把旧版全套文档冻结快照存进来,归档后只读。
二、为什么用它:五个痛点对应五道闸门
这一节回答"为什么值得套这套流程"。每个痛点对应模板里的一道具体闸门,不是空话。
2.1 防需求漂移:PRD 人工确认闸门
需求、架构、接口全部落成文档并经你确认之后,才允许写业务代码。prd.md 强制写清 Out of Scope(明确不做什么),AI 被规则禁止新增范围外功能。需求有模糊、缺失、矛盾的地方,它必须主动提问澄清,在你回答前不允许脑补、不替你决定范围。
2.2 防上下文丢失:规范全部落 Git,新会话读文档恢复
不再依赖云端聊天记忆。换了新会话,先粘贴 docs/prompt.md,AI 就拿回完整框架规则;具体的需求、架构、接口、决策都在 docs/ 的 Markdown 里,随仓库版本一起管理,任何时候可回溯、可 diff。
2.3 防任务一次性炸开:增量任务卡 + 依赖闸门
任务一卡一文件,禁止一次性拆完整个里程碑。第一批只出 3~5 张任务卡,你人工审阅确认入库后,才允许开发,或者再拆下一批。每张卡有唯一编号、前置依赖、优先级、可判定的验收标准和评测方案;前置依赖不是 done,禁止启动。
2.4 决策可追溯:ADR 只追加不修改
architecture.md 里的 ADR(架构决策记录)每条按"上下文 → 备选方案 → 最终决策 → 取舍与代价 → 遗留风险"写。历史 ADR 只追加、不修改、不删除。几周后回看,当时为什么放弃方案 A 选方案 B,白纸黑字都在。
2.5 版本与变更可控:归档快照 + 发布脚本 + CI
- MAJOR 破坏性升级:先把当前稳定版全套文档(含 tasks)快照进
docs/archive/vX.Y/,再改活跃文档。 - 废弃接口:必须标
deprecated并附迁移指引,不允许直接删。 - 版本发布:
scripts/release.sh校验语义化版本号、更新CHANGELOG.md、给出打 tag 的完整命令。 - CI 兜底:push 到 main 或提 PR 时,GitHub Actions 自动跑 markdownlint 检查全部文档、shellcheck 检查脚本语法,文档格式问题在合并前拦住。
