AI Coding 如何在团队落地？建设一套经得住人员、工具和时间变化的规范

周一早晨：一个代码库里出现了四个版本的“项目真相”

同一个团队用四种方式开发同一个项目：

• 一位开发者使用 Cursor，把重要规则放在 .cursor/rules/；
• 另一位使用 Codex，主要遵循 AGENTS.md；
• 第三位使用 Claude Code，维护了一份很长的 CLAUDE.md；
• App 开发者六周前把构建命令复制进了自己的私人 Prompt。

后来，项目更换了测试命令，还增加了一条新的模块边界。项目文档更新了，但两份 AI 指令文件和那段私人 Prompt 没有更新。

接下来的三个 Pull Request 看起来都挺合理：

• 一个人运行了已经覆盖不到当前模块的旧测试命令；
• 一个人引用了架构已经禁止访问的内部模块；
• 一个人正确修改了代码，却让项目文档继续描述旧行为。

问题不在于团队选错了模型，而在于团队没有共享的工程契约。每种工具都在依据不同时间、不同来源的项目快照工作。

本文要建设的就是这份契约。读完后，你会得到一套可以实际执行的方法，用来：

1. 在支持多种 AI Coding 工具的同时，只维护一个项目事实源；
2. 根据可验证能力而不是职级，为同事分配不同程度的自主权；
3. 在不同人员、会话和工具之间安全交接工作；
4. 把重要的自然语言规范变成可执行检查；
5. 让项目文档随着代码和开发方式一起持续演进。

目标不是要求每位开发者用同一种方式使用 AI，而是让每一个最终被接受的修改都满足同一份项目契约。

一、先建立正确模型：一份项目契约，五个实现层次

很多团队从写一份很大的 AGENTS.md 开始。它有用，但它还不是团队体系。一套可持续的体系应该明确分成五层。

必须分层，是因为每一层的失败方式不同：

• 项目文档可能过期；
• Agent 可能误解一条写得很清楚的指令；
• 当前任务可能缺少关键决定；
• 测试可能遗漏重要行为；
• Review 意见可能随着 PR 关闭而消失，没有改善系统。

不要指望一个文件同时解决五种问题。

用这个问题检验设计是否合理

假设下个月团队替换了所有 AI Coding 工具，哪些东西必须留下？

• 架构与产品决定；
• 构建和测试方法；
• 任务验收条件；
• 数据、权限与安全边界；
• 验证证据；
• 过去失败留下的经验。

这些资产应该存在于仓库和交付体系里，不能只存在于某个厂商工具的 Memory 中。

二、把代码库建设成团队的共享记忆

先建立一套普通、容易发现的目录。一个中等规模项目可以这样组织：

repository/
├── README.md
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── .cursor/
│   └── rules/
│       └── 00-project-contract.mdc
├── docs/
│   ├── project-map.md
│   ├── development.md
│   ├── testing.md
│   ├── architecture/
│   │   ├── boundaries.md
│   │   └── decisions/
│   └── ai/
│       ├── tool-compatibility.md
│       ├── task-template.md
│       ├── review-checklist.md
│       └── evals/
├── .github/
│   ├── CODEOWNERS
│   └── pull_request_template.md
└── scripts/
    └── verify-ai-contract.sh

文件名可以变化，每类文件承担的职责不应该混乱。

AGENTS.md 应该是索引，不是百科全书

根目录指令文件只保留那些几乎会影响每一次 Agent 执行的内容：

# Repository working contract

## Start here
- Read `docs/project-map.md` to locate the owning module.
- Read the nearest `AGENTS.md` before editing a nested package.
- Read `docs/architecture/boundaries.md` before crossing package boundaries.

## Required workflow
1. Restate the task outcome, allowed scope, and unknowns.
2. Reproduce or characterize current behavior before changing code.
3. Make the smallest coherent change.
4. Run the focused checks, then the owning package checks.
5. Report changed files, commands, results, and remaining risk.

## Commands
- Install: `<verified-install-command>`
- Focused test: `<verified-focused-test-command>`
- Package verification: `<verified-package-command>`
- Repository checks: `<verified-repository-command>`

## Boundaries
- Do not change public contracts, stored data, permissions, dependencies, or release configuration implicitly.
- Do not use production data or credentials.
- Stop when the task conflicts with an architecture decision or requires another owner's approval.

