多 AI Coding Agent 工程化实践：用 CLAUDE.md + AGENTS.md 建立统一工程约束

基于一个简版内部 AI Agent 开发平台的真实开发经验记录在多 AI Coding Agent 共存的工作流中如何通过分层配置文件建立统一工程约束并让规则进入执行、验证和反馈闭环。一、背景与动机为什么需要统一 Agent 配置1.1 现实痛点如果你同时使用 Claude Code、Qwen Code、zcode、Trae 等多种 AI 编程工具大概率遇到过以下场景用 Claude Code 写了一个模块切到 Qwen Code 继续开发时它完全不知道项目架构边界直接跨模块引用了internal包zcode 帮你生成了一个新的 Adapter但命名规范、异常处理方式与前一个工具产出的代码完全不一致Trae 写的 Git 提交信息和 Claude Code 的格式完全不同提交历史混乱每个工具各自为政你在三个工具里重复解释同一个项目的模块依赖规则根本原因AI 编程工具的上下文是会话级的项目的工程约束却是长期且跨工具的。没有持久化、工具可读的配置层来注入项目上下文每个工具每次启动都从零开始。1.2 项目的解法本文所说的多 Agent主要指多个 AI Coding Agent 在同一代码仓库中的协同开发而不是多个 Agent 通过消息协议进行自主任务编排。该项目是一个简版内部 AI Agent 开发平台采用 Spring Boot 2.7 Vue 3 的模块化单体架构包含多个后端模块和 1 个前端项目。本文重点展示其中 7 个核心模块。在开发过程中我们同时使用了 Claude Code、Qwen Code、Kimi Code、zcode 和 Trae 五种 AI Coding 工具。解法分三层宪法层constitution.md不可绕过的工程原则优先级最高公共层AGENTS.md.agents/rules/.agents/skills/所有工具共享的项目上下文、规则和技能适配层.claude/、.qwen/、.zcode/、.trae/各工具的私有配置引用公共层核心思路同一个规则只在一个地方定义所有工具从公共层读取适配层只做工具特有的扩展如 Claude Code 的 Skills、Qwen Code 的测试 Skill、Trae 的 Git 提交规范。二、CLAUDE.md 实践Claude Code 的项目上下文注入2.1 设计原则精炼入口不重复在本项目中CLAUDE.md 作为 Claude Code 的入口文件。常见误区是把所有规则都塞进去文件膨胀、维护困难。项目的做法是让 CLAUDE.md 保持极简只做三件事声明启动流程、设置行为约束、索引可用技能。入口文件不是知识库而是导航器。# CLAUDE.md Claude Code 私有扩展。项目通用契约见 [AGENTS.md](AGENTS.md)。 ## 会话启动 每次会话开始时 1. 读取 [constitution.md](constitution.md) 了解项目工程宪法 2. 读取 [AGENTS.md](AGENTS.md) 了解项目全貌、模块结构和红线 3. 根据任务类型读取对应 .claude/rules/ 和 .claude/skills/ 4. 遵循 .claude/rules/ 中的行为规范和规则文件 ## 行为约束 - 修改代码前先确认目标模块在依赖矩阵中的位置AGENTS.md §2.2 - 跨模块调用只走 api 包发现违规立即停止 - 不引入技术栈以外的依赖需要时先问用户 - 改完代码后运行受影响模块的编译验证mvn -pl mod-module -am compile ## 可用 Skills | Skill | 触发场景 | |-------|---------| | deliver | 为新模块或新功能执行端到端交付流程 | | api-contract | 设计或变更 RESTful 接口契约 | | new-provider | 接入新的 LLM 供应商适配器 | | writeback | 将本次会话经验回写到规则文档 | | arch-check | 运行架构合规检查 | | new-module | 创建新业务模块脚手架 |30 行的入口文件建立了完整的上下文链条CLAUDE.md → constitution.md → AGENTS.md → .claude/rules/ .claude/skills/。2.2 编码规范约束通过 Rules 文件实现CLAUDE.md 本身不承载具体编码规范这些规则放在.claude/rules/目录下按领域分文件管理。项目有 10 个规则文件规则文件内容大小ai-collaboration.mdAI 编码协作行为指令3.6KBarchitecture.md架构、模块边界、代码组织7.6KBjava-coding.mdJava 编码规范7.0KBapi-contracts.md接口规范、Result 封装、错误码8.6KBdatabase.md数据库字段、索引、分页、pgvector8.9KBexternal-llm.mdLLM/MCP 调用、超时、熔断、重试6.6KBfrontend.md前端设计系统、组件模式7.0KBworkflow.md工作流定义与执行引擎4.2KBdeployment.md部署架构、缓存策略2.6KBconventions.md项目专属行为规范1.4KB以ai-collaboration.md为例它定义了 AI 在编码过程中的行为约束## 精准修改 - 只动必须改的文件和行不顺手优化相邻代码、注释、格式。 - 不重构没坏的东西匹配现有风格。 - 发现无关死代码时告知用户但不私自删除。 - 自己的改动导致 import/变量/方法无用时负责清理。 - 每一行改动都能追溯到用户请求。 - 在既有长链路如 ChatService.sendMessage中增量接入 RAG 等横向能力时 应把变更点收敛到单一方法如 buildMessages()不得扩散到流式调用、 SseEmitter 转发、消息持久化、Redis 上下文管理等已有环节。这条规则针对的痛点很直接AI 修改已有代码时经常顺手优化不相关代码diff 污染严重。2.3 任务分工策略通过 Skills 编码工作流Skills 是 Claude Code 的高级配置用于将重复性的多步骤工作流编码为可复用的技能。项目定义了 6 个核心 Skill其中最重要的是deliver模块交付技能。deliverSkill 将一个新模块从需求到验收的完整流程固化为 6 个阶段每个阶段有明确的产出物、验证方式和决策门禁阶段 1咨询模式梳理 → 产出需求设计文档 → 门禁数据模型确认 阶段 2数据模型设计 → 产出 DDL Flyway migration → 门禁数据模型确认 阶段 3后端分层实现 → Entity → DTO → Service → Controller逐层编译→ 门禁接口契约确认 阶段 4后端验证 → mvn test ArchUnit curl → 门禁后端完成确认 阶段 5前端对接 → API 文件 页面 路由 菜单 → 门禁前端方案确认 阶段 6完整验收 → curl 浏览器全流程 → 门禁最终验收确认每个门禁点都要求 Claude Code 输出等待用户确认并停止执行避免 AI 一口气写完所有代码才发现方向错了。还有一个 Skill 叫writeback经验回写它不是开发技能而是一个元技能。当会话中发现了可复用的经验或踩坑教训时触发回写流程将经验沉淀到规则文件中## 判断标准 只有同时满足以下条件才允许回写 1. 这是稳定规律不是一次性偶发细节。 2. 它能明显降低未来重复犯错概率。 3. 它适合写成规则、检查点或操作约束。 4. 仓库现有文档中尚未明确表达这一点。 5. 规则可以被后续 Agent 验证或执行而不是口号。 如果不满足以上条件明确告诉用户本次不建议经验回写并说明原因。此外.claude/settings.json还配置了 PreToolUse/PostToolUse Hook在编辑前后自动拦截敏感文件和运行验证.claude/agents/下有 architecture-reviewer 和 api-contract-reviewer 两个子 Agent在开发过程中被主 Agent 调用执行审查。这些机制的分工不同可以用一张表概括机制核心问题示例AGENTS.md项目是什么、有哪些红线模块依赖矩阵Rule应该遵守什么禁止跨模块 internalSkill怎么完成一类任务deliver 6 阶段Hook什么时候自动触发post-edit 运行测试Sub-Agent谁负责专项审查architecture-reviewerTest有没有真正做对ArchUnit三、AGENTS.md 实践跨工具共享的项目级契约3.1 设计思路一份文件多工具消费在本项目中我们将 AGENTS.md 作为跨工具共享的项目级 Agent 约束入口承载模块边界、依赖矩阵、红线规则和构建命令。对于不原生消费 AGENTS.md 的工具通过各自的适配层桥接。AGENTS.md 是项目级事实源Project Contract.agents/rules/是领域规则的规范源Domain Rules各工具目录中的规则文件属于适配副本或工具特有扩展。3.2 依赖矩阵用表格约束 AI 的代码修改项目采用模块化单体架构9 个模块之间有严格的依赖方向。AGENTS.md 中用表格定义哪些模块可以依赖哪些模块| 依赖方 \ 被依赖方 | provider | mcp | knowledge | agent | chat | workflow | common | |---|---|---|---|---|---|---|---| | mod-provider | - | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | mod-mcp | ❌ | - | ❌ | ❌ | ❌ | ❌ | ✅ | | mod-knowledge | ❌ | ❌ | - | ❌ | ❌ | ❌ | ✅ | | mod-agent | ✅ | ✅ | ✅ | - | ❌ | ❌ | ✅ | | mod-chat | ✅ | ✅ | ✅ | ✅ | - | ❌ | ✅ | | mod-workflow | ✅ | ✅ | ✅ | ✅ | ✅ | - | ✅ |配合 CLAUDE.md 中的行为约束修改代码前先确认目标模块在依赖矩阵中的位置AI 工具修改mod-agent时会先查表发现需要调用chat的功能就知道是架构违规停下来向用户报告。矩阵的使用方式AI 工具在编辑任何跨模块代码之前先查这张表确认依赖方向。如果当前模块在矩阵中对应行为 ❌说明不允许依赖立即停止修改并报告。这张表放在 AGENTS.md 而不是藏在某个规则文件里是因为它是最高频使用的约束——每次跨模块修改都要查一次。.agents/rules/是规范源.claude/rules/是同步副本通过脚本或手动保持一致。3.3 红线机制从口号到可执行约束红线不是写在文档里看的要有自动化验证兜底## 4. 关键红线必须遵守 1. **禁止跨模块引用 internal 包中的任何类** 2. **api 包只能依赖 mod-common 与 JDK**禁止依赖本模块 internal、Spring、MyBatis-Plus、数据库实体 3. **循环依赖视为架构错误**必须下沉公共抽象到 mod-common 4. **mod-common 不是垃圾桶**只放跨模块共用抽象不放业务逻辑 5. **Service 禁止直接返回 Entity 给 Controller**必须经过 converter 转换为 DTO 6. **LLM 调用必须走独立线程池**具备超时、熔断、降级与结果日志 7. **数据库表必须包含** id、created_at、updated_at、deleted 四个字段主键用自增 BIGINT 8. **对话记录分页必须使用游标分页**禁止深分页 LIMIT offset, size 9. **所有外部调用必须配置超时**所有配置项必须外化到 application.yml 10. **代码提交前必须通过 ArchUnit 架构测试**禁止合并破坏模块边界的代码。每条红线的验证方式分三级红线RuleAgent ReviewMachine Gate#1-4 模块边界✅✅✅ ArchUnit#5 Service 返回 DTO✅✅⚠️ 部分覆盖#6 LLM 线程池✅✅❌#7 数据库四字段✅❌⚠️ Flyway 检查#8 游标分页✅✅❌#9 配置外化✅❌⚠️ pre-edit hook#10 ArchUnit 测试✅❌✅ mvn test没有 Machine Gate 兜底的红线只是建议。3.4 宪法层更高优先级的工程原则在 AGENTS.md 之上还有一份constitution.md工程宪法定义了四条不可绕过的核心原则。这是本项目的工程治理模型不是 Claude Code 或 AGENTS.md 的标准机制思考先于编码简单优先显式思考、YAGNI、最小抽象、依赖克制精准修改纪律执行精准修改、Red-Green-Refactor、ArchUnit 门禁LLM 与外部调用治理线程隔离、超时必配、成本控制、不伪装成功安全与数据完整性无默认凭证、显式异常处理、数据基线、分页纪律优先级链条明确写在宪法中宪法 AGENTS.md 红线 .claude/rules/规则文件 个人偏好当用户要求的方案与 AGENTS.md 建议冲突时按宪法优先级处理。宪法同时规定当前会话中用户明确给出的边界和目标优先于默认流程在规则刚性和用户意图之间留了弹性。多工具场景下的冲突处理当 Claude Code 和 Qwen Code 对同一规则的理解不一致时以 AGENTS.md 为准。AGENTS.md 是项目级事实源所有工具的规则文件.claude/rules/、.qwen/rules/都从.agents/rules/同步确保各工具规则一致。本项目已采用 constitution.md 作为治理层对于尚未建立治理层的项目可以在 AGENTS.md 之上进一步引入。五、实战案例Agent 管理模块交付以mod-agent模块交付为例看 CLAUDE.md 和 AGENTS.md 在实际开发中怎么被使用。任务Agent 模块管理模型 提示词 参数 工具 知识库的组合配置关联model_config多对一、mcp_tool多对多、knowledge_base多对多。阶段 1-2需求梳理 数据模型Claude Code读取 CLAUDE.md 会话启动流程 AGENTS.md 依赖矩阵触发deliverSkill读取 AGENTS.md 依赖矩阵确认mod-agent只能依赖mod-provider、mod-mcp、mod-knowledge、mod-common。产出需求设计文档 → 编写 DDL Flyway migration →post-edit.sh自动运行 ArchUnit 测试验证包路径。两个门禁点确认后进入后端实现。阶段 3后端分层实现Claude Code读取 .claude/rules/architecture.md AGENTS.md 红线Kimi Code读取 AGENTS.md 红线规则按 Entity → Mapper → DTO → Converter → Service → Controller 逐层编码每层编译通过再进下一层。Service 层实现时切换到 Kimi Code 做代码审查发现一处 Service 直接返回 Entity 给 Controller红线 #5提示修复。Controller 完成后调用architecture-reviewer子 Agent 确认没有跨模块internal引用。阶段 4后端验证Claude Code读取 AGENTS.md 构建命令Qwen Code读取 AGENTS.md 规则索引 .agents/rules/ 测试相关规则mvn -pl mod-agent -am compile ArchUnit 测试通过后切换到 Qwen Code 触发integration-testSkill读配置 → 输出测试清单 → 确认 Mock 策略 → 逐场景写测试 → 跑测试处理失败。阶段 5前端对接Claude Code读取 .claude/rules/frontend.md创建web/src/api/agent.ts和页面组件。post-edit.sh自动运行vue-tsc --noEmit类型检查。npm run build验证路径三对齐。阶段 6完整验收Claude Code读取 AGENTS.md 验收标准Trae读取 .trae/rules/git-commit-message.mdcurl 用例 浏览器全流程产出验收报告。用 Trae 生成 Git 提交信息【新增】规范。经验回写zcode读取 .agents/rules/database.md 现有规则交付完成后用 zcode 触发rules-writebackSkill将踩坑经验回写到.agents/rules/database.md。整个流程中各工具共享同一份 AGENTS.md 和.agents/rules/确保架构边界、编码规范、红线约束一致。切换工具时不需要重新解释项目上下文新工具从公共层配置自动继承所有约束。六、经验总结1. 三层分离单一来源配置体系分三层宪法 公共层 适配层。工程原则写在constitution.md项目约束写在AGENTS.md.agents/rules/工具适配写在.claude/、.qwen/等目录。同一个规则只在一个地方定义其他地方引用或同步。常见坑规则文件写了但代码中已经存在违规AI 工具读到规则后反而困惑。规则文件必须与代码现状一致发现不一致时优先更新文档。2. 入口精炼规则分文件入口文件CLAUDE.md、QWEN.md保持在 30-50 行只做启动流程声明、行为约束和技能索引。具体规则按领域分文件管理按需加载。常见坑一开始把所有规则都写进 CLAUDE.md文件膨胀到 500 行每次会话启动都全量注入浪费上下文窗口。3. 红线必须有自动化验证兜底10 条关键红线有效不是因为在文档里写了而是每条都有对应的验证机制。验证分三级RuleAGENTS.md / rules、Agent ReviewReviewer Agent、Machine GateArchUnit / CI。没有 Machine Gate 兜底的红线只是建议。反模式哪些规则不应该写进 Agent 配置不稳定信息如当前线上版本是 v2.3.1很快过期一次性任务如本次需求必须修改 xxx.java不能写进长期规则无法验证的口号如写高质量代码Agent 很难执行过度细化的实现规则如所有 Service 方法必须不超过 30 行没有实际工程价值只会增加约束噪音规则冲突同一行为在不同 Rule 文件中出现相互矛盾的要求。例如architecture.md要求 Service 不允许直接调用 Repository但legacy.md又允许某历史模块例外。规则治理不仅是编写更是优先级、作用域和冲突检测。规则应该满足价值 上下文成本 冲突成本 维护成本。追求少量核心红线 按需加载领域规则 自动化验证兜底。经验回写闭环开发 → 发现问题 → 判断是否可泛化 → 提炼规则 → Rule Writeback → 自动验证 → 下一次 Agent 执行 → 减少重复错误这个闭环让项目规则持续进化而不是一次性写完就过时。安全门槛经验回写建议默认进入候选规则状态经人工审核后再进入正式规则禁止 Agent 在未经确认的情况下直接修改高优先级红线或宪法层规则。这篇文章的核心不是教大家怎么配置 CLAUDE.md而是当一个项目同时使用多个 AI Coding Agent 时如何建立统一的工程契约并让规则真正进入执行、验证和反馈闭环。本文提到的 CLAUDE.md 和 AGENTS.md 模板已整理需要的朋友关注公众号后发送CLAUDE.md 与 AGENTS.md即可获取。