Skip to content

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 检查脚本语法,文档格式问题在合并前拦住。

痛点 → 治理闸门 → 产出物映射(示意)

本文阅读--次|全站访问--次|访客--人