## Definition of done
- Acceptance criteria are met.
- Required checks pass.
- Documentation changes with behavior, commands, architecture, or operator workflow.
- The handoff states what was not verified.

详细架构不应该全部塞进这个文件，已经被 Formatter 或 Linter 强制执行的几百条规则也不应该重复一遍。

2026 年 6 月，一项针对 100 个热门开源仓库的研究发现，Agent 指令文件中反复出现 Lint 规则重复、上下文膨胀、流程放错位置、引用过期和指令冲突等问题。这仍是新研究，不能当成普适定律，但它支持一条很实用的原则：常驻指引应保持精简，通过链接指向有人负责的文档和可执行检查，不要复制它们（Configuration Smells in AGENTS.md Files）。

让每份长期文档带有四个属性

重要文档应该明确展示：

Owner: @team-or-role
Applies to: apps/web, apps/mobile
Last verified: 2026-08-17
Verify with: ./scripts/check-project-docs.sh

Last verified 不是装饰性的更新时间。它应该表示有人对照当前仓库检查过文档，或者运行过这里列出的验证证据。

三、每一种信息究竟应该放在哪里？

文档失控通常始于同一条有用信息被复制进每一种 AI 配置文件。可以用下面的归档规则避免它。

每次准备增加一条规则，都先问：

如果换一种工具，或者换一位同事执行同类任务，这件事是否仍然必须成立？

如果答案是“必须”，它应该进入项目契约或可执行控制；如果答案是“不一定”，它才可能属于工具适配或个人配置。

四、支持多种工具，但不要维护多个版本的项目

不同工具读取项目指令的方式并不一样。

• Codex 会从项目根目录向当前工作目录逐层发现 AGENTS.md，更近目录的指引在指令链中出现得更晚（Codex 官方 AGENTS.md 指南）。
• Claude Code 使用 CLAUDE.md；当前官方文档明确建议，在仓库已经使用 AGENTS.md 时，从 CLAUDE.md 中导入它（Claude Code Memory 文档）。
• Gemini CLI 默认使用分层的 GEMINI.md，支持导入其他文件，也可以把 AGENTS.md 配置为上下文文件名（Gemini CLI 上下文文档）。
• Cursor 支持 Project Rules 和 AGENTS.md，但编辑器和 CLI 等不同入口的具体行为可能不同；GitHub Copilot 也专门发布了支持矩阵，因为 Chat、Coding Agent、Code Review、不同 IDE 和 CLI 并不会加载完全相同的指令类型（Cursor Rules、GitHub 自定义指令支持矩阵）。

所以，答案不是“选出最好的文件名”，而是：

维护一份项目契约，让每个工具的适配文件保持轻量、明确并且可以验证。

轻量适配文件应该长什么样？

CLAUDE.md 可以导入共享契约，只补充 Claude Code 独有的行为：

@AGENTS.md

## Claude Code adapter
- Use plan mode before a change spans more than one owned package.
- Project facts and definition of done come from `AGENTS.md` and `docs/`.
- Do not store team decisions only in auto memory; propose a repository document change.

Gemini CLI 可以通过项目配置直接加载共享文件名：

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Cursor 的 Project Rule 也可以刻意保持很短：

---
description: Load the canonical project contract before implementation
alwaysApply: true
---

Read `AGENTS.md` and the linked project documents before editing.
Cursor-specific workflows may be defined here; project requirements may not.

除非某个工具完全没有导入或共享文件机制，否则不要生成四份完整副本。如果确实只能复制，就从同一个事实源自动生成适配文件，并在生成结果漂移时让 CI 失败。

维护一份工具兼容性记录

创建 docs/ai/tool-compatibility.md：

当工具版本、使用入口、指令格式或项目适配变化时，重新检查这张表。“厂商说支持 AGENTS.md”并不能证明团队实际使用的那个入口真的加载了预期文件。

五、让每个任务都带着一份可以跨工具传递的契约

一位同事应该能够把任务从 Cursor 转到 Codex，或者交给使用 Claude Code 的同事，而不需要从聊天记录中重新拼出任务目标。

可以使用下面这份任务封装：

# Change request

## Outcome
What should a user, operator, or developer observe when this is complete?

## Context to read
- `AGENTS.md`
- `<owning-module-document>`
- `<relevant-decision-or-spec>`

