RepoCanon

RepoCanon

AI コーディングエージェント向けの検証済み AGENTS.md とプロジェクトメモリです。 小さな .ai/ フォルダーひとつで、Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Gemini CLI、Windsurf、Cline にプロジェクトの仕組みを伝え、git がその内容が今も正しいかをチェックします。

Framimo の提供でお送りします。ブラウザー上で、あらゆるクリップを GIF、WebP、AVIF、MP4 に変換できます。

30 秒でわかること

• これは何か： すべての AI コーディングエージェントが読む、小さなローカルのプロジェクトメモリレイヤー（AGENTS.md + .ai/）です。ルール、決定事項、コードだけではわからない注意点を記録します。
• できること： 1 つのコマンドで、すべてのツール向けにセットアップできます。作業中は各モジュールのルールをエージェントに届け、すべてのルールを git でコードと照合するため、古くなったルールを信頼するのではなく、警告として検出できます。
• 役立つ理由： エージェントは推測ではなく、プロジェクトのルールに従います（ルールを書き留めた後、タスクの合格率は 8% から 100% に向上しました）。作業中にドキュメントも正しく保たれます。ローカルで動作し、LLM を呼び出さず、依存関係もありません。

選ばれる理由

• エージェントはタスクのたびにリポジトリの情報を学び直します。 ファイルをスキャンしてトークンを消費しても、コードには書かれていないルールを見落とします。ステートマシン、金銭や権限に関する不変条件、ある選択をした理由などです。
• 手書きの CLAUDE.md やルールファイルは、気づかれないまま古くなります。 コードと一致しなくなっても、誰も気づきません。
• ツールごとに別のファイルが必要です。 CLAUDE.md、.cursor/rules、Copilot の指示、GEMINI.md、.windsurfrules、.clinerules などです。

RepoCanon は単一のナレッジレイヤー（AGENTS.md + .ai/）を維持し、使用するすべてのツールから参照できるようにします。また、コードの変更後にどのドキュメントが古くなったかを git で知らせます。ローカルで動作し、LLM を呼び出さず、依存関係もありません。

クイックスタート

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

次に、エージェントにドキュメントを記入してもらいます。方法は 2 つあります。

