代理会忘，团队会忘，文件不会。 像登山者堆石头路标一样，把"人 + 多个 AI 代理"的上下文堆在 Markdown 文件里 —— 后来的人和代理都能沿着路标走。
English | 中文
Cairn 是一份纯 Markdown 形式的协作协议。 把模板文件复制进项目根目录即可生效，无需安装、构建或运行时依赖。
Cairn（[ker-n]）原指登山者沿途堆起的石头路标。 在这个项目里，每一块"石头"是一个 md 文件；它们一起标出项目的来路，让任何代理或新加入的人都不会迷路。
把它放进项目根目录，AI 代理和人类协作者就会共享同一份 可追溯的上下文：当前在做什么、为什么这么做、谁卡在哪、哪些事必须人来做、改动如何回写计划。
简言之：让记忆从聊天框里走出来，长在文件里。
如果你用 AI 代理写过真实项目，下面这些场景应该熟悉：
- 🧠 代理失忆 / plan 漂移：换一个会话、换一个代理就要从头解释项目；上一次的设计取舍消失在聊天记录里，几周后没人记得项目原本要做什么。
- 🤝 多代理打架：让 Codex 改一版，再让 Claude Code 接手；两个代理对"什么算完成"理解不同，互相覆盖对方的工作。
- 👤 人工事项丢失：代理遇到无法独立验证或解决的事项时，要么执行进程被静默阻塞，要么相关问题被忽略丢弃；既没交还给人类，也没进入任何台账。
Cairn 用 职责边界清晰的几个文件 给每类信息一个固定家。
┌──────────────────────────────────────────┐
│ 人类 ⇄ 多个 AI 代理 │
└─┬─────────────────────────────────────┬──┘
反馈/审查/ │ │ 写代码 /
测试 ▼ ▼ 推进任务
┌────────────────────┐ 条目进入 TODO ┌──────────────┐ 代理改不动? ┌─────────────┐
│ fix_<desc>.md │ ─────────────▶ │ TODO.md │ ─────────────▶ │ HUMAN.md │
│ fix-plan_<desc>.md │ │ 执行台账 │ │ 人工分流 │
│ (语义命名) │ │ (执行中心) │ ◀───────────── │ │
└─────────┬──────────┘ └──────┬───────┘ 完成: [x]/[~] └─────────────┘
│ 修改 plan 的唯一两类入口 ▲
│ fix 归档时按需修正描述 │ 初始拆解为步骤
│ fix-plan 用户确认时新增内容 │
▼ │
┌────────────────┐ │
│ plan.md │ ──────────────────────────┘
│ 项目大纲 │
└────────────────┘
── 地基：进入项目时按顺序读 ─────────────────────────────────────────────────
NICKNAME.md 项目术语表；第一个读 (≥5 个术语时建立)
ARCHITECTURE.md 代码组织：新代码归属、模块依赖、启动顺序
AGENTS.md 上面所有箭头背后的读写规则由它定义
README.md 只给最终用户读 — 与 AGENTS.md 严格不重叠
── 按需：满足触发条件才出现 ─────────────────────────────────────────────────
INTERFACE.md 对外接口契约；与代码同步，TODO 注 "已同步 INTERFACE.md"
TEST.md 测试方法 (用户主动要求测试时建立)；
测出的 bug 流入 fix_<desc>.md
── 终点：归档收纳 ─────────────────────────────────────────────────────────
archive/ 已归档 fix 批次 · 已完成 TODO 步骤 · 已完成 HUMAN 条目
- 主流程闭环：fix / fix-plan → TODO ⇄ HUMAN；fix 归档时按需修正 plan 描述偏差，fix-plan 在用户最终确认时立即写入新增内容。
- 稳定地基与按需补充各司其职，归档进
archive/不删除历史。
# 把 AGENTS 模板拷进你的项目
cp template/AGENTS.zh.md your-project/AGENTS.md
cd your-project打开任何支持读取仓库的 AI 代理，直接说：
读一下 AGENTS.md，按里面的规则给本项目补全协议要求的元文件。
代理会按协议建出 plan.md / ARCHITECTURE.md / TODO.md / README.md，并在触发条件出现时建 INTERFACE.md / NICKNAME.md / HUMAN.md。
每个采用 Cairn 的项目都遵循同一套文件分工。职责互不重叠、信息只放在它的家里。
| 文件 | 角色 | 改动频率 |
|---|---|---|
plan.md |
项目大纲：定位 / 功能清单 / 数据模型 / 接口 / 验收 | 仅初始化（仅 fix 归档时回写） |
ARCHITECTURE.md |
代码组织：目录分工 / 新增代码归属 / 启动顺序 | 仅初始化 |
AGENTS.md |
代理协作协议：状态约定 / 文件分工 / 同步要求 | 低频 |
README.md |
用户说明：能做什么 / 怎么装 / 怎么用 / FAQ | 低频 |
TODO.md |
执行台账：步骤 / 子项 / 阻塞 / 来源 / 完成状态 | 每次会话同步 |
| 文件 | 触发条件 | 备注 |
|---|---|---|
fix_<desc>.md |
用户要求审查 / 审计 / 复核，或提供测试反馈 | 缺陷反馈闭环，语义命名；归档时按需修正 plan 描述偏差 |
fix-plan_<desc>.md |
用户提出 plan 之外的新功能 / 新模块 / 验收标准扩展 | 计划扩展闭环，语义命名；用户最终确认时立刻写入 plan，是新增 plan 内容的唯一入口 |
HUMAN.md |
出现代理无法完成、必须人工执行的事项 | — |
INTERFACE.md |
项目存在对外接口（API / CLI / SDK / 前后端） | — |
TEST.md |
项目复杂且用户明确要求代理测试 | — |
NICKNAME.md |
项目专有术语 ≥ 5 个 | — |
完整规则见 template/AGENTS.zh.md。
以下是 Cairn 协议的几条核心硬性约束。每一条都直接对应一类典型的协作失败模式：
- plan.md 仅可通过两类入口修改：
fix_<desc>.md归档时按需修正描述偏差，fix-plan_<desc>.md在用户最终确认时写入新增内容。防止每次会话都改大纲，导致项目定位漂移。 - fix 与 fix-plan 严格分文件。 即使用户在同一次对话中同时提出 bug 修复与新功能，也必须分别建两份文件，从文件名前缀即可判别批次性质。
- fix 文件用语义命名（
fix_gesture-scoring.md而不是fix_01.md）。从文件名就能判断批次主题。 - TODO 优先级低于所有未归档的 fix 与 fix-plan。 反馈先收敛，再继续推 TODO，避免遗漏外部输入。
- 代理改不动的事项必须转 HUMAN.md。 不让 fix 永久阻塞，不让人工事项溶解在聊天里。
- TODO 的
[!]/[~]状态保留废弃条目。 历史决策可回溯，而不是被悄悄删除。 - AGENTS.md 给代理读，README.md 给用户读。 同一信息不在两边重复维护。
| 目录 | 内容 |
|---|---|
template/ |
AGENTS.md 中英文双版本，核心交付物 |
design/ |
每个 md 文件的设计理由：为什么需要它、边界在哪、如何配合 |
workflow/ |
6 个典型场景的代理工作流：新项目、迭代、fix 缺陷闭环、人工分流、fix-plan 扩展闭环、按需补充 |
example/ |
一个完整虚构项目（Northstar Ops）的 md 状态快照，展示协议跑起来的样子 |
| 我想… | 直接读 |
|---|---|
| 复制一份立刻用 | template/AGENTS.zh.md |
| 理解为什么这样分文件 | design/overview.md |
| 看代理在不同场景怎么走流程 | workflow/01-new-project.md … 06- |
| 看真实项目跑起来长什么样 | example/README.md |
Q：这跟在 README 里写一段"AI 须知"有什么区别？ A：那只是给单个代理的提示。Cairn 规定 多个 代理之间如何在 多次 会话间共享状态、闭环反馈、回写决策。
Q：不会让文件多到爆炸吗？
A：5 个核心元文件 + 最多 6 类按需补充文件。其中 plan.md / ARCHITECTURE.md 仅在初始化阶段撰写，后续基本不动；fix_* 与 fix-plan_* 完成后均归档进 archive/，活跃文件始终保持清爽。
Q：改一行代码也要更新 TODO？ A：是。这是协议的强制约束。每次同步只需一行 markdown，换来的是数月之后任何代理都能立即接手项目。
- 不提供具体语言 / 框架 / CI / Git 分支模型 / 测试工具的选择。
- 不替代 issue tracker、不替代 ADR，但可以和它们共存。
- 不绑定任何代理或 IDE：只规定文件结构和读写规则，任何能读取 Markdown 仓库的工具都可用。
MIT — 见 LICENSE。