## In scope
- named behavior
- allowed packages or components

## Out of scope
- contracts, platforms, migrations, or cleanup not included in this task

## Acceptance evidence
- observable behavior
- focused automated check
- owning-package regression checks
- documentation that must remain accurate

## Autonomy lane
- read only / plan only / branch implementation / expert-approved implementation

## Stop conditions
- missing decision
- boundary crossing
- sensitive data or permission required
- unexpected unrelated failure

## Handoff
- base commit and resulting commit
- files changed
- commands and actual results
- decisions made
- unresolved risks and recommended next owner

这份任务契约刻意不绑定工具。产品、设计、Web、服务端和 App 开发可以理解同一个结果，各自再提供本专业需要的验证证据。

一个贯穿全文的例子：修改产品术语，但不破坏公共契约

假设产品要把用户看到的 Project 改成 Workspace。

一条糟糕的任务是：

把所有 Project 全部替换成 Workspace。

一份安全的任务契约会这样写：

结果
Web 和 App 用户在导航、空状态和校验提示中看到“Workspace”。

范围内
- apps/web 和 apps/mobile 的用户可见文案
- 被修改状态对应的 Snapshot 或 UI 测试
- 产品术语表和用户文档中的截图

范围外
- project_id 等公共 API 字段
- 数据库名称、埋点事件名与迁移工作
- 无关的内部类名

验收
- 指定流程中不再出现用户可见的“Project”
- Web 与 App 的针对性检查通过
- 公共契约没有改变
- 术语表和受影响用户文档使用“Workspace”

这份契约把用户结果与实现边界分开，因此不同技术方向都能使用。它也让“全局搜索替换”这个危险捷径变得明显不合法。

六、根据能力证据、任务风险和工具熟悉度分配自主权

“初级开发不能用 Agent”过于粗暴，“所有人都能用全部功能”又不安全。

能力应该是一张矩阵，不是永久等级。同一个人在熟悉的 Web 模块里可以独立工作，在不熟悉的 App 模块里需要监督，刚换用一种新工具时则可能只适合 Plan-only。

按工作流验证能力，不要只让同事看产品演示

在允许同事用一种新工具直接修改分支前，让他完成四个可观察动作：

1. 展示工具实际加载了哪些项目指令；
2. 为一个样例任务找到正确负责人和验证命令；
3. 完成一次不越界的有边界修改；
4. 产出另一位同事可以复现的交接报告。

任何一步失败时，不仅要培训这个人，也要检查仓库和适配文件。新人上手失败，往往同时暴露了项目文档的问题。

个人配置不能削弱项目契约

可以允许个人设置解释深度、快捷键、本地 Alias 或自己喜欢的计划方式，但不能允许本地文件暗中覆盖：

• 必须运行的测试；
• 架构边界；
• 数据与权限规则；
• Review 要求；
• Definition of Done。

当工具会合并全局、项目和本地指令时，必须验证最终生效内容。除非产品文档和实际测试都能证明，否则不要想当然地认为“项目规则优先”。

七、把重要文字规范变成可执行护栏

指令文件只是上下文，不是强制控制。Claude Code 官方文档明确说明了这一点，GitHub 也提醒自定义指令不一定每次都以完全相同的方式得到遵循。2026 年的研究则把这个问题描述为需要用可执行控制弥补的“被动指令”（Claude Code Memory、GitHub 自定义响应、ContextCov，2026）。

对 AGENTS.md 里的每条重要要求，都问一句：它是否需要一个可执行的“双胞胎”？

GitHub 受保护分支可以要求状态检查成功和人工批准，CODEOWNERS 可以为匹配路径自动请求并强制责任团队评审（Protected Branches、CODEOWNERS）。其他代码托管平台也有对应机制。

不要只设一个总权限开关，应该划分操作通道

OWASP Agentic Applications Top 10 2026强调了工具滥用、身份与权限滥用、意外执行和供应链风险。实际对策是缩小工具、身份和执行环境，在高影响操作前保留人工检查点，而不是继续往 Prompt 里增加一句“请小心”。

八、让项目文档跟着项目一起变化

“请记得更新文档”不是工作机制。团队需要定义更新触发条件。

在 Pull Request 模板中加入：

