你给 Claude Code 写了十条规矩，它转身就忘；Cursor 明明配置了代码规范，提交的 PR 还是满屏魔法数字。问题不在模型不够聪明，而在于你从来没跟它签过一份正式的「合同」——现在，这份合同有了开源标准版。

一、痛点：AI 编码代理的「失忆症」

过去一年，AI 编码代理（Coding Agent）彻底改变了开发者的工作方式。Claude Code、OpenAI Codex、Cursor、GitHub Copilot——这些工具能读懂整个代码库，能自主规划任务、修改文件、运行测试。但用过的人都知道一个尴尬的事实：它们没有长期记性，更没有统一的行为约束。

你在 CLAUDE.md 里写了“禁止使用 any 类型”，结果 Cursor 里的同一个项目完全不知道这条规矩；你在 Cursor 的 .cursorrules 里定义了分支命名规范，切到 Codex 又得重写一遍。每个工具都有自己的配置格式、自己的记忆文件、自己的“脾气”，团队规范被碎片化地散落在四五份配置文件里，维护成本极高，最终没人维护。

更深层的问题是：AI 代理不理解“契约”这个概念。它不知道哪些规则是硬性的（违反即失败），哪些是建议性的（可以灵活处理），也不知道违反规则后该如何自查自纠。人类开发者靠 code review 兜底，AI 代理往往一气呵成地提交——没有兜底。

二、agents-contract：一份契约，管住所有代理

最近登上 GitHub Trending 的开源项目 AntoGA/agents-contract 给出了一个优雅的解法。它的核心思路可以用三句话概括：

1. 用 AGENTS.md 作为唯一契约源——一份文件，定义 AI 代理在项目中必须遵守的所有规则；

2. 零依赖的 Linter——不装任何 npm 包，直接校验契约文件的完整性和规范性；

3. SessionStart Hook——每次代理会话启动时自动注入契约内容，确保代理“开机即读规矩”。

关键在于 AGENTS.md 这个格式正在成为事实上的行业标准。与 CLAUDE.md（Claude Code 专属）、.cursorrules（Cursor 专属）不同，AGENTS.md 是一个开放规范，Claude Code、Codex、Cursor、Copilot 都已支持或兼容。这意味着你写一次规则，所有工具共享。

它的架构非常清晰：

<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" font-family="PingFang SC, Microsoft YaHei, Noto Sans SC, sans-serif">
  <defs>
    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
      <path d="M0,0 L8,3 L0,6 Z" fill="#6366f1"/>
    </marker>
  </defs>
  <rect x="40" y="40" width="200" height="80" rx="12" fill="#6366f1"/>
  <text x="140" y="75" text-anchor="middle" fill="#fff" font-size="18" font-weight="bold">AGENTS.md</text>
  <text x="140" y="100" text-anchor="middle" fill="#e0e7ff" font-size="13">唯一契约源</text>
  <rect x="300" y="40" width="200" height="80" rx="12" fill="#8b5cf6"/>
  <text x="400" y="75" text-anchor="middle" fill="#fff" font-size="18" font-weight="bold">Linter 校验</text>
  <text x="400" y="100" text-anchor="middle" fill="#ede9fe" font-size="13">零依赖 · 规范检查</text>
  <rect x="560" y="40" width="200" height="80" rx="12" fill="#6366f1"/>
  <text x="660" y="75" text-anchor="middle" fill="#fff" font-size="18" font-weight="bold">SessionStart Hook</text>
  <text x="660" y="100" text-anchor="middle" fill="#e0e7ff" font-size="13">会话启动自动注入</text>
  <line x1="240" y1="80" x2="298" y2="80" stroke="#6366f1" stroke-width="2.5" marker-end="url(#arrow)"/>
  <line x1="500" y1="80" x2="558" y2="80" stroke="#6366f1" stroke-width="2.5" marker-end="url(#arrow)"/>
  <rect x="80" y="220" width="150" height="70" rx="12" fill="#f5f3ff" stroke="#8b5cf6" stroke-width="2"/>
  <text x="155" y="262" text-anchor="middle" fill="#6d28d9" font-size="16">Claude Code</text>
  <rect x="260" y="220" width="150" height="70" rx="12" fill="#f5f3ff" stroke="#8b5cf6" stroke-width="2"/>
  <text x="335" y="262" text-anchor="middle" fill="#6d28d9" font-size="16">Codex</text>
  <rect x="440" y="220" width="150" height="70" rx="12" fill="#f5f3ff" stroke="#8b5cf6" stroke-width="2"/>
  <text x="515" y="262" text-anchor="middle" fill="#6d28d9" font-size="16">Cursor</text>
  <rect x="620" y="220" width="150" height="70" rx="12" fill="#f5f3ff" stroke="#8b5cf6" stroke-width="2"/>
  <text x="695" y="262" text-anchor="middle" fill="#6d28d9" font-size="16">Copilot</text>
  <text x="400" y="180" text-anchor="middle" fill="#6366f1" font-size="14">↓ 契约内容分发至所有代理会话 ↓</text>
</svg>

三、上手实战：三步接入

第 1 步：安装（真的零依赖）

# 无需 npm install，直接通过 npx 使用
npx agents-contract init

第 2 步：编写契约

一份结构良好的 AGENTS.md 大致长这样：

# Project Contract

## Hard Rules（硬性规则，违反即失败）
- TypeScript 严格模式，禁止使用 `any`
- 所有公开函数必须有 JSDoc 注释
- 禁止直接修改 `legacy/` 目录下的文件

## Conventions（约定）
- 分支命名：`feat/xxx`、`fix/xxx`、`chore/xxx`
- 提交信息遵循 Conventional Commits
- 组件文件使用 PascalCase

## Verification（完成定义）
- 修改后必须运行：`npm run lint && npm run test`
- 所有测试通过才算任务完成

第 3 步：配置 SessionStart Hook

以 Claude Code 为例，在 .claude/settings.json 中配置：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npx agents-contract inject"
          }
        ]
      }
    ]
  }
}

这个 Hook 的作用是：每次代理会话启动，自动把契约内容注入上下文。不需要你每次手动说“请先阅读 AGENTS.md”，代理开机第一件事就是“读合同”。

校验契约本身

契约文件写错了、写漏了怎么办？跑一下 Linter：

npx agents-contract lint

# 输出示例：
# ✓ AGENTS.md found at project root
# ⚠ Missing "Verification" section — agents won't know when a task is done
# ✓ Hard Rules section is valid

它会检查契约文件的结构完整性，比如是否定义了硬性规则、是否有明确的验证标准（Definition of Done）。这一点很妙——合同本身也要有人审。

四、为什么这个项目值得关注？

当然也有冷静的一面：契约不是银弹。模型对规则的理解和遵守仍有概率性，契约写得再好，也替代不了 code review。它的正确定位是大幅降低 AI 犯低级错误的基线，而不是根除错误。

五、写在最后

从 .cursorrules 到 CLAUDE.md 再到 AGENTS.md，AI 编码工具的配置规范正在经历一场“大一统”。agents-contract 这样的项目出现，说明社区已经开始为“AI 代理的工程化协作”建设基础设施——就像当年 ESLint 之于 JavaScript、EditorConfig 之于多编辑器协作。

当你的 AI 代理学会“签合同”上岗，你才会意识到：约束，才是释放生产力的前提。

项目地址：https://github.com/AntoGA/agents-contract ，感兴趣的话不妨在你的下一个项目里试试。