RepoCanon

RepoCanon

为 AI 编码 Agent 提供经过验证的 AGENTS.md 和项目记忆。 一个小小的 .ai/ 文件夹，就能告诉 Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Gemini CLI、Windsurf 和 Cline 如何处理你的项目，而 git 会检查这些信息是否依然准确。

由 Framimo 赞助 — 在浏览器中将任意片段转换为 GIF、WebP、AVIF 或 MP4。

30 秒了解

• 它是什么： 一个轻量的本地项目记忆层（AGENTS.md + .ai/），供每个 AI 编码 Agent 读取：记录代码无法体现的规则、决策和易忽略之处。
• 它能做什么： 一条命令即可为所有工具完成设置，在 Agent 工作时向其提供各模块的规则，并通过 git 将每条规则与代码核对，因此过时的规则会被标记，而非被盲目信任。
• 它有何帮助： Agent 会遵循项目规则，而不是自行猜测（记录规则后，任务通过率从 8% 提升至 100%），并在工作时保持文档准确。它在本地运行，不会调用大模型，也没有任何依赖。

为什么需要它

• Agent 每次执行任务时都会重新学习你的代码仓库。 它们会扫描文件、消耗 token，却仍会遗漏代码中看不出来的规则：状态机、资金和权限方面的不变条件，以及做出某项选择的原因。
• 手写的 CLAUDE.md 和规则文件会悄无声息地过时。 当它们与代码不再一致时，没人会注意到。
• 每种工具都需要自己的文件。 CLAUDE.md、.cursor/rules、Copilot instructions、GEMINI.md、.windsurfrules、.clinerules……

RepoCanon 只保留一个知识层（AGENTS.md + .ai/），让你使用的每种工具都指向它，并通过 git 告诉你代码变更后哪些文档已经过时。它在本地运行，不会调用大模型，也没有任何依赖。

快速开始

需要 Node.js 18+ 和一个 git 仓库。

cd your-project
npx repocanon init          # pick your AI tools (↑/↓, space, enter)

◆ repocanon init · shop

  Stack  Node.js, Express
  Tools  Claude Code, Cursor

Files
  +  .repocanon.json            created
  +  .ai/.gitignore             created
  +  .ai/INDEX.md               created
  +  .ai/PROJECT.md             created
  +  .ai/DOMAIN.md              created
  +  .ai/CONVENTIONS.md         created
  +  .ai/DECISIONS.md           created
  +  .ai/STATE.md               created
  +  .ai/prompts/update.md      created
  +  .ai/modules/_TEMPLATE.md   created
  +  AGENTS.md                  created
  +  CLAUDE.md                  created
  +  .cursor/rules/project.mdc  created

Generated
  ✓  Module map    2 module(s) → .ai/INDEX.md
  ·  Scoped rules  up to date
  ✓  Skills        3 file(s) updated: .ai/skills/rc-verify-change/SKILL.md, .claude/skills/rc-verify-change/SKILL.md, .agents/skills/rc-verify-change/SKILL.md

✓ Knowledge layer created

Next
  npx repocanon setup        connect the MCP server to your tools
  npx repocanon prompt fill  brief for your agent to fill the docs (or ask it over MCP)
  npx repocanon doctor       check the result

接下来让你的 Agent 填写文档。任选一种方式：