## Project contract impact
- [ ] Behavior or acceptance changed; affected docs are updated.
- [ ] Commands, package boundaries, or ownership changed; project guidance is updated.
- [ ] AI instruction files or adapters changed; supported tools were rechecked.
- [ ] No durable decision exists only in a chat transcript or personal memory.

给 AI 相关文档指定负责人

例如：

/AGENTS.md                       @platform-team @repo-maintainers
/CLAUDE.md                       @platform-team
/GEMINI.md                       @platform-team
/.cursor/rules/                  @platform-team
/docs/ai/                        @ai-practice-stewards
/docs/architecture/              @architecture-owners

负责人对正确性负责，不代表每句话都要亲自写。AI 可以起草更新，但最终接受这份项目契约的人必须是资产 Owner。

让每次失败至少改善一项长期资产

使用下面这条 Review 规则：

第一次出现  → 修好当前任务并保留证据
形成重复模式 → 找出缺失或薄弱的系统资产
修改系统    → 只更新一个事实源或可执行控制
验证修改    → 重跑最小的相关历史案例

不要把每条 Review 意见都塞进 AGENTS.md，应该选择正确资产：

• 缺少项目事实 → 项目文档；
• 任务边界不清 → 任务模板；
• 确定性违规 → 测试或 CI；
• 工具独有行为 → 工具适配；
• 可重复流程 → Skill 或脚本；
• 模型/工具回归 → 评估案例。

OpenAI 当前的评估最佳实践建议开展贴近任务的持续评估，保留日志，并用人工判断校准自动评分。对于这套团队体系，评估对象应该包含仓库快照、任务契约、指令版本、工具入口、权限、执行命令和 Review 结果，而不只是模型名称。

九、不同人员和工具怎样协作完成同一个修改？

回到 Project → Workspace 这个例子。

第一步：由一个负责人发布任务契约

Issue 写清用户结果、指定的 Web 和 App 流程、受保护的公共契约、必须更新的文档与验证命令，并引用一个基准 Commit。

第二步：由经验较少的同事先做影响面分析

他使用 Cursor 的 Plan-only 模式，产出：

受影响的 Web 路径
受影响的 App 路径
相关术语表和截图
可能命中、但绝不能修改的公共契约
未知负责人或缺失测试

维护者确认影响面并拆分工作前，不开始实现。

第三步：两位贡献者在隔离范围内工作

• Web 开发者使用 Codex，在 Web Worktree 中工作；
• App 开发者使用 Claude Code，在独立分支中工作；
• 两人拿到同一份任务契约和基准 Commit；
• 两人都不能修改公共 API，也不能进入对方模块。

工具不同没有关系，因为契约、边界和证据形式是共享的。

第四步：每次交接都必须可以长期保存和复现

每位贡献者都要报告：

任务与基准 Commit
选择的修改范围
修改文件
针对性与模块级检查的实际结果
已更新文档
执行过程中做出的决定
尚未验证的行为与剩余风险
最终 Commit 或 Pull Request

只有聊天总结，没有 Commit、Diff 或可复现命令，不算完成交接。

第五步：由 CI 和 Owner 集成结果

CI 检查指定流程中的文案、Web 和 App 测试、公共契约 Snapshot、文档链接和适配文件漂移；CODEOWNERS 把 Web、App 和术语表修改交给对应 Reviewer。

第六步：必要时让 Review 改善整个系统

假设两种工具都试图修改 project_id。任务边界已经足够清楚，重复犯错说明可执行边界太弱。团队应该增加契约 Snapshot 或禁止 Diff 检查，并把这项任务保存成评估案例。

这才是可持续协作：同一种失败下次出现时，处理成本应该更低。

十、看起来很规范、实际却会失败的设计

十一、用一周建设最小可用体系

第一天：盘点现在有哪些“项目真相”

• 列出项目文档和所有 AI 指令文件；
• 按具体使用入口列出工具，而不只记录厂商名称；
• 找出重复、冲突、只存在于个人电脑和已经过期的规则；
• 确认主要项目区域真实有效的命令和负责人。

第二天：建立唯一项目契约

• 创建或修复项目地图、开发指南、测试指南和架构边界；
• 把 AGENTS.md 缩减为导航、必要流程、命令、边界和 Definition of Done；
• 把一次性任务说明从长期规则中移走。

第三天：让工具适配足够薄

