Cairn — A file-based protocol for humans + AI agents

代理会忘，团队会忘，文件不会。
像登山者堆石头路标一样，把"人 + 多个 AI 代理"的上下文堆在 Markdown 文件里 —— 后来的人和代理都能沿着路标走。

English | 中文

GitHub：RT64M/cairn

✦ 这是什么

Cairn 不是框架、不是 SDK、不是 IDE 插件。 它是一份可以直接复制进任何项目的协作协议。

Cairn（[ker-n]）原指登山者沿途堆起的石头路标。 在这个项目里，每一块"石头"是一个 md 文件；它们一起标出项目的来路，让任何代理或新加入的人都不会迷路。

把它放进项目根目录，AI 代理（Claude Code / Cursor / Codex / Aider / Cline / Devin / 自家 Agent…）和人类协作者就会共享同一份 可追溯的上下文：当前在做什么、为什么这么做、谁卡在哪、哪些事必须人来做、改动如何回写计划。

一句话：让记忆从聊天框里走出来,长在文件里。

✦ 它解决什么问题

如果你用 AI 代理写过真实项目,下面这些场景应该熟悉：

• 🧠 代理失忆：换一个会话、换一个代理,又要从头解释项目;上一次的设计取舍消失在聊天记录里。
• 🤝 多代理打架：让 Codex 改一版,再让 Claude Code 接手,两个代理对"什么算完成"理解不同,互相覆盖对方的工作。
• 🚧 plan 漂移：每次新需求都直接进代码,几周后没人知道项目原本要做什么。
• 👤 人工事项丢失："这个要你登录真机验一下"在聊天里说过一次,再也没人提,最后上线翻车。
• 📝 README / TODO / 计划互相污染：用户文档里夹着内部 TODO,计划文档里塞满 bug 修复记录。

Cairn 用 职责边界清晰的几个文件 给每类信息一个固定家。

✦ 30 秒看懂

                  ┌──────────────────────────────────────────┐
                  │         人类  ⇄  多个 AI 代理            │
                  └─┬─────────────────────────────────────┬──┘
       反馈/审查/   │                                     │  写代码 /
       测试        ▼                                     ▼  推进任务

   ┌────────────────┐  条目进入 TODO   ┌──────────────┐  代理改不动?    ┌─────────────┐
   │ fix_<desc>.md  │ ───────────────▶ │   TODO.md    │ ──────────────▶ │  HUMAN.md   │
   │ 反馈批次闭环   │                  │   执行台账   │                 │  人工分流   │
   │ (语义命名)     │                  │  (执行中心)  │ ◀────────────── │             │
   └───────┬────────┘                  └──────┬───────┘   完成: [x]/[~] └─────────────┘
           │ 归档时:                          ▲
           │ 唯一回写 plan 的入口             │ 初始拆解为步骤
           ▼                                  │
   ┌────────────────┐                         │
   │    plan.md     │ ────────────────────────┘
   │   项目大纲     │
   │ (仅 fix 归档   │
   │  能改写)       │
   └────────────────┘

── 地基：进入项目时按顺序读 ─────────────────────────────────────────────────
   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 → TODO ⇄ HUMAN，反馈进 TODO、人工事项分流出去再回写、fix 归档时唯一回写 plan。
• 稳定地基：plan / ARCHITECTURE / AGENTS / README 各管一摊，互不污染。
• 按需补充：INTERFACE / TEST / NICKNAME 满足触发条件才建，不预先占位。
• 终点：archive/ 让活跃文件保持清爽，不删除历史。

✦ 60 秒上手

# 把 AGENTS 模板拷进你的项目
cp template/AGENTS.zh.md your-project/AGENTS.md
cd your-project

打开任何支持读取仓库的 AI 代理（Claude Code / Cursor / Codex / Aider / Cline …）,直接说：

读一下 AGENTS.md,按里面的规则给本项目补全六件套元文件。

