Agent 写的代码总不合团队规范，问题可能出在少了一份规则文件
Agent 写的代码总不合团队规范，问题可能出在少了一份规则文件
先明确一件事：Agent 不是猜不到你的意图，它只是不知道你团队那些没写进代码里的约定——单测怎么跑、提交信息长什么样、哪些目录不许跨层引用。极狐GitLab Duo 支持用两份规则文件把这些约定固定下来：
chat-rules.md只对极狐GitLab 生效，适合个人偏好和团队标准；AGENTS.md是跨工具的共享规则，适合项目上下文、monorepo 组织和目录级约定。两者可以同时存在，Duo 会把所有可用规则文件里的指令都应用上。
为什么同一个 Agent，在别人仓库里很懂事
一个很常见的场景：团队把 Duo 的开发者流程接进项目，第一个合并请求看起来还不错，第二个开始跑偏——测试用错了框架、提交信息写成了一句话、新写的 service 直接引了 controller 层的工具函数。
换个人来问同样的问题，Agent 又答得很对。差别不在模型，在上下文里有没有那些「不用说也知道」的东西。
人类新同事入职，前两周是靠人带：老员工顺口说一句「我们跑测试用 make test-unit，别直接 pytest」「提交信息按 Conventional Commits 写」。这些信息有个共同特点——它们不在代码里，但在每次提交里都要用到。
Agent 没有这两周。它能读到整个仓库，但读不出「惯例」：仓库里有三套测试入口，它不知道哪套是权威的；提交历史里有两种消息格式，它不知道哪种是新标准；monorepo 下面每个子项目各有一套 lint 配置，它不知道该按就近的那份来。
于是它只能做一个统计意义上的合理选择——用最通用的写法。通用写法在单个文件里永远是对的，在团队里永远是错的。
这就是规则文件要解决的问题。它不是一个「提示词技巧」，而是把口头约定变成仓库里可评审、可版本化、可继承的资产。
第一步：把约定写进 AGENTS.md
AGENTS.md 放在仓库根目录，用 Markdown 写，Duo 的开发者流程、内置任务流、自定义任务流都会把它作为上下文读取。官方建议记录的内容包括：测试命令、代码检查规则、提交格式、编码模式。
一份能用的 AGENTS.md 不需要写得像规范文档，关键是命令可复制、边界可判断：
# 项目约定
## 技术栈
- 后端：Go 1.22，框架 gin；前端：React 18 + TypeScript strict
- 包管理：后端 go mod，前端 pnpm（禁止 npm / yarn）
## 提交前必须通过
- 单测：`make test-unit`（不要直接 `go test ./...`，会漏 build tag）
- 静态检查：`make lint`（golangci-lint + eslint）
- 生成代码：改了 `api/*.proto` 后必须执行 `make proto` 并提交产物
## 编码约定
- 错误处理统一用 `pkg/errors` 包装，禁止裸 `fmt.Errorf`
- 数据库访问只允许出现在 `internal/repo/`，其他层通过接口调用
- 新增接口必须同步更新 `docs/openapi.yaml`
## 提交信息
Conventional Commits：`feat|fix|refactor|docs|test|chore(scope): subject`
subject 不超过 72 字符，正文说明「为什么」而不是「改了什么」这份文件的写法有两个要点。
一是写「不要什么」，不只写「要什么」。 上面 make test-unit 那条特意补了括号里的原因——因为直接 go test ./... 也能跑通，只是会漏掉带 build tag 的集成测试。Agent 不知道这个差别，但知道了原因之后，它在遇到变体场景时也更可能做对选择。
二是把可验证的命令写全。 「跑一下测试」这种描述对人和对 Agent 都等于没说。写成具体命令，Agent 才能在流程里真正执行，而不是凭想象生成一个测试文件就交差。
第二步：分清 chat-rules.md 和 AGENTS.md 的分工
两份文件都能写规则，但定位不同。官方给出的区分很清楚：
chat-rules.md（自定义规则）：只对极狐GitLab 生效，适合个人偏好和团队标准。AGENTS.md（共享规则）：适用于极狐GitLab 以及其他支持 AGENTS.md 规范的 AI 工具，适合项目上下文、monorepo 组织和特定目录的约定。
这个区分直接决定了内容该放哪边：
内容类型 | 放哪 | 理由 |
|---|---|---|
「我不喜欢用 tab 缩进」 | chat-rules.md | 个人偏好，不该影响别人 |
「本仓库所有新接口必须同步 openapi.yaml」 | AGENTS.md | 项目约束，换任何 AI 工具都成立 |
「后端用 Go，禁止引入 CGO 依赖」 | AGENTS.md | 项目事实，其他工具同样需要 |
「回复我时先给结论再给理由」 | chat-rules.md | 交互偏好，是个人习惯 |
判断标准可以简化成一句话：换一个 AI 编程工具进来，这条规则还应不应该生效？ 应该，写 AGENTS.md；只对我自己的对话有用，写 chat-rules.md。
两者同时存在时，Duo 会应用所有可用规则文件中的指令。所以不要把同一条规则抄两份——将来改了一处忘了另一处，冲突时你很难解释 Agent 为什么选了旧的那条。
第三步：monorepo 用目录级约定，别写一份大而全
单仓多服务的团队最容易踩的坑，是把十几个服务的规则全塞进根目录一份 AGENTS.md。结果是六千字的规则文件，Agent 每次都要读，读完了还是不知道当前改的这个服务该用哪套。
AGENTS.md 支持目录级约定，这正好对上 monorepo 的结构：根目录只放全局不变的部分（提交格式、禁止事项、可用命令），各子项目目录下放自己的规则。
repo/
├── AGENTS.md # 全局：提交格式、禁止 CGO、PR 模板要求
├── services/
│ ├── order/
│ │ └── AGENTS.md # 本服务：DDD 分层、事件命名、禁止跨聚合查询
│ └── payment/
│ └── AGENTS.md # 本服务：金额必须用 decimal、禁止浮点、幂等键规范
└── web/
└── AGENTS.md # 前端：组件目录结构、状态管理只允许 zustand这样写的另一个好处是评审成本。规则文件在仓库里，改动走合并请求，谁改了哪条约定、为什么改，全都有记录。比起散落在群公告和口头传达里的「我们一般不这么写」，这份文件至少能在评审时被人指出来。
第四步：规则之外，还要给它一个能跑的环境
规则解决「该怎么做」，环境解决「能不能做」。官方在开发者流程的配置建议里把这两件事并列写：除了添加 AGENTS.md 记录项目约定，还建议用 agent-config.yml 配置代理执行环境，把工具链装好。
如果项目需要特定工具链（Go、Python、Node.js 等），只在 AGENTS.md 里写「记得跑测试」是不够的——环境里没有对应的运行时，Agent 要么跳过验证，要么跑出一个必然失败的结果。配置好执行环境之后，它才能在提交前真正运行测试、验证自己的改动。
# agent-config.yml
image: golang:1.22
setup_script:
- apt-get update && apt-get install -y make protobuf-compiler
- go mod download
- make proto
cache:
- key: gomod
paths:
- /go/pkg/mod这一步的投入产出比往往被低估。规则文件能把 Agent 的输出质量从「看着像」拉到「能用」，执行环境决定它能不能自己发现「不能用」。
几个容易踩的坑
坑一：把 AGENTS.md 写成愿望清单。 「代码要优雅」「注意性能」这类描述对 Agent 没有任何约束力，它的作用是让输出看起来更认真，不是更正确。能落地的规则都长这样：一条命令、一个路径、一个格式模板。
坑二：规则和 CI 打架。 AGENTS.md 里写「提交前跑 make lint」，但 CI 里跑的其实是 golangci-lint run ./... --config .golangci-strict.yml，两套配置严格程度不同。Agent 按前者自检通过，推上去照样红。规则文件里的命令必须和 CI 里的完全一致，最好直接引用同一份 Makefile 目标。
坑三：忘了规则是上下文，不是执行器。 规则文件影响的是 Agent 的判断，不是强制门禁。它不会阻止有人绕过流程直接推代码，也不会替你拦下不合规的合并请求。真要拦，还是得靠分支保护、推送规则、必需审批这些机制——规则文件管「让 Agent 做对」，门禁管「不让人做错」，两件事不能互相替代。
坑四：写完就不管了。 团队换了测试框架、改了目录结构，规则文件还是半年前的版本，Agent 会严格地按过时约定办事，而且比人更「自信」。把它当代码看待：改架构的时候顺手改规则，评审时一起看。
常见问题
Q：AGENTS.md 会覆盖 CI 里的配置吗？
不会。它是给 Agent 读的上下文，不参与流水线执行，也不会改动项目设置。它唯一的作用是让 Agent 在生成代码、写提交信息、选择命令时参考你的约定。
Q：团队用的是别的 AI 编程工具，这份文件还有用吗？
AGENTS.md 走的是跨工具规范，支持该规范的 AI 工具都能读。这也是它比 chat-rules.md 更适合放「项目级约定」的原因——规则只写一份，换工具不用重写。
Q：规则写多细比较合适？
按「一个新同事看完能不能照做」这个标准。能写出命令和路径的写到命令和路径，写不出来的（比如「代码风格要统一」）就先别写，交给 lint 去管。
下一步
如果你已经在用极狐GitLab Duo 的开发者流程或任务流，可以在项目根目录先加一份最小可用的 AGENTS.md：把测试命令、lint 命令、提交格式三条写清楚，跑一周看看合并请求的返工率有没有变化。这份文件不需要一次写全，它应该随着评审意见一点点长出来。
更多关于 Duo 上下文与自定义规则的说明，可以查阅极狐GitLab 文档中心的 Duo Agent Platform 章节。