• 使用 MCP（npx repocanon setup，详见连接 MCP 服务）：告诉你的 Agent “填写 RepoCanon 文档”。它会调用 rc_prepare_fill，并自行编写 .ai/*.md。
• **不使用 MCP：**运行 npx repocanon prompt fill，然后将输出粘贴到你的 Agent 中。

最后检查结果并提交：

npx repocanon doctor        # lint: size caps, TODOs, broken paths, token budget, content agents can infer
git add -A && git commit -m "Add RepoCanon knowledge layer"
npx repocanon stamp --all   # mark the docs verified at that commit
git commit -am "Verify RepoCanon docs"

◆ repocanon doctor · shop

Warnings (1)
  !  scoped rule files are out of date (2: .cursor/rules/rc-billing.mdc, AGENTS.md) — run: npx repocanon rules

Info (1)
  i  27 TODO placeholder(s) remain in .ai/ — run: repocanon prompt fill

Token budget
  Entry context (AGENTS + PROJECT + INDEX)  ~662 tokens
  Whole repo source                         ~820 tokens
  Entry share of the repo                   80.73%
  → estimates: word-aware for docs, bytes/4 for code

Freshness █████████░ 91/100

! 1 warning · 1 note(s)

Next
  npx repocanon prompt fill
  npx repocanon rules
  npx repocanon doctor       run again after fixing

阅读输出

每条命令都会打印相同的格式：标题、行项目、一行结论，然后是 Next：需要运行的具体命令。符号始终附带文字说明，因此输出在无颜色时也能正常使用（NO_COLOR=1、--no-color、CI 日志、屏幕阅读器）。

每条命令都支持通过 --help 查看选项和示例：npx repocanon status --help。--json 和 --format=github 可为脚本和 CI 提供机器可读的输出。

已经有 CLAUDE.md、Cursor 规则或 Cline 记忆库？

npx repocanon adopt --dry-run   # preview: what goes where, what gets removed
npx repocanon adopt             # import into .ai/ (creates it if needed)
git add -A && git commit -m "Adopt RepoCanon"
npx repocanon adopt --move      # originals become pointers, so tools stop reading two copies

adopt 会读取 CLAUDE.md、GEMINI.md、.windsurfrules、.clinerules、.github/copilot-instructions.md、.cursorrules、始终生效的 .cursor/rules/*.mdc、仓库级 Copilot 指令以及 Cline 的 memory-bank/。它会将各个部分归入对应文档（术语表 → DOMAIN，决策 → DECISIONS，进展 → STATE，概览 → PROJECT，其余内容 → CONVENTIONS），剔除目录树、依赖列表、粘贴的代码和机密信息，并告知你因此节省了多少令牌。已限定适用文件范围的规则会保留原位。重新运行时会跳过已导入的内容；--move 绝不会处理有未提交更改的文件。

你将获得什么

AGENTS.md                 entry point every agent reads: commands, a digest of your rules and decisions, Definition of Done
.ai/
  PROJECT.md              purpose, stack, boundaries
  INDEX.md                path → module map (auto block refreshed by `analyze`)
  DOMAIN.md               business rules, states, invariants, glossary
  CONVENTIONS.md          coding style and patterns
  DECISIONS.md            why things are built this way
  STATE.md                current focus and recent changes
  modules/<name>.md       one doc per module: purpose, invariants, flow, code map, gotchas
.repocanon.json           config (presets, modules, excludes, chosen tools)
CLAUDE.md, .cursor/…      small pointer files, only for the tools you pick

文档是语义索引，而不是代码副本。文档与代码不一致时，以代码为准，并修正文档。

选择工具

init 会打开一个选择器，让你选择哪些 AI 工具应读取知识层。它始终会写入 AGENTS.md；你选择的每个工具都会获得一个简短的指针文件：

• 可随时重新运行。 init 会重新打开选择器，并显示你之前的选择；每个工具会标记为 set up 或 detected。如果没有变化，则会显示 Up to date。
• 取消勾选某个工具后，init 会询问是否移除它的 RepoCanon 区块。只会移除该区块：你自己的文本会保留，且只有文件中没有其他内容时才会删除文件。
• 脚本和 CI（无需终端）：使用 --targets=claude,cursor、--targets=all 或 --targets=none；--yes 保留已保存的选择；--prune 移除不再选择的工具对应区块。

作用域规则：在 Agent 编辑的位置提供恰到好处的模块知识

npx repocanon rules 会将每份已填写的模块文档转换为规则文件，只有当工具中的 Agent 编辑该模块的文件时才会加载这些规则——其他时候不会调用工具，也不会额外消耗令牌：

• .ai/modules/<module>.md 是唯一的信息源。生成的文件会在文件头注明这一点；请编辑文档，然后再次运行 rules。
• 只有你在 init 中选择的工具才会生成文件。嵌套的 AGENTS.md 指针默认关闭；在 .repocanon.json 中设置 "nestedAgents": true 可启用。
• 文档仍是空模板的模块不会生成任何文件。已删除的文档和取消选择的工具所对应的生成文件会被清理；你自己的规则文件绝不会被触碰。
• init 会自动为你运行 rules；doctor 会在文件过期时发出警告；rules --check 会在文件尚未重新生成时使 CI 失败。

Skills：仅在需要时加载的仓库自有检查

npx repocanon skills（init 也会运行）会生成一份 Agent Skill，告诉 Agent 如何验证此仓库中的更改：.ai/skills/rc-verify-change/SKILL.md。Agent 的上下文中只有一行描述；当 Agent 准备说“完成”时，才会加载正文。

• 命令来自仓库本身：package.json / composer.json 脚本（使用你的包管理器运行）、Makefile、justfile、Taskfile.yml，以及 .github/workflows/*.yml 或 .gitlab-ci.yml 中的 run: 步骤。每条命令都会注明其来源，重复项会合并，步骤按顺序运行：格式化 → lint → 类型检查 → 测试（汇总用的 make check 会先运行）。
• 安装、部署、发布、使用 CI 密钥的行，以及 watch 或开发服务器，都不会包含在内。
• .ai/skills/ 是唯一需要编辑的位置。修改生成的技能后，RepoCanon 就会停止重新生成它；添加你自己的 .ai/skills/<name>/SKILL.md，它也会被复制出去。

仅会为你选择的工具写入副本，副本带有 “Generated by RepoCanon” 标头；取消选择工具时会将其删除。RepoCanon 从未写入过的同名技能绝不会被覆盖。名称无效（必须为小写、使用连字符，并与文件夹名称一致）、缺少描述或包含密钥的技能不会被复制，doctor 会说明原因。Windsurf 和 Cline 目前还不会读取 skills 文件夹。

Monorepo

RepoCanon 会读取 pnpm、npm、yarn 和 bun workspaces、lerna、nx（project.json）、turbo、go.work、Cargo workspaces 和 uv workspaces。然后：

• 每个库包都是一个模块：packages/ui（@acme/ui）→ ui。
• 当应用的框架文件夹显示有两个或更多功能时，应用会按功能拆分：apps/web（Next.js）→ web-billing、web-pricing；apps/api（NestJS）→ api-users、api-billing。否则，应用就是一个模块。
• 包之外的根目录工具不属于任何模块。名称相同的两个包会按路径命名（apps-web、packages-web）。

.ai/INDEX.md 会添加一个 Workspace 表格（包、路径、应用或包、技术栈），填充说明也会注明这是一个 monorepo。若要以不同方式拆分，可在 .repocanon.json 中设置 moduleRoots 或 modules，或设置固定的 preset；任意一项都会关闭工作区拆分。

Claims：与证明它们的代码绑定的规则

文档中的普通规则，其新鲜程度取决于整篇文档。为重要规则添加注释后，RepoCanon 会逐条检查：

## Invariants
- Money is integer cents. 
- Floats are rejected. 
- Never round twice.

• repocanon claims 会列出每条 claim 及其级别和状态。遇到 broken claim 时退出码为 1；使用 --ci 时，遇到 stale claim 也会如此。
• doctor 会将 broken claim 报告为错误，将 stale claim 报告为警告。
• rc_context 和编辑时钩子会在文档中标记 stale claim，即使整篇文档看起来仍然是最新的。
• stamp <doc>（以及 rc_stamp）会锁定其验证的文档中的 claims。代码有未提交更改的 claim 不会被锁定。
• 哈希由工具计算，绝不手动编写。符号查找基于模式（JS/TS、Python、Go、Rust、PHP、Java 风格的方法），而非解析器；如果找不到符号，请锚定到文件。

日常工作流

在你或你的 Agent 修改代码后：

npx repocanon sync          # which docs are stale, which files changed, what to inspect
# your agent updates the affected .ai/*.md (or: npx repocanon prompt update → paste)
git commit -am "Update billing + docs"
npx repocanon stamp billing # mark only the docs you actually re-checked (code must be committed)

stamp 会编辑该文档中的 verified_at（以及 verified_by: human）；它会随你的下一次提交一并提交。

代码变更后，status 和 sync 会显示有哪些内容出现了偏差：

◆ repocanon status · shop

  ✓  .ai/INDEX.md            fresh  2 commit(s) since verify
  ✓  .ai/PROJECT.md          fresh  2 commit(s) since verify
  ✓  .ai/DOMAIN.md           fresh  2 commit(s) since verify
  ✓  .ai/CONVENTIONS.md      fresh  2 commit(s) since verify
  ✓  .ai/DECISIONS.md        fresh  2 commit(s) since verify
  ✓  .ai/STATE.md            fresh  2 commit(s) since verify
  ✓  .ai/modules/auth.md     fresh
  !  .ai/modules/billing.md  stale  1 code file(s) changed since verify

Freshness █████████░ 91/100

! 1 stale doc(s) · 8 docs

Next
  npx repocanon sync         what changed and which docs to update
  npx repocanon stamp <doc>  after you re-checked a doc against the code

◆ repocanon sync · shop

Docs to update (1)
  !  billing  1 file(s) changed since a1b2c3d
      src/modules/billing/refund.js
      inspect: git diff a1b2c3d -- src/modules/billing/

! 1 doc(s) to update · 1 up to date · HEAD a1b2c3d

Next
  update the docs above        only where behaviour, rules or flow changed
  npx repocanon stamp billing  after committing, for each doc you re-checked

连接 MCP 后，只需说 “更新上下文文档”：Agent 会调用 rc_sync_report、编辑文档、通过 rc_propose_adr / rc_checkpoint_state 记录决策和进度、用 rc_stamp 标记已重新检查的内容，并通过 rc_verify 完成验证。Agent 标记会写入 verified_by: agent：该文档会被视为最新，但 status 会显示 fresh (agent)，而 doctor 和 PR 报告会列出该文档，供人工重新检查。人工运行 repocanon stamp 即可替换该标记。

可选：npx repocanon hook 会安装一个 pre-commit hook。代码变更时若没有更新任何 .ai/ 文件，它会发出警告（绝不会阻止提交）；若提交会将 API 密钥、令牌或密码添加到 AGENTS.md 或 .ai/ 文档中，则会阻止提交（可通过 git commit --no-verify 覆盖）。运行密钥检查需要在本地安装 RepoCanon（npm i -D repocanon）或全局安装。

连接 MCP 服务

repocanon mcp 是一个 stdio Model Context Protocol 服务。Agent 使用它获取有预算限制的上下文包，而不是扫描代码库；还可以用它更新文档，无需复制粘贴。

让 RepoCanon 写入配置：

npx repocanon setup              # the tools you picked in init
npx repocanon setup cursor copilot

◆ repocanon setup · shop

  +  .mcp.json         created · repocanon server added
  +  .cursor/mcp.json  created · repocanon server added

✓ MCP server registered in 2 config(s)

Next
  restart or reload your tool                     so it starts the server
  ask your agent: "use rc_context for this task"  to check it works

setup 只添加它自己的 repocanon 条目：文件中的其他服务和设置保持不变，重复运行也不会造成任何更改。对于非纯 JSON 文件（例如带注释的 .vscode/mcp.json），它会保持原样，并提供可供粘贴的代码块。对于使用全局配置的工具（Windsurf、Cline、Codex），它会生成包含项目路径、可直接粘贴的代码片段。

**也可以手动添加。**大多数工具都使用以下代码块：

{
  "mcpServers": {
    "repocanon": { "command": "npx", "args": ["-y", "repocanon", "mcp"] }
  }
}

服务会处理其启动所在的文件夹。全局配置（Windsurf、Cline）通常会在项目目录之外启动，因此请添加路径："args": ["-y", "repocanon", "mcp", "--root=/abs/path/to/project"]。

写入工具会在修改文件前进行验证：每个字段一行、长度限制，以及不得包含机密、粘贴的代码、目录树或依赖项列表。被拒绝的写入不会更改任何内容。每个工具都带有 MCP 注释（readOnlyHint），因此客户端可以自动批准只读工具。

Claude Code 插件

该插件只需安装一次，即可将 Claude Code 连接到知识层，并在 Claude 工作期间保持文档更新：

/plugin marketplace add awalhadi/repo-canon
/plugin install repocanon@repocanon

在没有 .ai/ 文件夹的项目中，这些钩子不会执行。它们会运行 npx repocanon，因此首次会话会下载一次。

在 CI 中使用

GitHub Action 会检查每个拉取请求，在更改的行上标注问题，并持续更新一条摘要评论：

# .github/workflows/repocanon.yml
name: repocanon
on: [pull_request]
permissions:
  contents: read
  pull-requests: write          # for the summary comment
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # full history, so freshness can be computed
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - uses: awalhadi/[email protected]
        with:
          fail-on: error           # error (default) | stale | never

评论如下：

RepoCanon：⚠️ 1 个模块已更改，但文档未更新

模块	代码已更改	文档
billing	3 个文件	⚠️ 未更新 — .ai/modules/billing.md

新鲜度 82/100 · 1 份过期，0 份损坏，2 份未验证

只有有意义的代码更改才会计入：测试、说明文档和锁文件的修改，以及仅空白字符的更改，都不会导致文档过期。使用 driftIgnore 添加自己的模式，或设置 "drift": "all" 来计入所有更改。

不使用 Action——使用普通命令执行相同的检查：

# .github/workflows/repocanon.yml
name: repocanon
on: [pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # full history, so verified_at commits resolve
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx -y repocanon doctor --ci   # fails on errors; add --strict to fail on warnings too
      - run: npx -y repocanon status --ci   # fails on stale or broken docs
      - run: npx -y repocanon rules --check # fails when scoped rule files are out of date

命令

全局标志：--root=<dir> 对其他文件夹运行；--version；--help。

配置

.repocanon.json（由 init 创建）：

{
  "preset": "auto",
  "moduleRoots": ["src/domains"],
  "modules": { "checkout": ["app/Services/Checkout/", "app/Models/Order.php"] },
  "exclude": ["legacy/", "vendor/"],
  "targets": ["claude", "cursor"],
  "nestedAgents": false,
  "driftIgnore": ["src/generated/", "*.snap"]
}

• preset：auto（根据检测到的技术栈自动选择）或以下选项之一：laravel nextjs nuxt react vue nestjs node fastapi django rails go tauri。预设会跨层合并同一个领域：

  预设	查找内容
  Laravel	Billing = Services、Actions、Controllers、Pages 文件夹；也支持扁平应用：Invoice.php + InvoiceController.php + StoreInvoiceRequest.php → invoice；nwidart Modules/、Filament 资源
  Next.js	App Router 路由段（会遍历 (groups)；跳过 [dynamic]、_private、@slots；api/billing 会合并到 billing），以及 src/features、src/modules
  FastAPI	routers/users.py + models/user.py + schemas/user.py → user（位于 app/ 或 src/<pkg>/ 下），以及 app/modules、app/domains
  Go	internal/*、pkg/*、cmd/*；按领域合并分层应用（internal/handler/user + internal/service/user → user）
  NestJS	除 app.module.ts 外的所有 *.module.ts 文件夹

  名称至少要出现在两个层中才会成为模块，因此单独的 User.php 或 health.py 不会被识别为模块。

• moduleRoots：额外的文件夹，其子文件夹均视为模块。

• modules：显式指定模块 → 路径；覆盖同名的已检测模块。

• exclude：在所有地方忽略的路径前缀。

• targets：init 为其完成配置的 AI 工具（由选择器管理）。

• nestedAgents：也在每个模块文件夹中写入指针文件 AGENTS.md（默认值为 false）。

• entryDigest：在 AGENTS.md 区块中保留 .ai/CONVENTIONS.md 和 .ai/DECISIONS.md 的摘要（每项决策占一行，最多约 700 个 token）（默认值为 true）。Agent 会可靠地遵循入口文件中的内容，且常常跳过指向其他文件的指针；设为 false 时只保留指针。rules 会重新生成摘要；若摘要过时，doctor、rules --check 和 PR 报告会标记出来。

• driftIgnore：额外指定其变更永远不会导致文档过时的路径（以 / 结尾的文件夹前缀、* 和 ** 通配符）。测试、说明文档、锁文件以及仅涉及空白字符的编辑始终会被忽略；"drift": "all" 会关闭此行为。

基准测试

项目知识是否有帮助？RepoCanon 提供这些知识的效果是否优于手写的 AGENTS.md？Claude Code（claude-sonnet-5-5，CLI 2.1.178）在 JavaScript、Python、PHP 和 Rust 项目中运行了 8 项任务，在 4 种条件下每种运行 5 次：共 160 次运行，日期为 2026-10-27。每项任务都会涉及代码中无法体现的项目规则。只有隐藏测试和规则检查均通过，运行才算通过。

这些结果说明了什么，又没有说明什么：

• **关键在于把规则写下来。**没有规则时，Agent 仅在 8% 的运行中通过；有规则时，每次运行都通过。
• **在这些任务中，RepoCanon 的正确率并不比优质的手写 AGENTS.md 高，成本却约为其 1.5 倍。**其 Agent 每次运行会读取 6 个以上的 .ai/ 文档，并进行约两倍数量的编辑，遵循 AGENTS.md 中的完成定义。两种知识格式的通过率都达到 100%，因此此基准测试无法从正确性上区分二者。
• 0.6 新增的规则摘要将成本降低了 8%，相较于仅指针的设计。Claude Code 在这些无头运行中从未调用 MCP 工具或技能，而是直接读取文件。
• **本测试未衡量 RepoCanon 应发挥作用的方面：**文档随时间偏离代码、大型代码库以及众多工具。下一轮基准测试将针对这些方面。

测试方法、任务及重新运行方式：bench/README.md。原始结果：bench/results/2026-10-27/。

Drift 试点：文档中描述的值已在代码中更改，文档却没有更新

4 个漂移任务都会验证文档，然后提交对文档所述某个值（费率、默认值、上限或错误代码）的更改。隐藏测试期望代码采用新值。2026-10-28 共运行 12 次，每个任务和条件各运行一次：

• 过时文档没有误导 Agent。 当更改后的值位于 Agent 为完成任务会读取的文件中时，即使没有提示，claude-sonnet-5-5 也会相信代码。这种设计无法体现过时警告的效果，因此没有运行原计划的 60 次测试。
• 钩子确实触发了（每次 0.7 运行都收到了对应模块的规则），而且成本更高，部分原因是回合结束钩子要求 Agent 为没有文档的文件夹编写文档。此问题现已修复；请参阅下方的成本测试。
• 要区分不同条件，漂移的事实必须位于 Agent 通常不会查找的地方。请参阅下方的跨模块测试。

原始结果：bench/results/2026-10-28-drift/。

成本测试：精简入口文件（0.7）

试点中的工具调用次数显示，额外成本来自 AGENTS.md 中的两条指令：读取顺序（每次运行读取 5–10 份知识文档）和强制的完成定义（9–15 次编辑）。0.7 替换了这两条指令：入口文件只列出有内容的文档，并且仅在规则、流程或决策发生更改时才要求编辑文档。2026-10-28 使用 claude-sonnet-5-5 运行了 44 次：

• 不设读取顺序也能保持正确性： 每次运行都通过了测试，包括规则仅存在于模块文档中的核心任务。
• 剩余差距在于文档维护，而非阅读。 每次运行约多出两次编辑，因为回合结束钩子会要求 Agent 更新其工作所在模块的文档。手写的 AGENTS.md 从不执行这项工作，因此这是保持文档最新的代价，≤1.2× 的目标未能实现。

原始结果：bench/results/2026-10-28-cost/ 和 2026-10-28-cost2/。

跨模块偏差：文档指错了位置，而修复在另一个模块中

node-cancel-xdrift：文档称 cancelOrder 会补充库存，而仓库监听器只记录发货。后续的一次提交将补充库存的逻辑移到了监听 order.cancelled 的仓库监听器中。照文档操作会补充两次库存。进行了三轮测试，每轮 9 次运行（每种条件 3 次）：先是偏差出现在最新提交中，然后埋在 12 次无关提交之下，最后在相同条件下增加了测试器对文档的检查。

• 正确性：没有差异。 每种条件下的每次运行，都找到了监听器，且没有重复补充库存。Agent 阅读了代码、近期历史记录以及自己失败的测试，并且更相信这些内容，而不是文档。
• 文档维护：差异明显。 RepoCanon Agent 每次运行都会更正文档中的错误表述。AGENTS.md Agent 一次也没有修正：这次没有误导任何人的文档，对下一个 Agent 和其他人来说仍然是错的。根据 Agent 自己的总结评估的前几轮也得出了相同结论（RepoCanon 为 12/12，AGENTS.md 为 2/6）。
• 这项任务的成本相近，为 AGENTS.md 的 1.05–1.13 倍。
• 样本量较小（每个单元 3 次运行）；这些数字反映的是趋势，而非发生率。原始结果：xdrift、buried、doc check。

对比

仓库打包工具向 Agent 展示代码是什么。RepoCanon 记录代码无法表达的内容——规则、决策、边界——并在这些记录过时后告知你。

常见问题

它会调用 LLM 或上传我的代码吗？ 不会。RepoCanon 从不发起网络请求。由你自己的 Agent 读取和编写文档。

如果 Agent 把机密粘贴到文档中怎么办？ doctor 会将其报告为错误（因此 doctor --ci 会失败），npx repocanon secrets 会将其脱敏后列出，提交前钩子也会阻止提交。在该行使用 `` 标记已知的误报。

如果有人植入针对 Agent 的指令怎么办？ 拉取请求、依赖项或构建步骤可能会在 AGENTS.md、.ai/ 或 CLAUDE.md 中添加 Agent 会遵循的文本。doctor 会对隐藏的 Unicode 字符（双向覆盖字符、零宽标记、标签字符）、“忽略之前的指令”式覆盖指令、向用户隐瞒工作的规则、伪造的 <system> 标记以及 curl … | sh 报错，并对 git 未跟踪的指令文件发出警告。MCP 写入时也会拒绝相同的文本，提交前钩子也会阻止它。使用 `` 标记有意添加的文本。

它适用于 ChatGPT 吗？ OpenAI Codex 原生读取 AGENTS.md。浏览器中的 ChatGPT 无法查看你的仓库，但 npx repocanon context "your task" 会生成可供你粘贴的内容包。

它会覆盖我的 CLAUDE.md 或其他规则文件吗？ 不会。它会添加或更新一个标记清晰的代码块，并保留文件的其余部分。只有通过 init --force 才会替换 .ai/ 中的核心文档。

单体仓库呢？ 目前可使用 moduleRoots 或 modules 映射软件包。按软件包划分的知识层已列入路线图。

我可以把它用作库吗？ 可以：require('repocanon') 会公开 CLI 使用的相同函数。请参阅 CONTRIBUTING。

原则

1. 文档是语义索引，绝不是代码副本。如有冲突，以代码为准。
2. 渐进式披露：AGENTS.md（含规则摘要）→ PROJECT → INDEX → 一个模块 → 代码。
3. 不变量和业务规则优先于实现细节。
4. 新鲜度根据 git 计算，而非承诺保证。
5. 零依赖，Node.js 18+。

路线图与贡献

• 已完成和后续计划：docs/ROADMAP.md
• 设计与威胁模型：docs/ARCHITECTURE.md
• 从源代码运行、项目结构、测试：docs/CONTRIBUTING.md
• 发布到 npm 和 MCP Registry（mcp-publisher publish）：docs/PUBLISHING.md
• Bug 和想法：GitHub issues

赞助商

Framimo — 在浏览器中直接将任意片段转换为 GIF、WebP、AVIF 或 MP4。剪辑、裁剪、调整大小并压缩动画；文件均在你的设备上处理。

想要赞助 RepoCanon？提交 issue。

许可证

MIT © Md. A Awal Hadi