Your agents forget. Your team forgets. Files don't. Stack files like trail markers — and any agent finds the trail.
English | 中文
Cairn is a Markdown-based collaboration protocol. Copy the spec files into your project root and it takes effect — no installation, no build, no runtime dependency.
A cairn ([kern]) is a stack of stones hikers leave along a trail. In this project, each "stone" is a Markdown file; together they mark the path of your project, so any agent or new teammate can follow the trail without getting lost.
Drop it into your repo root, and AI agents plus human collaborators all share the same traceable context: what's being worked on, why, who is blocked, what must be done or decided by a human, and how each change feeds back into the plan.
In short: let memory live in files, not in chat windows.
If you've ever used AI agents on a real project, these scenes will feel familiar:
- 🧠 Agent amnesia / plan drift. New session, new agent — and you're explaining the project from scratch again. Last week's design tradeoffs are buried in chat history; a few weeks in, nobody remembers what the project was supposed to be.
- 🤝 Multi-agent collisions. You let Codex take a pass, then Claude Code picks it up. They disagree on what "done" means and quietly overwrite each other's work.
- 🔁 External agents interrupt the main line. You want to ask another agent to review direction, revise content, or suggest changes at any time, but the feedback often stays in chat and the main agent cannot tell that TODO, fix, or plan boundaries changed.
- 👤 Lost human tasks and decisions. When an agent hits something it cannot independently verify, solve, or responsibly decide, execution either silently blocks or the issue is quietly dropped — never handed back to a human, never logged in any ledger.
Cairn gives each kind of information a dedicated home with strict boundaries.
This is especially useful when a main agent is already deep in continuous work: sidecar agents can review, supplement context, add interface notes, report test feedback, or propose plan revisions in parallel. Their output lands in files, and the main agent merges it at sync points without losing its current context or dropping sidecar input.
┌──────────────────────────────────────────┐
│ Human ⇄ Multiple AI Agents │
└─┬─────────────────────────────────────┬──┘
feedback / │ │ writes code /
reviews / ▼ ▼ progresses tasks
tests
┌────────────────────┐ items enter ┌──────────────┐ agent can't do ┌─────────────┐
│ fix_<desc>.md │ ──────────────▶ │ TODO.md │ ────────────────▶ │ HUMAN.md │
│ fix-plan_<desc>.md │ │ work ledger │ or needs human │ intervention│
│ (semantic name) │ │ (exec hub) │ ◀──────────────── │ │
└─────────┬──────────┘ └──────┬───────┘ done: [x] / [~] └─────────────┘
│ the ONLY two ways ▲
│ to rewrite plan.md: │ initial breakdown
│ fix on archive (corrections) │ into steps
│ fix-plan on confirmation │
│ (adds/revises + annotates) │
▼ │
┌────────────────┐ │
│ plan.md │ ───────────────────────────┘
│ project outline│
└────────────────┘
── Foundation: read in order on every project entry ──────────────────────────
NICKNAME.md project glossary and naming preferences; read first
(built once ≥5 terms exist)
ARCHITECTURE.md where new code goes; module deps; startup order
AGENTS.md the read/write rules behind every arrow above
README.md for end users only — strictly disjoint from AGENTS.md
── Conditional: created only when triggered ──────────────────────────────────
INTERFACE.md external API/CLI/SDK contract; synced with code,
noted as "INTERFACE.md synced" inside TODO entries
TEST.md test methods (only when user explicitly requests testing);
bugs found via TEST flow back into fix_<desc>.md
── Terminus: archive ────────────────────────────────────────────────────────
archive/ archived fix batches · finished TODO steps · done HUMAN
- Active loop:
fix / fix-plan → TODO ⇄ HUMAN.fixarchives correct plan descriptions on demand; after user final confirmation,fix-planwrites and annotatesplan.md, archives first, then TODO is derived from the revised plan. - Stable foundation and conditional supplements each own one concern; closed batches move to
archive/so history is preserved without cluttering the active set.
# Copy the AGENTS template into your project
cp template/AGENTS.en.md your-project/AGENTS.md
cd your-projectOpen any AI agent that can read your repo and just say:
Read AGENTS.md and bootstrap the required meta-files for this project per its rules.
When your agent supports Plan mode, use it for the initial plan.md creation. Cairn expects the planning stage to be interactive: discuss positioning, feature scope, data model, interfaces, and acceptance criteria first, then write the plan only after final user confirmation. Plan mode fits that “ask first, write after confirmation” initialization flow.
If you ask an agent to create a brand-new project directly, make sure AGENTS.md exists before any other project files. The safest path is to place this AGENTS.md in the target project folder first. If the agent is also creating the folder, add a persistent memory or global rule for that agent: before creating any new project, create the project folder and immediately write Cairn's AGENTS.md into it.
The agent will create plan.md / ARCHITECTURE.md / TODO.md / README.md, plus INTERFACE.md / NICKNAME.md / HUMAN.md if their trigger conditions are met.
Every Cairn project follows the same file layout. Responsibilities never overlap. Each piece of information has exactly one home.
| File | Role | Change rate |
|---|---|---|
plan.md |
Outline: positioning / feature list / data model / interfaces / acceptance | Initialization only (rewritten only on fix archive or after fix-plan confirmation) |
ARCHITECTURE.md |
Code organization: directories / where new code goes / startup order | Initialization only |
AGENTS.md |
Agent collaboration protocol: state conventions, file ownership, sync rules | Low frequency |
README.md |
User-facing: what it does, how to install, how to use, FAQ | Low frequency |
TODO.md |
Work ledger: steps / sub-items / blockers / source / status | Per-session sync |
| File | Trigger | Note |
|---|---|---|
fix_<desc>.md |
User requests review / audit / plan re-check, or provides test feedback | Defect-feedback loop, semantic naming; rewrites plan.md description on archive only when current state has diverged |
fix-plan_<desc>.md |
User proposes a new feature / new module / acceptance scope extension outside the current plan, or asks to revise existing plan items | Plan-revision loop, semantic naming; writes into plan.md, annotates source, and archives first after user final confirmation — the only entry for adding / revising plan content |
HUMAN.md |
A human-only task appears, or a direction-level question needs human decision | The agent packages work it cannot complete or should not decide alone; humans can edit status and feedback any time while the agent pauses the affected scope and continues other work |
INTERFACE.md |
The project exposes any external interface (API / CLI / SDK / FE↔BE) | — |
TEST.md |
The project is complex and the user explicitly asks the agent to test | — |
NICKNAME.md |
Project-specific terminology reaches 5 or more terms | Captures your naming preferences so agents understand project slang, abbreviations, and aliases first |
Full rules: template/AGENTS.en.md.
The following are Cairn's core hard constraints. Each one maps directly to a specific collaboration failure mode:
plan.mdis rewritten only via two entry points:fix_<desc>.mdcorrects description divergence on archive;fix-plan_<desc>.mdwrites new / revised content after user final confirmation, with source and date annotations. Prevents the outline from drifting in every session.fixandfix-planare kept strictly separate. Even if the user raises a bug fix and a new feature in the same conversation, two distinct files must be created — the prefix tells you the batch's nature.fixfiles use semantic names (fix_gesture-scoring.md, notfix_01.md). The filename alone tells you the batch's subject.- All open
fixandfix-planfiles outrankTODO.md. Defect feedback closes first; plan changes complete theplan.mdwrite, source annotation, and fix-plan archive before TODO continues, so external input never gets dropped. - Sidecar agents can work without interrupting the main agent. The main agent can keep progressing the current TODO while other agents review, supplement context, revise docs, or propose plan changes in parallel. Sidecar results land in
fix_*,fix-plan_*,HUMAN.md,TODO.md, or conditional meta-files, and the main agent merges them at sync points without losing context or leaving feedback trapped in chat. - What an agent cannot do or should not decide alone must move to
HUMAN.md. The agent packages human-only work, key confusion, or direction risks for a human; humans can edit status, feedback, or completion results in the file at any time. The agent pauses the affected scope while continuing other executable work that does not depend on that decision. - Project slang belongs in
NICKNAME.md. It is not a generic glossary; it captures your naming preferences so agents understand abbreviations, aliases, and project-specific meanings before reading the rest. - Deprecated TODO items are kept with
[!]/[~]status. Historical decisions stay traceable instead of being silently deleted. AGENTS.mdis for agents,README.mdis for users. Same fact never lives in two places.
| Directory | Contents |
|---|---|
template/ |
AGENTS.en.md and AGENTS.zh.md — the two template files |
design/ |
Design notes split into design/en/ and design/cn/ |
workflow/ |
Workflow samples split into workflow/en/ and workflow/cn/ |
example/ |
Fictional project-state snapshots split into example/en/ and example/cn/ |
| I want to… | Read |
|---|---|
| Just copy and use it | template/AGENTS.en.md |
| Understand why files are split this way | design/en/overview.md |
| See how agents act in different scenarios | workflow/en/01-new-project.md … workflow/en/07-parallel-agent-intervention.md |
| See a real-looking project mid-flight | example/en/AGENTS.md, example/en/TODO.md, example/en/fix_audit-batch.md |
Q: How is this different from putting an "AI instructions" section in the README? A: That only briefs a single agent. Cairn defines how multiple agents share state, close feedback loops, and rewrite decisions across multiple sessions.
Q: Won't this explode into a sea of files?
A: 5 core meta-files plus up to 6 conditional supplementary file types. plan.md / ARCHITECTURE.md are written once at initialization and barely change after; both fix_* and fix-plan_* move into archive/ once closed, so the active file set stays compact.
Q: One line of code = update TODO? A: Yes. It is a strict requirement of the protocol. Each sync costs one line of Markdown, and in return any agent can pick the project up months later without ramp-up.
- No prescriptions about language / framework / CI / branching model / testing tools.
- Does not replace your issue tracker or ADRs — it lives alongside them.
- Not bound to any agent or IDE: Cairn only specifies file structure and read/write rules; any tool that can read a Markdown repository can use it.
English | 中文
代理会忘，团队会忘，文件不会。 像登山者堆石头路标一样，把"人 + 多个 AI 代理"的上下文堆在 Markdown 文件里 —— 后来的人和代理都能沿着路标走。
Cairn 是一份纯 Markdown 形式的协作协议。 把模板文件复制进项目根目录即可生效，无需安装、构建或运行时依赖。
Cairn（[ker-n]）原指登山者沿途堆起的石头路标。 在这个项目里，每一块"石头"是一个 md 文件；它们一起标出项目的来路，让任何代理或新加入的人都不会迷路。
把它放进项目根目录，AI 代理和人类协作者就会共享同一份 可追溯的上下文：当前在做什么、为什么这么做、谁卡在哪、哪些事必须人来做或决定、改动如何回写计划。
简言之：让记忆从聊天框里走出来，长在文件里。
如果你用 AI 代理写过真实项目，下面这些场景应该熟悉：
- 🧠 代理失忆 / plan 漂移：换一个会话、换一个代理就要从头解释项目；上一次的设计取舍消失在聊天记录里，几周后没人记得项目原本要做什么。
- 🤝 多代理打架：让 Codex 改一版，再让 Claude Code 接手；两个代理对"什么算完成"理解不同，互相覆盖对方的工作。
- 🔁 外部 agent 介入会打断主线：你想随时请另一个 agent 复核项目方向、补充内容或提出修订，但反馈常常散落在聊天里，主 agent 不知道 TODO、fix 或计划边界已经变了。
- 👤 人工事项和关键决策丢失：代理遇到无法独立验证、解决或不应擅自决定的事项时，要么执行进程被静默阻塞，要么相关问题被忽略丢弃；既没交还给人类，也没进入任何台账。
Cairn 用 职责边界清晰的几个文件 给每类信息一个固定家。
这尤其适合“主 agent 持续工作 + 旁路 agent 随时补充”的节奏：主 agent 不必停下来等待审查或资料补充，其他 agent 可以把 review、接口补充、测试反馈或计划修订写入对应文件；主 agent 在同步点统一合流，既保留当前工作上下文，也不会漏掉旁路输入。
┌──────────────────────────────────────────┐
│ 人类 ⇄ 多个 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 在用户最终确认后立即写入并标注 plan 来源，然后优先归档，再从新版 plan 拆 TODO。
- 稳定地基与按需补充各司其职，归档进
archive/不删除历史。
# 把 AGENTS 模板拷进你的项目
cp template/AGENTS.zh.md your-project/AGENTS.md
cd your-project打开任何支持读取仓库的 AI 代理，直接说：
读一下 AGENTS.md，按里面的规则给本项目补全协议要求的元文件。
建议在支持 Plan mode / 计划模式 的代理里完成初始 plan.md 创建。Cairn 要求计划阶段先充分交互讨论项目定位、功能清单、数据模型、接口和验收标准，再由用户最终确认；计划模式更适合这种“先问清楚，再落文件”的初始化过程。
如果是让 agent 直接创建一个全新项目，要确保 AGENTS.md 先于其他项目文件出现。最稳妥的做法是在目标项目文件夹中预先放入这份 AGENTS.md；如果项目文件夹也由 agent 创建，则建议在 agent 的长期记忆或全局规则里写明：创建任何新项目前，先创建项目文件夹并立刻写入 Cairn 的 AGENTS.md。
代理会按协议建出 plan.md / ARCHITECTURE.md / TODO.md / README.md，并在触发条件出现时建 INTERFACE.md / NICKNAME.md / HUMAN.md。
每个采用 Cairn 的项目都遵循同一套文件分工。职责互不重叠、信息只放在它的家里。
| 文件 | 角色 | 改动频率 |
|---|---|---|
plan.md |
项目大纲：定位 / 功能清单 / 数据模型 / 接口 / 验收 | 仅初始化（仅 fix 归档或 fix-plan 确认后回写） |
ARCHITECTURE.md |
代码组织：目录分工 / 新增代码归属 / 启动顺序 | 仅初始化 |
AGENTS.md |
代理协作协议：状态约定 / 文件分工 / 同步要求 | 低频 |
README.md |
用户说明：能做什么 / 怎么装 / 怎么用 / FAQ | 低频 |
TODO.md |
执行台账：步骤 / 子项 / 阻塞 / 来源 / 完成状态 | 每次会话同步 |
| 文件 | 触发条件 | 备注 |
|---|---|---|
fix_<desc>.md |
用户要求审查 / 审计 / 复核，或提供测试反馈 | 缺陷反馈闭环，语义命名；归档时按需修正 plan 描述偏差 |
fix-plan_<desc>.md |
用户提出 plan 之外的新功能 / 新模块 / 验收标准扩展，或要求修订既有 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。 缺陷反馈先收敛；plan 修改先完成写入、来源标注和 fix-plan 归档，再继续推 TODO，避免遗漏外部输入。
- 支持旁路 agent 不打断主 agent。 主 agent 可以持续推进当前 TODO；其他 agent 可在旁路做审查、补充资料、修正文档或提出计划修订，并把结果写进
fix_*、fix-plan_*、HUMAN.md、TODO.md或按需补充文件。主 agent 在同步点读取这些文件后合流，既不丢上下文，也不让反馈散落在聊天里。 - 代理改不动或不应擅自决定的事项必须转 HUMAN.md。 代理把无法完成的人工事项、关键困惑或方向风险打包提交给人类；人类可随时通过修改文件中的状态、反馈或完成结果介入。代理暂停受影响范围，同时继续处理其他不依赖该决策的可执行事项。
- 项目黑话必须交给 NICKNAME.md。 它不是普通词典，而是你的独有命名取向说明；代理进入项目时先读它，避免误解缩写、别名和项目内特殊含义。
- TODO 的
[!]/[~]状态保留废弃条目。 历史决策可回溯，而不是被悄悄删除。 - AGENTS.md 给代理读，README.md 给用户读。 同一信息不在两边重复维护。
| 目录 | 内容 |
|---|---|
template/ |
AGENTS.en.md 与 AGENTS.zh.md 两个模板文件 |
design/ |
设计说明，按 design/en/ 与 design/cn/ 分目录存放 |
workflow/ |
工作流样例，按 workflow/en/ 与 workflow/cn/ 分目录存放 |
example/ |
虚构项目状态快照，按 example/en/ 与 example/cn/ 分目录存放 |
| 我想… | 直接读 |
|---|---|
| 复制一份立刻用 | template/AGENTS.zh.md |
| 理解为什么这样分文件 | design/cn/overview.md |
| 看代理在不同场景怎么走流程 | workflow/cn/01-new-project.md … workflow/cn/07-parallel-agent-intervention.md |
| 看真实项目跑起来长什么样 | example/cn/AGENTS.md、example/cn/TODO.md、example/cn/fix_audit-batch.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 — see LICENSE.