• 导入或引用唯一项目契约；
• 记录准确的工具入口和版本；
• 在每一种受支持工具中检查实际生效指令；
• 删除已经没有存在理由的规则副本。

第四天：强制执行代价最高的规则

• 保护默认分支；
• 要求针对性和模块级检查；
• 为架构、公共契约、AI 指引和项目文档指定 Owner；
• 限制外部写入和生产操作；
• 把代价最高的一条重复 Review 意见变成自动检查。

第五天：演练一次真实协作

• 让观察者完成任务影响面分析；
• 让有边界的贡献者实现其中一个范围；
• 使用长期交接格式，在两种不同工具之间传递任务；
• 记录每个缺失事实、模糊边界和无法复现的命令；
• 扩大自主权之前，先修好暴露出来的系统问题。

此后应该由证据触发体系复查，而不是只因为日历上出现了一场季度“AI 规范会议”。

十二、团队验收清单

能够肯定回答下面这些问题时，这套团队 AI Coding 体系才适合扩大使用。

项目事实

• 新同事能够找到负责人、架构边界、开发命令和验证命令。
• AGENTS.md 指向唯一文档，而不是复制整本项目 Wiki。
• 长期决定不会只存在于聊天记录或个人 Memory。

多工具支持

• 每个受支持的工具入口都有轻量适配，或者已经验证能直接加载共享契约。
• 工具版本、指令文件与验证日期已经记录。
• 替换一个工具不需要重写项目的 Definition of Done。

不同能力层级

• 自主权取决于能力证据、任务风险、仓库熟悉度和工具熟悉度。
• 停止条件和升级负责人明确。
• 同一个人可以针对不同领域处于不同层级，而不会被贴永久标签。

项目稳定性

• 高影响规则都有可执行控制。
• 默认分支、敏感路径、外部写入和生产操作得到保护。
• 交接包含 Diff 或 Commit、命令、实际结果和剩余风险。

文档持续演进

• Pull Request 会检查行为、命令、架构、所有权或工具支持是否发生变化。
• AI 指引、适配、架构和项目文档都有明确负责人。
• 重复失败会更新正确的长期资产，并重跑相关案例。

结语：统一项目契约，而不是统一开发者

一支可持续使用 AI Coding 的团队，不需要强迫每个人使用同一种编辑器、模型和交互方式。

真正需要统一的是：

一个项目事实源
+ 可以跨工具传递的任务契约
+ 轻量工具适配
+ 与能力相匹配的自主权
+ 可执行的工程控制
+ 文档与评估的持续反馈闭环

这样，新手有安全的成长路径，熟练开发者仍然可以快速工作，维护者则能得到可以审查的证据。同一个人更换工具时，项目的 Definition of Done 不会跟着改变。项目知识通过正常工程工作不断积累，而不是逐渐腐烂在私人 Prompt 中。

团队真正落地 AI Coding 的标志，不是所有人都开始使用 Agent，而是人员和 Agent 都可以变化，项目仍然保持可理解、可评审、稳定和可维护。

权威资料

以下持续更新的产品文档已于 2026 年 8 月 17 日重新核对；研究资料均明确标注 2026 年发布日期。

• OpenAI Codex：Custom instructions with AGENTS.md——Codex 当前的分层指令发现与优先顺序。
• Claude Code：How Claude remembers your project——CLAUDE.md、分层 Rules、项目与个人 Memory，以及导入 AGENTS.md。
• Cursor：Rules——当前 Project Rules 与 AGENTS.md 定制入口。
• Gemini CLI：Provide context with GEMINI.md files——分层上下文、文件导入、当前上下文检查和自定义文件名。
• GitHub：自定义指令支持矩阵——不同 Copilot 产品、IDE、Review、Cloud Agent 与 CLI 的支持差异。
• GitHub：Protected Branches 与 CODEOWNERS——可强制执行的检查、评审和所有权。
• OWASP Agentic Applications Top 10 2026——当前 Agent 工具、身份、执行和供应链风险。
• OpenAI：Evaluation best practices——结合自动证据与人工判断开展贴近任务的持续评估。
• Configuration Smells in AGENTS.md Files，2026 年 6 月——关于重复、膨胀、错位、过期和冲突 Agent 指引的实证分类。
• ContextCov，2026 年 2 月——把被动 Agent 指令转换为可执行约束的研究。