• MCP を使う場合（npx repocanon setup、詳細）：エージェントに 「RepoCanon のドキュメントを記入して」 と伝えます。エージェントが rc_prepare_fill を呼び出し、.ai/*.md に自分で書き込みます。
• MCP を使わない場合： npx repocanon prompt fill を実行し、出力をエージェントに貼り付けます。

最後に、結果を確認してコミットします。

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 は選択しなくなったツールのブロックを削除します。

スコープ付きルール：エージェントが編集するモジュールに、そのモジュールの知識を正確に配置

npx repocanon rules は、内容が記入された各モジュールドキュメントをルールファイルに変換します。これらのファイルは、エージェントがそのモジュールのファイルを編集している間だけツールに読み込まれます。他の場所では、ツール呼び出しもトークンの追加消費もありません。

• .ai/modules/<module>.md が唯一の情報源です。生成されたファイルのヘッダーにはその旨が記載されます。ドキュメントを編集してから、再度 rules を実行してください。
• ファイルは init で選択したツール向けにのみ作成されます。ネストされた AGENTS.md ポインターはデフォルトで無効です。有効にするには、.repocanon.json に "nestedAgents": true を設定します。
• ドキュメントが空のテンプレートのままのモジュールには、何も作成されません。削除されたドキュメントや選択解除されたツールについては、生成ファイルがクリーンアップされます。独自のルールファイルには一切触れません。
• init は rules を自動で実行します。doctor はファイルが古い場合に警告し、rules --check は再生成されるまで CI を失敗させます。

スキル：必要なときだけ読み込まれる、リポジトリ独自のチェック

npx repocanon skills（init の実行時にも実行されます）は、このリポジトリで変更を検証する方法をエージェントに伝える Agent Skill を .ai/skills/rc-verify-change/SKILL.md に書き込みます。エージェントのコンテキストに含まれるのは1行の説明だけで、本文はエージェントが「完了しました」と伝える直前に読み込まれます。

• コマンドはリポジトリ自体から取得されます：package.json / composer.json のスクリプト（パッケージマネージャーで実行）、Makefile、justfile、Taskfile.yml、および .github/workflows/*.yml または .gitlab-ci.yml の run: ステップです。それぞれのコマンドが検出元を示し、重複は統合され、ステップは順番に実行されます：format → lint → typecheck → test（集約コマンド make check が最初に実行されます）。
• インストール、デプロイ、公開、CI シークレットを使用する処理、および監視サーバーや開発サーバーは含まれません。
• 編集する場所は .ai/skills/ のみです。生成されたスキルを変更すると、RepoCanon はそのスキルを再生成しなくなります。独自の .ai/skills/<name>/SKILL.md を追加すると、それもコピーされます。

コピーが作成されるのは選択したツールに限られ、「Generated by RepoCanon」ヘッダーが付き、ツールの選択を解除すると削除されます。同じ名前のスキルが RepoCanon によって作成されたものでなければ、上書きされることはありません。名前が無効なスキル（小文字とハイフンを使い、フォルダー名と一致させる必要があります）、説明がないスキル、またはシークレットを含むスキルはコピーされず、その理由は doctor が表示します。Windsurf と Cline は、まだスキルフォルダーを読み込みません。

モノレポ

RepoCanon は、pnpm、npm、yarn、bun のワークスペース、lerna、nx（project.json）、turbo、go.work、Cargo のワークスペース、uv のワークスペースを読み込みます。その後、次のように処理します：

• 各ライブラリパッケージが1つのモジュールになります：packages/ui（@acme/ui）→ ui。
• アプリは、フレームワークのフォルダーから2つ以上の機能が確認できる場合、機能ごとに分割されます：apps/web（Next.js）→ web-billing、web-pricing、apps/api（NestJS）→ api-users、api-billing。それ以外の場合、アプリは1つのモジュールになります。
• パッケージの外にあるルートのツール類は、どのモジュールにも属しません。同じ名前のパッケージが2つある場合、パスを使った名前が付けられます（apps-web、packages-web）。

.ai/INDEX.md には、ワークスペースの表（パッケージ、パス、アプリまたはパッケージ、スタック）が追加され、入力用ブリーフにはモノレポであることが記載されます。分割方法を変更するには、.repocanon.json で moduleRoots または modules、あるいは固定の preset を設定します。これらを設定すると、ワークスペースの分割は無効になります。

Claims：根拠となるコードにひも付いたルール

ドキュメントに記された通常のルールは、ドキュメント全体がどれだけ最新かに左右されます。重要なルールに注釈を付けると、RepoCanon は各ルールを個別にチェックします：

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

• repocanon claims は、すべての claim をレベルと状態とともに一覧表示します。broken の claim がある場合、または --ci を指定して stale の claim がある場合は、終了コード 1 を返します。
• doctor は broken の claim をエラーとして、stale の claim を警告として報告します。
• rc_context と編集時フックは、ドキュメント全体が最新に見える場合でも、そのドキュメントに stale の claim があることを示します。
• stamp <doc>（および rc_stamp）は、検証するドキュメントの claim をロックします。コードに未コミットの変更がある claim はロックされません。
• ハッシュはツールが計算するもので、手作業で記述することはありません。シンボルの検索はパターンベースです（JS/TS、Python、Go、Rust、PHP、Java スタイルのメソッド）。パーサーは使いません。シンボルが見つからない場合は、ファイルをアンカーにしてください。

日々のワークフロー

自分またはエージェントがコードを変更した後：

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)

スタンプによって、そのドキュメントの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を接続した状態で「コンテキストドキュメントを更新して」と伝えるだけで、エージェントがrc_sync_reportを呼び出し、ドキュメントを編集して、rc_propose_adr／rc_checkpoint_stateで決定事項と進捗を記録し、再確認した箇所にrc_stampでスタンプを付け、rc_verifyで完了します。エージェントによるスタンプではverified_by: agentが記録されます。ドキュメントは最新として扱われますが、statusにはfresh (agent)と表示され、doctorとPRレポートにも一覧表示されるため、人が再確認できます。人がrepocanon stampを実行すると、そのスタンプが置き換えられます。

任意：npx repocanon hookを実行すると、コミット前フックがインストールされます。コードが変更されたのに.ai/の更新がない場合に警告し（処理はブロックしません）、APIキー、トークン、またはパスワードをAGENTS.mdまたは.ai/ドキュメントに追加するコミットはブロックします（git commit --no-verifyで回避できます）。シークレットチェックには、RepoCanonをローカル（npm i -D repocanon）またはグローバルにインストールする必要があります。

MCP サーバーに接続する

repocanon mcp は stdio の Model Context Protocol サーバーです。エージェントはリポジトリをスキャンする代わりに、予算内のコンテキストパックを取得し、コピー＆ペーストせずにドキュメントを更新できます。

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"]。

書き込みツールはファイルを変更する前に検証を行います。各フィールドは 1 行であること、長さの上限を守ること、シークレット、貼り付けたコード、ツリー、依存関係の一覧を含めないことが条件です。書き込みが拒否された場合、何も変更されません。各ツールには MCP アノテーション（readOnlyHint）が付いているため、クライアントは読み取り専用のツールを自動承認できます。

Claude Code プラグイン

このプラグインをインストールすると、Claude Code がナレッジレイヤーに接続され、Claude の作業中もドキュメントが最新の状態に保たれます。

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

フックは .ai/ フォルダーがないプロジェクトでは何もしません。npx repocanon を実行するため、最初のセッションで一度だけダウンロードされます。

CI での使用

GitHub Action はすべてのプルリクエストをチェックし、変更された行に問題を注釈し、最新のサマリーコメントを常に 1 つ維持します：

# .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 file(s)	⚠️ 未更新 — .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。

設定

init によって作成される .repocanon.json：

{
  "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 のいずれかです。プリセットは、1 つのドメインを複数のレイヤーにまたがって統合します。

  プリセット	検出対象
  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 フォルダー

  モジュールとして認識されるには、名前が少なくとも 2 つのレイヤーに存在する必要があります。そのため、単独の User.php や health.py はモジュールになりません。

• moduleRoots：子フォルダーをモジュールとして扱う追加フォルダーです。

• modules：明示的に指定するモジュール → パスです。同じ名前の検出済みモジュールを上書きします。

• exclude：すべての場所で無視するパスのプレフィックスです。

• targets：init で設定する AI ツールです（ピッカーで管理します）。

• nestedAgents：各モジュールフォルダーにもポインタとなる AGENTS.md を書き込みます（デフォルトは false）。

• entryDigest：.ai/CONVENTIONS.md と .ai/DECISIONS.md のダイジェスト（各決定事項につき 1 行、最大約 700 トークン）を AGENTS.md ブロックに保持します（デフォルトは true）。エージェントはエントリーファイルに記載された内容には確実に従いますが、別ファイルへのポインタは見落とすことがよくあります。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 つのタスクを実行し、2026-10-27 に 4 つの条件それぞれで 5 回ずつ試しました。合計 160 回です。各タスクでは、コードからは分からないプロジェクトのルールに関わります。隠しテストとルールチェックの両方に合格した実行を、合格として数えます。

この結果が示すこと、そして示さないこと：

• 重要なのは、ルールを文書に記録することです。 ルールがない場合、エージェントが合格した実行は 8% でしたが、ルールがある場合はすべての実行に合格しました。
• これらのタスクでは、RepoCanon の正確性は良質な手書きの AGENTS.md と同等で、コストは約 1.5 倍でした。 RepoCanon のエージェントは 1 回の実行につき .ai/ ドキュメントを 6 つ以上読み、約 2 倍の編集を行い、AGENTS.md の完了の定義に従いました。どちらの知識形式も 100% に達したため、このベンチマークでは正確性の差を判定できません。
• 0.6 で追加されたルールダイジェストにより、ポインタのみの設計と比べてコストが 8% 削減されました。 これらのヘッドレス実行では、Claude Code は MCP ツールもスキルも呼び出さず、ファイルを直接読みました。
• RepoCanon が役立つはずの場面は、ここでは測定していません。 時間の経過によるコードとドキュメントの乖離、大規模なリポジトリ、多数のツールです。次回のベンチマークではこれらを対象にします。

手法、タスク、再実行方法：bench/README.md。生データ：bench/results/2026-10-27/。

Drift pilot: コードでドキュメント記載の値が変更されたが、ドキュメントは更新されていない

4つのドリフトタスクはそれぞれ、まずドキュメントを確認し、その後、ドキュメントに記載された値の1つ（手数料率、デフォルト値、上限、エラーコード）を変更するコミットを行います。隠しテストでは、コードの新しい値が想定されます。2026-10-28に、タスクと条件の組み合わせごとに1回、計12回実行しました。

• 古いドキュメントがエージェントを誤らせることはありませんでした。 変更された値が、タスクのためにエージェントが読むファイルにある場合、指示されなくてもclaude-sonnet-5-5はコードを信頼します。この設計では古い情報への警告の効果を示せないため、予定していた60回の実行は行いませんでした。
• フックは実行され（0.7のすべての実行で、該当モジュールのルールが適用されました）、コストは増加しました。その一因は、ターン終了時のフックが、ドキュメントのないフォルダーについてもエージェントに記述を求めていたことです。これは修正済みです。コスト検証の項を参照してください。
• 条件間の差を明らかにできるドリフトには、変更された事実が、エージェントが通常は確認しない場所にある必要があります。モジュール横断の検証の項を参照してください。

生データ：bench/results/2026-10-28-drift/。

コスト検証：より軽量なエントリーファイル（0.7）

パイロットのツール使用回数から、追加コストの原因はAGENTS.mdにある2つの指示だと分かりました。読み取り順序（実行ごとにナレッジドキュメントを5～10件読む）と、必須の完了定義（9～15件の編集）です。0.7では両方を置き換えました。エントリーには内容のあるドキュメントだけを列挙し、ルール、フロー、または判断が変わった場合にのみドキュメントを編集するよう求めます。2026-10-28にclaude-sonnet-5-5で44回実行しました。

• 読み取り順序がなくても正確性は維持されました。 モジュールドキュメントにのみルールが記載されたコアタスクも含め、すべての実行が合格しました。
• 残る差は読み取りではなく、ドキュメントの保守にあります。 実行ごとに約2件の追加編集が発生するのは、ターン終了時のフックが、作業対象のモジュールドキュメントを更新するようエージェントに求めるためです。手書きのAGENTS.mdではこの作業は発生しません。そのため、ドキュメントを最新に保つためのコストとなり、目標の≤1.2×は達成できませんでした。

生データ：bench/results/2026-10-28-cost/および2026-10-28-cost2/。

モジュール間のずれ：ドキュメントの記述が誤った場所を指し、修正は別のモジュールにある

node-cancel-xdrift：ドキュメントには、cancelOrder が在庫を補充し、倉庫のリスナーは出荷を記録するだけだと書かれています。その後のコミットで、在庫の補充処理が order.cancelled の倉庫リスナーに移されます。ドキュメントに従うと、在庫を二重に補充してしまいます。各条件3回、計3ラウンドで各9回実行しました。ずれが最新のコミットにある場合、それと無関係なコミット12件の下に埋もれている場合、さらにその後に採点用チェックでドキュメントを確認する場合です。

• 正しさに違いはありません。 どの条件でも、すべての実行でリスナーを見つけ、在庫の二重補充を避けました。エージェントはコード、最近の履歴、自らの失敗テストを読み、ドキュメントよりそれらを信頼しました。
• ドキュメントの保守には明確な違いがあります。 RepoCanon のエージェントは、すべての実行で誤った記述を修正しました。AGENTS.md のエージェントは一度も修正しませんでした。今回は誰も誤らせなかったドキュメントも、次のエージェントや人にとっては依然として誤ったままです。エージェント自身の要約を基に評価した以前のラウンドでも同じ傾向が見られます（RepoCanon 12/12、AGENTS.md 2/6）。
• このタスクのコストはほぼ同じで、AGENTS.md の1.05～1.13倍でした。
• サンプル数は少なく（各セル3回）、数値が示すのは傾向であり、発生率ではありません。生データ：xdrift、埋もれた状態、ドキュメントのチェック。

比較

リポジトリのパッカーは、エージェントに「コードが何であるか」を示します。RepoCanon は、コードだけでは伝えられないルール、決定、境界を記録し、その記録が古くなったときに知らせます。

よくある質問

LLM を呼び出したり、コードをアップロードしたりしますか？ いいえ。RepoCanon はネットワーク呼び出しを一切行いません。ドキュメントの読み書きは、お使いのエージェントが行います。

エージェントがドキュメントに秘密情報を貼り付けた場合はどうなりますか？ doctor がエラーとして報告するため（これにより doctor --ci は失敗します）、npx repocanon secrets でマスクされた状態の一覧を確認でき、プレコミットフックがコミットをブロックします。既知の誤検出は、その行に `` を付けて示してください。

誰かがエージェント向けの指示を仕込んだ場合はどうなりますか？ プルリクエスト、依存関係、ビルド手順によって、エージェントが従う AGENTS.md、.ai/、CLAUDE.md にテキストが追加される可能性があります。doctor は、不可視の Unicode 文字（双方向オーバーライド、ゼロ幅文字、タグ文字）、「以前の指示を無視する」形式の上書き、作業をユーザーに隠すルール、偽の <system> マーカー、curl … | sh がある場合に失敗し、git が追跡していない指示ファイルについて警告します。MCP による書き込みも同じテキストを拒否し、プレコミットフックもブロックします。意図したテキストには `` を付けてください。

ChatGPT で使えますか？ OpenAI Codex は AGENTS.md をネイティブに読み込みます。ブラウザー版 ChatGPT はリポジトリを参照できませんが、npx repocanon context "your task" を実行すると、貼り付けて使える情報パックが出力されます。

CLAUDE.md やほかのルールファイルは上書きされますか？ いいえ。明確な目印が付いたブロックを1つ追加または更新し、ファイルの残りの部分には手を加えません。.ai/ 内のコアドキュメントが置き換えられるのは、init --force を実行した場合だけです。

モノレポではどうなりますか？ 現時点では、moduleRoots または modules でパッケージをマッピングできます。パッケージごとのナレッジレイヤーはロードマップに記載されています。

ライブラリとして使えますか？ はい。require('repocanon') で、CLI が使用するものと同じ関数を利用できます。CONTRIBUTING を参照してください。

原則

1. ドキュメントはセマンティックインデックスであり、コードのコピーではありません。矛盾がある場合はコードを優先します。
2. 段階的に情報を開示します：AGENTS.md（ルールの要約付き）→ PROJECT → INDEX → 1つのモジュール → コード。
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
• バグやアイデア：GitHub のイシュー

スポンサー

Framimo — ブラウザー上で、あらゆるクリップを GIF、WebP、AVIF、MP4 に変換できます。アニメーションのトリミング、切り抜き、サイズ変更、圧縮に対応。ファイルはお使いのデバイス上で処理されます。

RepoCanon のスポンサーをご希望ですか？イシューを作成してください。

ライセンス

MIT © Md. A Awal Hadi