代理会按协议建出 plan.md / ARCHITECTURE.md / TODO.md / README.md,并在触发条件出现时建 INTERFACE.md / NICKNAME.md / HUMAN.md。

✦ 核心：六件套 + 四个按需文件

每个采用 Cairn 的项目都遵循同一套文件分工。职责互不重叠、信息只放在它的家里。

必有六件套

按需四件套

完整规则见 template/AGENTS.zh.md。

✦ 几个关键设计

这些是 Cairn 在多轮真实使用里打磨出来的"硬规则",看起来反直觉,但每条都对应一个常见翻车场景：

• plan.md 只能通过 fix 归档回写。 防止每次会话都改大纲,导致项目定位漂移。
• fix 文件用语义命名（fix_gesture-scoring.md 而不是 fix_01.md）。从文件名就能判断批次主题。
• TODO 优先级低于所有未归档的 fix。 反馈先收敛,再继续推 TODO,避免遗漏外部输入。
• 代理改不动的事项必须转 HUMAN.md。 不让 fix 永久阻塞,不让人工事项溶解在聊天里。
• TODO 的 [!] / [~] 状态保留废弃条目。 历史决策可回溯,而不是被悄悄删除。
• AGENTS.md 给代理读,README.md 给用户读。 同一信息不在两边重复维护。

✦ 仓库结构

✦ 阅读路线

✦ 谁应该用 Cairn

• ✅ 用 AI 代理写真实项目,会跨多个会话、多个代理、多个工具切换的人。
• ✅ 同一个项目里既有人类开发者也有 AI 代理在改代码的团队。
• ✅ 想让 AI 代理产出物可审计、可回溯、可交接的工程师。
• ✅ 受够了"上一个会话讲过的设计取舍这次又得重新讲一遍"的人。
• ❌ 一次性脚本、一句 prompt 就能搞定的小工具 —— Cairn 是给长期项目用的。

✦ Agent-agnostic

Cairn 只规定文件结构和读写规则,不绑定任何代理或 IDE。已知可用的环境：

• Anthropic Claude Code
• Cursor / Windsurf / Zed AI
• OpenAI Codex CLI
• Aider / Cline / Continue.dev
• 自建 LangGraph / CrewAI / AutoGen 代理
• 任何能读取 Markdown 仓库的 LLM 工具

✦ FAQ

Q: 这跟在 README 里写一段"AI 须知"有什么区别？
A: 那只是给单个代理的提示。Cairn 规定 多个 代理之间如何在 多次 会话间共享状态、闭环反馈、回写决策。

Q: 我已经在用 CLAUDE.md / .cursorrules / AGENTS.md 了,要换吗？
A: 不用换,Cairn 的 AGENTS.md 就是这一类文件的超集,把 协作规则 和 执行台账 拆开管理。可以从把现有规则贴进 Cairn 模板开始。

Q: 不会让文件多到爆炸吗？
A: 必有六件套,按需四件套,最多十个 md。其中 plan.md / ARCHITECTURE.md 几乎不动;归档进 archive/ 让活跃文件保持清爽。

Q: 改一行代码也要更新 TODO?
A: 是。这是协议的"硬规则"。代价是每次同步一行 markdown,收益是几个月后任何代理都能秒上手。

✦ 不做什么

• 不提供具体语言 / 框架 / CI / Git 分支模型 / 测试工具的选择。
• 不提供示例项目里的真实代码或截图。
• 不替代 issue tracker、不替代 ADR,但可以和它们共存。
• 不要求所有项目模板都散成一堆文件;当前模板只保留 AGENTS.md 中英两份,其他文件由项目按协议自己创建。

✦ License

MIT — 见 LICENSE。

如果 Cairn 对你有用,欢迎在 GitHub 上 ⭐ 一下,并在自己的项目里把这一行加到 README：
This project follows the Cairn protocol — a file-based protocol for humans + AI agents.