面向 AI Agent 工程与 AI 辅助软件工程的全生命周期治理规范：一个启动配置阶段（Gate 0）加十二个治理关卡（Gate 1–12），按工程规模与风险动态选择「完整执行 / 简化执行 / 条件触发 / 关闭」。
作者：GitHub@kmmiku
功能： 在工程启动前先确定本工程需要执行哪些治理流程、各流程的执行深度、汇报频率和审批要求，再按需执行后续关卡。覆盖可行性分析、架构设计、任务拆解、分支开发、重大决策审批、交付汇报、阻塞处理、工期成本、实施验收、变更管理、运行维护、回滚闭环。适用于小型 PoC、中型功能开发和大型生产级 AI 工程。
- 支持 Skill 机制的 Agent 客户端（Claude Code、Codex 等），或任何能读取 Markdown 规范文档的协作流程。
- 工程涉及 AI Agent、LLM、RAG、Prompt 或 AI 与传统代码混合系统时收益最大。
- 纯问答、文本润色等不涉及工程实施的讨论，无需启动本流程。
git clone https://github.com/kmmiku/AIagent-App-Development.git将 aiagent-engineering-spec 整个目录放入你所用客户端的 skills 路径：
- Claude Code：
~/.claude/skills/aiagent-engineering-spec/ - Codex：
~/.codex/skills/aiagent-engineering-spec/
目录内必须包含 SKILL.md，其 YAML frontmatter 提供 name 与 description，客户端据此决定何时加载。
在开工或开发中直接提问，例如：
- 「帮我评估这个需求适不适合用 LLM 做」
- 「这个工程要拆成哪些可独立验收的单元」
- 「设计一下分支策略和接口契约」
- 「上线前按规范帮我做变更管理和回滚检查」
客户端匹配 description 后自动加载本 skill，按要求给出关卡配置建议与执行方案。
先做 Gate 0 启动配置，产出精简的工程配置记录（目标、规模、风险等级、关卡配置、验收要求、审批阈值、待定假设）；再按 G0 → G1 → … → G12 的依赖关系推进，无依赖的工作可并行。
| 状态 | 含义 | 执行规则 |
|---|---|---|
ON |
完整执行 | 输出该关卡规定的完整成果 |
LITE |
简化执行 | 保留必要判断和证据，减少文档及重复操作 |
AUTO |
条件触发 | 预先定义触发条件，满足时执行 |
OFF |
关闭常规流程 | 不单独执行，但仍须满足强制门禁和依赖要求 |
OFF 不等于可以忽略风险；G5、G7、G10 的条件触发规则必须保留，G9 对所有实际交付都必须保留适用的验证。
| 关卡 | 名称 | 默认模式 |
|---|---|---|
| G1 | 可行性分析（Task-Model Fit） | ON / LITE |
| G2 | 架构设计（Minimal Architecture First） | ON / LITE |
| G3 | 工程精细化拆解（Work Breakdown） | 按规模 |
| G4 | 分支与模块化开发策略 | 按风险 |
| G5 | 重大决策与人工审批 | AUTO |
| G6 | 工程单元完成与统一汇报 | 按规模 |
| G7 | 分歧、阻塞与异常处理 | AUTO |
| G8 | 工期、资源与成本估算 | 按风险 |
| G9 | 实施、测试与交付验收 | ON / LITE |
| G10 | 需求与架构变更管理 | AUTO |
| G11 | 维护、可观测性与运行风险 | 按交付目标 |
| G12 | 备份、回滚与项目闭环 | 按风险 |
| 级别 | 适用场景 | 推荐策略 |
|---|---|---|
| S | 局部 Prompt/配置调整、明确缺陷修复、小型工具函数 | 轻量可行性判断，不强制拆解表与独立分支 |
| M | 新增独立 AI 功能、多文件多模块配合、需模型评测 | 可行性+架构评估，拆分可独立验证单元，关键节点更新 |
| L | 多模块多系统、复杂 Agent 工作流、多人并行、关键数据模型 | 全套治理评估、项目级拆解表、里程碑与阶段验收 |
风险等级独立于规模：小工程若涉及生产库不可逆迁移，仍必须执行高风险门禁。
- 选择治理模式：可直接选用「全部推荐」「轻量开发」「标准开发」「生产级开发」，或按清单逐关卡自定义 ON / LITE / AUTO / OFF。
- 调整成本阈值：默认单次运行超 50 美元、月度累计超 500 美元触发审批；有正式预算时以正式预算为准。
- 调整汇报频率：S 级只需一次精简交付报告，M 级在关键节点更新，L 级采用进度状态+单元报告+阶段汇报+重大事件报告。
- 调整拆解粒度：原则上单元为 0.5–1 个工作日，超 3 个工作日应重新评估范围与阶段交付方式。
- 全局配置版本化：全局配置变更不自动覆盖已启动工程，原工程继续用原配置，除非明确升级并记录影响。
Q：小工程也要跑完十二个关卡吗？ A：不需要。切片只需必要判断和证据；普通文档、重复报告等流程可关闭或简化，但涉及未授权高风险操作、敏感数据、不可逆副作用时，对应安全门禁必须保留。
Q：用户直接说「别废话，直接写代码」怎么办？ A：规范要求先完成必要的可行性、架构和拆解评估，可复用用户已提供的信息，不重复询问。低风险、可逆的探索性 PoC 可在明确边界、成本和副作用的前提下先行验证——但 PoC 不等于正式开发审批。
Q：AI 说自己「已经测过了」能信吗？ A：规范明确禁止声称执行了未实际执行的命令、测试、备份、合并、部署或回滚。实现完成、单元验收、集成验收、合并、部署、线上验证是六个不可互相替代的状态。
Q：审批一直没回复，可以默认通过吗？ A：不可以。审批等待不得造成整个工程无差别停滞，也不得因超时自动获批。无依赖的低风险工作应继续推进，并把未确定事项列为待确认项。
Q：需求中途变了要全部重做吗？ A：不需要。轻量变更在当前单元内执行并留记录即可；结构性变更须做影响分析并更新拆解表，命中 G5 条件才需人工批准。已批准的方案在批准范围内执行不重复审批。
Q：这套规范绑定某个框架吗？ A：不绑定。规范只约束治理流程、状态真实性与验收证据，单 Agent、多 Agent、RAG、混合系统均可套用。
如有问题或建议，欢迎在 GitHub 提交 Issue 或 Pull Request。
感谢使用！🤖