本文提供一套可直接落地到团队项目的 AI Agent 协作规范模板覆盖代码风格、单元测试、文档治理、开发流程、质量门禁等核心维度。团队可基于此模板结合自身技术栈进行裁剪和落地。一、总览与适用范围本文档定义了项目中 AI Agent 参与研发时必须遵守的协作规则旨在确保代码风格统一质量可预期单元测试有明确的边界和门禁文档体系结构化、可追溯开发流程有节奏review 有章法质量问题可跟进、可闭环适用对象所有使用 AI Agent如 Claude、Codex、OpenCode 等参与编码的项目前端 / 后端 / 全栈项目均可复用按技术栈做少量适配二、规范分层Source Of Truth项目中所有规则按单一可信源原则维护避免重复定义和漂移维度唯一来源文档说明业务代码风格docs/code-style/src-code/README.md命名、分层、目录、写法约束单元测试规范docs/code-style/unit-tests.md测试对象、覆盖范围、质量门禁项目文档规范docs/code-style/docs.md目录边界、更新规则、入口维护协作流程规则AGENTS.md/CLAUDE.md/GEMINI.mdAgent 协作流程与质量门禁核心原则三份协作规则文件AGENTS / CLAUDE / GEMINI内容必须保持一致仅标题不同协作规则文件只维护流程、门禁和约束不重复代码风格细则质量检查统一按上述三份规范执行业务代码走 src-code 门禁测试走单元测试门禁文档走 docs 门禁三、代码工作规则3.1 风格一致性所有新增代码必须遵守 code-style所有被改动的旧代码其新增区域、修改区域和相邻重组代码也必须向 code-style 收敛新增业务逻辑或较大改动必须先按 code-style 的分层规范判断归属3.2 改动范围控制小范围修复只调整本次触达区域不顺手扩大改造范围较大范围改动涉及旧实现迁移时必须先和需求方确认是否按分层规范重构移除多余功能代码时以是否仍被其它业务代码使用为唯一判断标准确认未使用即可先移除不因文档或测试仍存在而阻塞3.3 UI 组件约束以 Ant Design 为例优先使用组件库自带组件不重复造轮子不得为基础组件额外设置size统一遵从全局ConfigProvider的尺寸配置默认不得覆盖组件内部样式优先使用公开的 props、slots、classNames和 token 能力确需调整时必须先说明能力缺口、原因、影响范围和方案获得确认后实施例外代码必须限制作用域并备注原因3.4 运行时假设明确目标运行环境如浏览器 Chrome 100不对基础对象做过度存在性判断后端接口返回数据按接口定义信任不做额外兜底堆叠接入后端接口时必须同步补充同路径 mockmock 实现不要求单元测试四、开发流程4.1 任务启动方案先行较大任务、主链路调整、跨模块调整或重构必须先给出处理方案确认后再写代码入口确认页面/组件/全局能力任务必须先从对应设计文档docs/design/pages/、docs/components/、docs/global-design/定位工作入口没有入口记录时先补齐入口文档边界声明必须声明本次任务边界不处理边界外的页面、组件、模型或历史问题4.2 实现顺序跨公共组件 / 全局能力并影响多页面的任务先公共能力再逐个页面消费不在同一轮中混入无关页面治理修改业务代码时优先保持逻辑靠近使用场景形成稳定复用关系后才上提到共享目录触达超大文件、超长函数或职责混杂代码时本次改动不得继续扩大问题必要时优先抽出局部函数 / 组件 / hook / store / service4.3 Review 与校验实现完成后进入 review重点检查行为回归、测试缺口、规则偏离、文档漂移review 范围默认以git diff --name-only与入口文档反推确需扩大阅读范围时应说明原因code-style 校验、功能测试校验、文档校验拆分处理按不同校验角色分段完成修复验证问题时只修改当前改动直接涉及的点其它既有问题只记录到质量待办不扩大范围4.4 交付测试全部通过后必须更新本次改动涉及的业务最终状态文档交付说明默认包含改动摘要、验证结果、未覆盖风险、必要后续项不复述完整业务背景和已知失败细节五、单元测试规范摘要完整规则以docs/code-style/unit-tests.md为准代码改动涉及的测试新增、更新、移除和执行统一按单元测试规范处理除非明确提出否则不进行浏览器 UI 测试已记录的既有失败交付时只引用对应记录不重复展开分析六、质量跟进Quality Follow-ups项目维护一个docs/quality/目录专门记录待跟进的质量问题处理需求时如触达已记录的关联模块必须先提示对应待落实项触达关联待办后应同步落实业务逻辑、测试断言和验证结果docs/quality仅记录问题和待跟进项不作为当前需求必须更新的业务文档已落实的最终业务状态应沉淀到docs/design、docs/global-design或docs/components的对应文档中七、文档治理7.1 文档体系项目文档入口docs/README.md用户手册如user-manual/是独立交付目录默认不纳入业务代码或项目文档的改动范围7.2 文档规则处理文档时不得保留中间状态或时间线只保留最终校订时间和最终状态页面、组件和全局能力文档必须能作为工作入口记录涉及文档、源码目录、参考规范和单元测试入口文档治理任务应独立处理不把大范围文档入口补齐混入业务功能改动功能代码完成移除后必须同步处理所有相关文档、入口链接和过期说明业务需求、业务边界和接口资料不得写入项目规则文件应进入业务文档目录八、技术基线示例以下为示例基线团队按实际情况替换层级技术选型框架React 19UI 组件库Ant Design 5语言TypeScript构建工具Vite九、快速落地 Checklist首次引入本规范到项目时按以下清单操作复制AGENTS.md模板到项目根目录同步创建CLAUDE.md、GEMINI.md建立docs/code-style/目录编写src-code/README.md、unit-tests.md、docs.md建立docs/design/、docs/components/、docs/global-design/目录骨架建立docs/quality/目录用于记录质量待办明确技术基线并更新到规范中在团队内宣贯确保所有使用 AI Agent 的成员知晓并遵守十、模板使用说明脱敏替换将本文中所有项目特定的路径、工具名、技术栈替换为团队实际使用的内容粒度调整根据项目规模调整规则粒度。小型项目可精简大型团队可细化分层持续迭代规范不是一成不变的每季度回顾一次根据实际协作痛点更新工具适配如果使用特定的 Agent 工具如特定 IDE 插件、CLI在技术基线章节补充对应约束 AI 研发协作规范模板（AGENTS.md通用版）
本文提供一套可直接落地到团队项目的 AI Agent 协作规范模板覆盖代码风格、单元测试、文档治理、开发流程、质量门禁等核心维度。团队可基于此模板结合自身技术栈进行裁剪和落地。一、总览与适用范围本文档定义了项目中 AI Agent 参与研发时必须遵守的协作规则旨在确保代码风格统一质量可预期单元测试有明确的边界和门禁文档体系结构化、可追溯开发流程有节奏review 有章法质量问题可跟进、可闭环适用对象所有使用 AI Agent如 Claude、Codex、OpenCode 等参与编码的项目前端 / 后端 / 全栈项目均可复用按技术栈做少量适配二、规范分层Source Of Truth项目中所有规则按单一可信源原则维护避免重复定义和漂移维度唯一来源文档说明业务代码风格docs/code-style/src-code/README.md命名、分层、目录、写法约束单元测试规范docs/code-style/unit-tests.md测试对象、覆盖范围、质量门禁项目文档规范docs/code-style/docs.md目录边界、更新规则、入口维护协作流程规则AGENTS.md/CLAUDE.md/GEMINI.mdAgent 协作流程与质量门禁核心原则三份协作规则文件AGENTS / CLAUDE / GEMINI内容必须保持一致仅标题不同协作规则文件只维护流程、门禁和约束不重复代码风格细则质量检查统一按上述三份规范执行业务代码走 src-code 门禁测试走单元测试门禁文档走 docs 门禁三、代码工作规则3.1 风格一致性所有新增代码必须遵守 code-style所有被改动的旧代码其新增区域、修改区域和相邻重组代码也必须向 code-style 收敛新增业务逻辑或较大改动必须先按 code-style 的分层规范判断归属3.2 改动范围控制小范围修复只调整本次触达区域不顺手扩大改造范围较大范围改动涉及旧实现迁移时必须先和需求方确认是否按分层规范重构移除多余功能代码时以是否仍被其它业务代码使用为唯一判断标准确认未使用即可先移除不因文档或测试仍存在而阻塞3.3 UI 组件约束以 Ant Design 为例优先使用组件库自带组件不重复造轮子不得为基础组件额外设置size统一遵从全局ConfigProvider的尺寸配置默认不得覆盖组件内部样式优先使用公开的 props、slots、classNames和 token 能力确需调整时必须先说明能力缺口、原因、影响范围和方案获得确认后实施例外代码必须限制作用域并备注原因3.4 运行时假设明确目标运行环境如浏览器 Chrome 100不对基础对象做过度存在性判断后端接口返回数据按接口定义信任不做额外兜底堆叠接入后端接口时必须同步补充同路径 mockmock 实现不要求单元测试四、开发流程4.1 任务启动方案先行较大任务、主链路调整、跨模块调整或重构必须先给出处理方案确认后再写代码入口确认页面/组件/全局能力任务必须先从对应设计文档docs/design/pages/、docs/components/、docs/global-design/定位工作入口没有入口记录时先补齐入口文档边界声明必须声明本次任务边界不处理边界外的页面、组件、模型或历史问题4.2 实现顺序跨公共组件 / 全局能力并影响多页面的任务先公共能力再逐个页面消费不在同一轮中混入无关页面治理修改业务代码时优先保持逻辑靠近使用场景形成稳定复用关系后才上提到共享目录触达超大文件、超长函数或职责混杂代码时本次改动不得继续扩大问题必要时优先抽出局部函数 / 组件 / hook / store / service4.3 Review 与校验实现完成后进入 review重点检查行为回归、测试缺口、规则偏离、文档漂移review 范围默认以git diff --name-only与入口文档反推确需扩大阅读范围时应说明原因code-style 校验、功能测试校验、文档校验拆分处理按不同校验角色分段完成修复验证问题时只修改当前改动直接涉及的点其它既有问题只记录到质量待办不扩大范围4.4 交付测试全部通过后必须更新本次改动涉及的业务最终状态文档交付说明默认包含改动摘要、验证结果、未覆盖风险、必要后续项不复述完整业务背景和已知失败细节五、单元测试规范摘要完整规则以docs/code-style/unit-tests.md为准代码改动涉及的测试新增、更新、移除和执行统一按单元测试规范处理除非明确提出否则不进行浏览器 UI 测试已记录的既有失败交付时只引用对应记录不重复展开分析六、质量跟进Quality Follow-ups项目维护一个docs/quality/目录专门记录待跟进的质量问题处理需求时如触达已记录的关联模块必须先提示对应待落实项触达关联待办后应同步落实业务逻辑、测试断言和验证结果docs/quality仅记录问题和待跟进项不作为当前需求必须更新的业务文档已落实的最终业务状态应沉淀到docs/design、docs/global-design或docs/components的对应文档中七、文档治理7.1 文档体系项目文档入口docs/README.md用户手册如user-manual/是独立交付目录默认不纳入业务代码或项目文档的改动范围7.2 文档规则处理文档时不得保留中间状态或时间线只保留最终校订时间和最终状态页面、组件和全局能力文档必须能作为工作入口记录涉及文档、源码目录、参考规范和单元测试入口文档治理任务应独立处理不把大范围文档入口补齐混入业务功能改动功能代码完成移除后必须同步处理所有相关文档、入口链接和过期说明业务需求、业务边界和接口资料不得写入项目规则文件应进入业务文档目录八、技术基线示例以下为示例基线团队按实际情况替换层级技术选型框架React 19UI 组件库Ant Design 5语言TypeScript构建工具Vite九、快速落地 Checklist首次引入本规范到项目时按以下清单操作复制AGENTS.md模板到项目根目录同步创建CLAUDE.md、GEMINI.md建立docs/code-style/目录编写src-code/README.md、unit-tests.md、docs.md建立docs/design/、docs/components/、docs/global-design/目录骨架建立docs/quality/目录用于记录质量待办明确技术基线并更新到规范中在团队内宣贯确保所有使用 AI Agent 的成员知晓并遵守十、模板使用说明脱敏替换将本文中所有项目特定的路径、工具名、技术栈替换为团队实际使用的内容粒度调整根据项目规模调整规则粒度。小型项目可精简大型团队可细化分层持续迭代规范不是一成不变的每季度回顾一次根据实际协作痛点更新工具适配如果使用特定的 Agent 工具如特定 IDE 插件、CLI在技术基线章节补充对应约束