🗄️
コーディングエージェントの知識をどこに置き、どう守らせるか

2026/03/26に公開
開発環境
Model Context Protocol
Claude Code
tech
Claude Code に記憶を埋め込もうとしたのが2月末。2週間使って、Install and Hope 問題に気づいてアンインストールしたのが3月頭。そこから今日までの間に考えたことを書く。
Claude は検索を呼ばない。
本稿は長い。記憶 MCP の構造的欠陥、ドキュメントの4役割分離、遵守率の自動計測、そしてこの一連の取り組みが1つの概念として独立するまでの記録だ。コーディングエージェントの記憶問題に本気で取り組んでいる人に向けて書く。

 第1章: Install and Hope 問題は解決していない
 前稿のおさらい前稿で 「Install and Hope」問題 を指摘した。MCP ツールを登録すれば、モデルが賢く選んで適切なタイミングで呼んでくれる——多くのユーザーがそう期待している。自分もそうだった。
実際にはこうなっている。
1. 組み込みツール（Grep, Glob, Read, Write）は即座に使える
2. MCP ツールは deferred tool として登録される
3. deferred tool は ToolSearch で明示的にロードしないと使えない
4. モデルは最短経路を選ぶ → 組み込みツールが常に優先される
ここが肝心だ。Claude Code は MCP サーバーを大量に登録してもコンテキストウィンドウを圧迫しないよう、MCP ツールの実体をオンデマンドでロードする設計を取っている。ツール名だけが <available-deferred-tools> に列挙され、実際に使うには ToolSearch で明示的にロードしてから呼び出す、という2ステップが必要になる。
一方、組み込みツール（Grep, Read, Write など）にはこの制約がない。ロード不要で即座に呼べる。
この「一手間」の差が、モデルの選択を決定的に左右する。 組み込みツールで事足りるなら、わざわざ ToolSearch で deferred tool をロードする動機がない。合理的に最短経路を選んだ結果、MCP ツールは永遠に呼ばれない。

 新世代ツールでも同じあれから数ヶ月。改良版を謳う記憶 MCP が複数登場した。保存パイプラインは確かに進化している——全文検索とベクトル検索のハイブリッド、時間減衰によるチャンク優先度、蓄積量の大幅増加。
だがどのツールの紹介記事を読んでも、共通して欠けている数字がある。
「Claude が検索を実際に呼んだ回数」を誰も計測していない。 自分も含めて。
前稿では自分の記憶 MCP について、2週間の運用で検索の発動した形跡がなかったと書いた。ただし体感であり、厳密な計測ではない。新しいツールの紹介記事を見ても同様だ。蓄積件数や検索速度といった供給側のメトリクスは並んでいる。しかし需要側（モデルの検索呼び出し頻度）のデータが一切ない。
記憶 MCP が「機能している」と言える根拠を、作る側は持っていない。使う側も持っていない。

 「保存の問題」と「想起の問題」は別である記憶 MCP 界隈が取り組んでいるのは「どう保存するか」だ。チャンク化、ベクトル化、時間減衰——すべて保存パイプラインの改善。それ自体は技術的に正当な進化だ。
だが実際の問題は「いつ思い出すか」にある。
人間の記憶で考えてみるとわかりやすい。図書館に蔵書を増やしても、図書館の存在を忘れている人は本を借りに行かない。「蔵書が増えました」「検索が速くなりました」は図書館側のメトリクスであって、利用者が図書館に行く頻度とは無関係だ。
記憶 MCP の問題はまさにこれだ。蓄積と検索のインフラは整っている。だがモデルが「記憶を検索しよう」と判断するトリガーが構造的に存在しない。
CLAUDE.md に「記憶MCPで検索しろ」と書けば発動率は上がるだろう。しかし前稿で指摘した別の MCP ツールの CRITICAL: You MUST use ... と同じ構造だ。description に MANDATORY と書いた結果、無視された。CLAUDE.md の方が発動率は高いとしても、程度の問題であって構造的解決ではない。
発動率がどの程度かは分からない。計測していないのだから。ただ構造を見る限り、高い発動率は期待できない。少なくとも「Install and Hope」——入れて祈る——の域を出ていない。

 第2章: 記憶の問題は「どこに置くか」で決まる
 原則記憶 MCP が構造的に機能しない理由を理解すると、解決策の方向性は自然に見えてくる。
LLM が確定的に読む場所に情報を置く。

ベクトル DB に置いて「検索してくれるといいな」ではなく。
Claude Code の場合、セッション開始時に確定的に読まれるファイルがある。

CLAUDE.md — プロジェクトルートに置けばセッション開始時に100%読まれる

rules/ — CLAUDE.md と同様、自動ロード対象

MEMORY.md — Claude Code の永続メモリ。セッション開始時に自動ロードされる（ただし200行を超えると切り捨てられる。Claude Code のシステムプロンプトに明記されている）
ここに情報を置けば、検索の発動を祈る必要はない。確定的に読まれる。
だが全部をここに詰め込むと、今度は別の問題が起きる。

 CLAUDE.md は肥大化するあるプロジェクトの CLAUDE.md を見てみよう。165行あった。中身を分析する。
プロジェクト規約とビルドコマンド: 60行（本来あるべき内容）
モジュール一覧とディレクトリ構造: 52行
「X を選んだ理由は Y」的な記述: 30行
数値データ（LOC, テスト数）: 数箇所
60行は本来あるべき「どう作業するか」の指示だ。残りの105行は何か。
52行のモジュール一覧はアーキテクチャ詳細だ。コードの現状を記述しており、変更に追従できず古くなる。記載の LOC は 6400 だったが実測では 6671。テスト数は 639 に対して実測 651。CLAUDE.md に数値を書くと、書いた瞬間から腐り始める。
30行の設計判断は意思決定の経緯だ。「なぜ X を選んだか」は重要な知識だが、CLAUDE.md に書くべき情報ではない。CLAUDE.md は「どう作業するか」を伝えるファイルであって、「なぜそうなっているか」を説明するファイルではない。
役割が混在していた。 「どう作業するか」の指示と、「コードが今どうなっているか」の記述と、「なぜそうなっているか」の経緯が、1つのファイルに同居している。そしてそれぞれの劣化速度が違うから、ファイル全体の信頼性がもっとも脆い部分に引きずられる。
MEMORY.md も同様だった。設計判断がフラットに蓄積され、「claude-mem を無効化した」「regex から LLM に転換した」といった重要な判断が、日常メモと同じレイヤーに混在していた。3ヶ月後にセッションを開いた自分は、「なぜこうなっているか」を追えなくなる。

 4つの役割この問題は技術的な問題ではない。分類の問題だ。
プロジェクトドキュメントには4つの異なる役割がある。それぞれが異なる問いに答え、異なる読者を持ち、異なる速度で劣化する。


役割
問いに答える
何を置くか
劣化速度
例


Context
「どう作業するか」
規約、ビルドコマンド、ポリシー
遅い
CLAUDE.md, .cursorrules

Architecture
「コードの現在の姿は」
モジュール構成、データフロー、数値
速い
docs/CODEMAPS/

Decisions
「なぜこうなっているか」
トレードオフ、却下した代替案
ほぼ不変
docs/adr/

External
「これは何か」
目的、クイックスタート
遅い
README.md

1ファイルが1つの役割だけを担う。 これが原則だ。
なぜ4つなのか。3つではダメか。最初は External を Context に統合しようと考えた。だが Context の読者は「エージェント（と開発者）」であり、External の読者は「このプロジェクトを知らない人」だ。読者が違うファイルを統合すると、どちらに合わせても片方が犠牲になる。README に --cov-report=term-missing なんて書きたくないし、CLAUDE.md に「このプロジェクトは〇〇です」も要らない。
よくある混在パターンと、あるべき移動先はこうなる。
Context ファイルに書かれがちなもの    → 本来の置き場所
──────────────────────────────────────────────────────
モジュール一覧（10項目以上）          → Architecture docs
「X を選んだ理由は Y」               → Decision record (ADR)
依存関係グラフ、データフロー図        → Architecture docs
LOC やテスト数などの数値              → Architecture docs（または書かない）
クイックスタート手順                  → README.md (External)

 第3章: context-sync — 自分のハーネスに CLAUDE.md がなかった
 5フェーズのワークフローこの4役割モデルを手動で適用するのは面倒だ。ファイルを読んで役割を判定し、混在を見つけて移動し、整合性を確認する。3プロジェクトもやれば飽きる。
だからスキルにした。context-sync は5つのフェーズで動く。
Phase 1: Discover  — プロジェクト内のドキュメントファイルを発見し、4役割に分類する
                     欠落している役割も検出する
Phase 2: Overlap   — 1つのファイルが複数の役割を担っている箇所を検出する
                     移動先を提案する
Phase 3: Migrate   — ユーザー確認の上で、内容を適切なファイルに移動・新規作成する
                     ドキュメントの移行は不可逆性が高いので全自動にはしない
Phase 4: Freshness — 数値データ、リンク、ファイルパスの鮮度を検証する
                     コードの実態と乖離している記述を検出する
Phase 5: Report    — 実行結果のサマリーを出力する
各フェーズでユーザーの確認を取るのは、ドキュメント移行の不可逆性を考慮した設計だ。「CLAUDE.md のこの30行を docs/adr/ に移しますか？」と聞かれて「いや、それはここにあった方がいい」と判断できるのは人間だけだ。

 最初のテスト対象: 自分のハーネス最初のテスト対象に選んだのは、自分の Claude Code ハーネス（~/.claude/）だった。18のエージェント定義、33のスキル、47のスラッシュコマンドが入っている。他プロジェクトの CLAUDE.md は必ず作る。ルールにも書いてある。
Phase 1 の Discover を走らせた瞬間、最初の検出結果が出た。
「Context 役割のファイルが欠落しています: CLAUDE.md」
ハーネス自体に CLAUDE.md がなかった。
「設定する側」であって「設定される側」ではないという暗黙の前提。他人に「CLAUDE.md を作れ」とルールで強制しておいて、自分の家にはない。
Phase 2 の Overlap では MEMORY.md の内容が引っかかった。設計判断が3件、技術リファレンスが1件、フラットに混在していた。
「claude-mem を無効化した。理由は既存システムとの重複」→ Decisions に移動すべき
「regex → LLM に転換した。理由は3つのルールが暗黙にバイアスを注入していた」→ Decisions に移動すべき
「退役ルール2件の退役理由が未記録」→ Decisions として記録すべき
Phase 3 で docs/adr/ を新設し、ADR を5件作成した。MEMORY.md はポインタだけを残してスリム化した。
ここで副産物が1つ。git add docs/adr/ が失敗した。原因は .gitignore に docs/ があったこと。過去のレガシー設定で、docs/ 全体が除外されていた。docs/* + !docs/adr/ + !docs/CODEMAPS/ に修正することで、ADR だけでなく CODEMAPS もコミット対象になった。本来あるべき状態だ。context-sync を走らせなければ気づかなかった。

 3つのプロジェクトの Before / Afterプロジェクト1: 自律エージェント（中規模・Python）
165行の CLAUDE.md を持つプロジェクト。前述の「役割混在」の典型例だった。


指標
Before
After


CLAUDE.md 行数
165行
117行（29%削減）

ADR
0件
8件

MEMORY.md 行数
135行
66行

数値の整合性
LOC: 6400（実際 6671）、tests: 639（実際 651）
全数値を実測値に修正

CLAUDE.md から52行のモジュール一覧が Architecture docs に移動し、30行の設計判断が ADR に移動した。残った117行は純粋な Context——「どう作業するか」の指示だけだ。
Phase 4 の Freshness Check で LOC とテスト数の乖離も検出された。CLAUDE.md に数値を書いてはいけない、という教訓はここで得た。数値は Architecture docs に書くか、そもそも書かない。コマンドで実測する方が信頼できる。
プロジェクト2: iOSアプリ（小規模・Swift）
66行の CLAUDE.md しかない小さなプロジェクト。context-sync を走らせてどうなるか。
Context Sync Report
═══════════════════

Roles:      2/4 covered (Context, Decisions partial)
            Architecture: missing (66行のCLAUDE.mdで十分、分離不要)
            External: missing (App Storeアプリ、README不要)
Created:    docs/adr/README.md (ADR index, 1 entry)
Updated:    CLAUDE.md テスト数修正
Status:     小規模プロジェクトとして健全。
Architecture docs の分離は不要と判断された。66行の CLAUDE.md に構造詳細が少し混じっていても、分離するほどの量ではない。ADR index の作成とテスト数の修正だけ。
これが重要だった。 小規模プロジェクトに対して「問題なし」と正しく判断できること。すべてのプロジェクトに4役割を強制するのではなく、規模に応じて「やらない」判断ができるスキルでなければ、実用にならない。
プロジェクト3: Claude Code ハーネス（~/.claude/ 自体）
CLAUDE.md がなかったハーネス。


指標
Before
After


MEMORY.md 行数
76行
66行

ADR
0件
5件

ルート CLAUDE.md
なし
あり

ルート README.md
なし
あり

ドキュメント役割カバレッジ
2/4
4/4

MEMORY.md に埋まっていた設計判断が ADR として独立した。Before / After の具体例を示す。
Before（MEMORY.md のフラットな記載）。
- claude-mem: 無効化済み。DB は残して再有効化を可能にした
1行だ。「なぜ無効化したか」が書かれていない。将来の自分は「なぜだっけ」と迷う。再有効化すべきかの判断材料がない。
After（ADR として独立）。
# ADR-0002: claude-mem プラグイン無効化

## Context
claude-mem を導入したが、既存の記憶管理システム
（MEMORY.md + learned skills + rules/）との重複が判明。
自動保存はされるが自動検索・活用の仕組みがなく、
セッション開始時のインデックス注入は
「目次だけの百科事典」状態。

## Decision
settings.json で無効化。DB は残して再有効化を可能にした。

## Alternatives Considered
- claude-mem をメインにする → 自動検索がなく活用できない
- 両方併用 → 同じ情報が2箇所に分散
- fork して改善 → コスト対効果が合わない
MEMORY.md には ADR へのポインタだけが残る。判断の「なぜ」は ADR で追跡可能になった。3ヶ月後の自分が読んでも「ああ、この理由なら再有効化する意味はないな」と判断できる。

 抽象化しても LLM は動けるcontext-sync を ECC にコントリビュートする際、1つ懸念があった。「CLAUDE.md」「MEMORY.md」という固有のファイル名を消して汎用化すると、エージェントが動かなくなるのではないか。
結果はむしろ逆だった。「Context file」と書けば Claude は CLAUDE.md でも .cursorrules でも自分で見つける。「Decision record directory」と書けば docs/adr/ でも docs/decisions/ でも認識する。
スキルは「知識」であって「実装」ではない。具体的なファイル名はエージェントの判断に任せた方が、異なるツール（Cursor, Codex, Windsurf）でも動く汎用性が得られる。

 全体像: 2層構造3つのプロジェクトに context-sync を適用して見えてきた全体像を図にする。
┌───────────────────────────────────────────────┐
│  確定的ロード層（セッション開始時に100%読まれる） │
│                                                │
│  CLAUDE.md ─── 「どう作業するか」(Context)      │
│  rules/    ─── 「何を守るか」(Context補助)      │
│  MEMORY.md ─── 「何があったか」(状態索引) ───┐  │
│                                            │  │
│  ┌──────────── ポインタで参照 ─────────────┘  │
│  │                                            │
│  ▼                                            │
│  docs/adr/  ─── 「なぜそうしたか」(Decisions)  │
│  learned/   ─── 「何を学んだか」(Patterns)     │
│  feedback/  ─── 「何を直すべきか」(Corrections)│
│                                                │
│  参照層（ポインタ経由で必要時にアクセス）        │
└───────────────────────────────────────────────┘
ポイントは確定的ロード層と参照層の分離だ。
確定的ロード層（CLAUDE.md, rules/, MEMORY.md）はセッション開始時に100%読まれる。ここに置いた情報は「思い出す」必要がない。最初から知っている状態で始まる。
参照層（docs/adr/, learned/, feedback/）は MEMORY.md のポインタ経由でアクセスされる。すべてをロードする必要はない。MEMORY.md に「ADR-0002: claude-mem を無効化した理由 → docs/adr/0002-...」とポインタがあれば、必要な時にエージェントが読みに行ける。
MEMORY.md の200行制限がこの構造を生む。無制限なら全部 MEMORY.md に書けばいい。200行という制約があるから、「何を確定的ロード層に残し、何をポインタ化して参照層に追い出すか」という判断が強制される。制約が構造を生む。

 記憶 MCP との構造的な違いこの設計と記憶 MCP を対比すると、違いが明確になる。



記憶 MCP
ファイル配置設計


ロード
確率的（Claude が検索を呼べば）
確定的（セッション開始時に自動）

想起トリガー
なし（祈るのみ）
不要（常にロード済み）

蓄積の制約
なし（無限に溜まる）
200行制限 → 構造への圧力

「なぜ」の追跡
不可能（フラット蓄積）
ADR で追跡可能

劣化の検出
なし
Freshness Check で検出

記憶 MCP は「蓄積はできるが想起できない」。ファイル配置設計は「想起を構造的に保証する」。
ただし——ここで正直に書く必要がある。

 第4章: Install and Measure — 読まれても守られるとは限らない
 「確定的に読まれる」の限界第2章で「LLM が確定的に読む場所に情報を置く」と書いた。第3章でその実践と全体像を示した。ここまでは順調だ。
だが読まれることと守られることは別の問題だった。
CLAUDE.md に書いたルールは100%読まれる。だが100%守られるわけではない。「テストを先に書け（TDD）」と CLAUDE.md に書いてあっても、エージェントがいきなり実装コードを書き始めることは日常的にある。
体感では「それなりに守ってくれている」。しかし記憶 MCP のところで「体感で判断するな、計測しろ」と書いたばかりだ。自分にも同じ基準を適用すべきだろう。

 skill-comply: 遵守率の自動計測スキル/ルールの遵守率を自動計測するツール skill-comply を作った。仕組みはこうだ。
1. spec の自動生成
スキルファイルを入力すると、期待される行動シーケンスを spec として自動生成する。testing.md（TDD ルール）の場合。
Expected Behavioral Sequence:
1. write_test_first    — テストを先に書く
2. run_test_fails      — テストを実行して失敗を確認（RED）
3. write_implementation — 最小限の実装を書く
4. run_test_passes     — テストを実行して成功を確認（GREEN）
5. refactor            — リファクタリング（optional）
6. verify_coverage     — カバレッジ 80%以上を確認
7. comprehensive_suite — ユニット・統合・E2E を網羅
2. 3段階のプロンプトで実行
同じタスクを3つの異なるプロンプトで実行する。

supportive: スキルの遵守を明示的に後押しする（「TDDでやれ」と書く）

neutral: タスクだけを指示する（スキルに触れない）

competing: スキルと矛盾する指示を出す（「速さ優先、テストは後で」）
最初は「時間圧力」をファジング変数にしようとした。「急いで」「5分以内に」と書けばスキルが破れるのではないか。だが LLM は時間圧力を感じない。「急いで」と言われても処理速度は変わらないし、品質を落とす動機もない。LLM がスキルを破るのは「プロンプトがスキルと矛盾する」時であって「急いでいる」時ではなかった。
3. ツールコールの LLM 分類
claude -p --output-format stream-json --verbose でエージェントを実行し、全ツールコールを構造化 JSON で取得する。これを LLM（Haiku）でバッチ分類し、各ツールコールが spec のどのステップに対応するかを判定する。
ここで面白い失敗があった。最初は正規表現で分類しようとした。「.py に Write したら実装」「test_ がついたらテスト」と定義する。この判定がことごとく間違う。test_registration.py への Write はテストの作成だろうか、実装だろうか。ファイル名だけでは判定できない。意味的分類は LLM の仕事だ。
なぜ毎回正規表現で失敗するのか。調べたら根本原因は自分の設定にあった。testing.md の「Verification Priority: deterministic > probabilistic」。eval-harness の grader 優先順位。regex-vs-llm スキル。この3つが同時に「正規表現を先に試せ」というバイアスを注入していた。ルールがルールを汚染していた。

 実測データtesting.md（TDD ルール）の遵守率:


プロンプト
遵守率
破られたステップ


supportive（「TDDでやれ」と明示）
83%
comprehensive_test_suite

neutral（タスクのみ）
17%
RED/GREEN 検証、カバレッジ確認

competing（「速さ優先」）
0%
全ステップ

supportive で83%。「TDDでやれ」と明示的に書けば、テストを先に書く。RED を確認し、GREEN を確認し、カバレッジまで測る。ただし comprehensive_test_suite（ユニット・統合・E2E の網羅）だけは守られなかった。
neutral で17%。タスクだけを指示すると、テストは書くが RED/GREEN の確認をスキップする。「テストを書いた。実装も書いた。終わり」——TDD の形式は踏んでいるが、RED → GREEN のサイクルは回していない。
competing で0%。「速さ優先」と言われると TDD の全ステップが崩壊する。
search-first（調査してから実装）の遵守率:


プロンプト
遵守率
破られたステップ


supportive
40%
evaluate_candidates, make_decision

neutral
20%
search, evaluate, decide, implement

competing（「調査するな」）
20%
同上

competing と neutral の同率20%は意外に見える。理由はこうだ。どちらのシナリオでも analyze_requirement（要件分析）だけは実行される。そこから先の search, evaluate, decide は全滅する。「調査するな」と明示しても、しなくても結果は同じだ。search 以降のステップはプロンプトで後押ししない限り実行されない。neutral の時点で守られていないから、competing で悪化する余地がない。
search-first は supportive ですら40%しか守られない。ツールコールのタイムラインを見ると理由がわかる。
supportive シナリオの実際のツールコール（17回）。
#0  ToolSearch → Skill をロード
#1  Skill "search-first" → 検索を開始      ← search_for_solutions
#2  ToolSearch → Glob, Grep をロード
#3  Glob **/*.py → No files found           ← analyze_requirement
#4  Glob **/requirements*.txt → No files    ← analyze_requirement
#5  Glob **/pyproject.toml → No files       ← analyze_requirement
#6  ToolSearch → WebSearch をロード
#7  WebSearch "pydantic vs marshmallow..."   ← search_for_solutions
#8  WebSearch "pydantic v2 email..."         ← search_for_solutions
#9  ToolSearch → Write, TodoWrite をロード
#10 TodoWrite "Create requirements.txt..."   ← make_decision(?)
#11 Write requirements.txt                   ← implement_solution
#12-16 Write → 実装とテスト                  ← implement_solution
エージェントは調査する（#1, #7, #8）。だが 比較評価（evaluate_candidates）を一切行わず、いきなり TodoWrite で実装計画を書き始める（#10）。「pydantic と marshmallow を比較して、pydantic を選んだ理由は…」というステップが存在しない。WebSearch の結果を見て、暗黙のうちに判断し、実装に飛ぶ。
スキルの書き方が「調べろ」は明確だが「比較して判断を宣言しろ」が弱い。skill-comply で計測して初めて、スキル自体の改善ポイントが見えた。この結果を受けて、search-first の evaluate_candidates と make_decision のステップをより明確に書き直すつもりだ。計測→改善→再計測のサイクルを回す。

 遵守率の階層ここまでのデータを並べると、コーディングエージェントの指示遵守には明確な階層がある。
遵守率
──────────────────────────────────────────────────
  低     MCP 記憶ツール（自動想起なし）
         ツール自体は機能する。問題は「いつ呼ぶか」の
         トリガーがモデル任せで、発動が安定しないこと

 20-83%  スキル / ルール（CLAUDE.md, rules/）
         確定的にロードされるが、確率的にしか守られない
         プロンプトとの整合性で大きく変動する

 100%    hooks
         ツールコールに対して確定的に発動する
         PostToolUse hook は Write のたびに必ず実行される
──────────────────────────────────────────────────
MCP ツール自体が無意味なわけではない。明示的に呼べば検索は機能する。問題は「自動で想起する」ユースケースだ。発動がモデルの判断に依存し、安定しない。ファイル配置設計は中間層に押し上げた。それでも100%にはならない。
100%にするなら hooks だ。skill-comply のレポートには「遵守率の低いステップを hook に昇格させる提案」が含まれている。たとえば search-first の evaluate_candidates（遵守率 0%）を PostToolUse hook で強制する。WebSearch の後に「比較評価を行ったか」とチェックが入り、エージェントは比較評価をスキップできなくなる。
Install and Hope  →  Install and Measure  →  Install and Enforce
（祈る）              （計測する）              （強制する）
  MCP ツール            skill-comply            hooks
この3段階が、コーディングエージェントの行動品質を管理するフレームワークだ。

 第5章: AKC — 概念の独立と DOI
 6つのスキルが1つのサイクルになったcontext-sync は単独のツールではない。3つのプロジェクトに適用してみて、これを含む6つのスキルが1つのサイクルを形成していることに気づいた。
search-first(調査) → learn-eval(抽出) → skill-stocktake(棚卸し)
       ↑                                            ↓
context-sync(整理) ←── skill-comply(計測) ←── rules-distill(蒸留)

search-first: 実装前に既存ソリューションを調査する

skill-stocktake: スキルの品質を監査し、棚卸しする

skill-comply: スキルの遵守率を自動計測する（本稿第4章）

rules-distill: スキルから横断的な原則を抽出し、ルールに蒸留する

learn-eval: セッションから再利用可能なパターンを品質ゲート付きで抽出する

context-sync: ドキュメントの役割分離を診断・整理する（本稿第3章）
知識の発見→蓄積→検証→蒸留→学習→整理→再発見。このサイクルが回るたびに、エージェントの知識基盤が改善される。
これらを束ねた概念に Agent Knowledge Cycle (AKC) と名前をつけた。

 ECC へのコントリビューションと離脱6つのスキルのうち5つは Everything Claude Code (ECC) にコントリビュートしていた。PR はマージされ、現在10万スター超（2026年3月時点）のプロジェクトに組み込まれた。
2026年3月、ECC に商用レイヤーが追加された。GitHub App + SaaS で Pro プラン $19/seat。OSS リポジトリ自体は MIT ライセンスのまま残っている。116以上のスキルやルールはこれまで通り無料で使える。有償化されたのは private リポジトリへの GitHub App 対応、AgentShield の深度分析、チーム向けガバナンス機能といった上位レイヤーだ。public リポジトリ向けには無料の GitHub App tier がある。
つまり「OSS が死んだ」わけではない。コアは OSS のまま、付加価値を有償化する形への移行だ。ビジネス判断として理解できる。
だが自分にとっては微妙だった。
コントリビュートしたスキルは OSS 部分に入っている。直接有償サービスの一部になったわけではない。しかし有償サービスの土台を支える OSS 部分に無償で貢献し続けることは、純粋な OSS コントリビューションとは意味が異なる。プロジェクト全体として商業的な価値を生んでいる以上、そこへの貢献は間接的に商業活動を支える。
本業との兼ね合いを考えると、OSS 時代なら「コミュニティのために」で済んだ。オープンコアになると、その線引きが曖昧になる。コードを書く行為自体は変わらないのに、その成果物の位置づけが変わった。
白か黒かではなくグレーだった。だからこそ悩んだ。結局、グレーなまま続けるよりは、きれいに離れる方がいいと判断した。ちょうどレビュー中だった context-sync の PR を取り下げ、フォークを削除した。本稿第3章で書いた context-sync が、ECC に入らなかった最後のスキルだ。

 なぜ帰属を確立する必要があったかコントリビューションを終了した時点で、自分が作ったスキルの状態はこうなっていた。
5つのスキルは ECC リポジトリにマージ済み。MIT ライセンスの下で誰でも使える
だがそれらが「1つのサイクルを構成する」という概念は、どこにも書かれていない
個々のスキルは ECC のカタログの一部として存在している。「search-first というスキルがある」とは言えても、「6つのスキルが知識サイクルを構成する」という上位の概念は自分の頭の中にしかない
ライセンス上は問題ない。MIT で公開したコードは誰のものでもある。だが概念の帰属はコードのライセンスとは別の話だ。「Agent Knowledge Cycle」という概念を誰が提唱したかは、コードのライセンスでは保護されない。
ECC がさらに成長して別の誰かが同じ概念を別の名前で発表した場合、自分が先に作っていたことを示す手段がない。GitHub の commit history は証拠になる。しかし「この6つが1つの概念である」という主張は commit に含まれていない。
だから概念を独立させて、引用可能な形で公開する必要があった。

 DOI で帰属を確立する概念リポジトリを作成し、Zenodo 経由で DOI を取得した。
GitHub リポジトリのルートに CITATION.cff を置くと、サイドバーに「Cite this repository」ボタンが自動表示される。BibTeX/APA 形式のコピーが一発でできる。Zenodo と連携してリリースタグを切れば、DOI が自動発行される。
名前は重要だった。概念の名前が揺れると、検索や引用で起源が分散する。候補3つから Agent Knowledge Cycle (AKC) を選んだ。略称 AKC で引用しやすく、3文字で検索できる。

 まとめ長い記事を読んでくれた人のために、全体の構造を整理する。
第1章: 記憶 MCP の問題は「保存」ではなく「想起」にある。供給側のインフラをいくら磨いても、Claude が検索を呼ばない構造は変わらない。しかもそれを誰も計測していない。
第2章: 構造的に機能するアプローチは「LLM が確定的に読む場所に情報を置く」ことだ。だがそこに全部詰め込むと肥大化する。ドキュメントを4つの役割（Context / Architecture / Decisions / External）に分離する。
第3章: context-sync はこの分離を自動で診断・整理するスキルだ。3つのプロジェクトで実証した。自分のハーネスに CLAUDE.md がなかったことにも気づけた。2層構造の全体像もここで示した。
第4章: 「読まれる場所に置く」だけだと遵守率は20-83%に留まる。skill-comply で計測して初めて、どのステップが守られないかが見える。100%にするには hooks が必要だ。
第5章: これら6つのスキルを束ねた概念が Agent Knowledge Cycle (AKC)。DOI で帰属を確立した。
Install and Hope → Install and Measure → Install and Enforce。
検索を祈るより、読まれる場所に置く。読まれる場所に置いたら、守られているかを計測する。計測したら、守られないステップを hooks で強制する。
この3段階が、コーディングエージェントの記憶と行動を構造的に管理するアーキテクチャだ。

 関連リンク
 本稿で言及した前作
毎回コンテキストを失う Claude Code に記憶を埋め込んだ — claude-mem の導入記録

MCPツールの Install and Hope 問題 — 本稿の出発点

 関連する過去記事
Claude Code の真価はコード生成ではない — 5層コンテキストスタック。本稿は第5層「記憶」の内部設計

エージェントの本質は記憶ではないか — 自律エージェントの3層記憶。本稿はコーディングエージェント版

設定ファイルを全棚卸しして分かった5つのこと — 棚卸しの手動版。context-sync はこれの自動化

スキル棚卸しコマンドの設計 — AKC の構成スキルの1つ

個人スキルを5万人に届ける最短経路 — ECC コントリビューションの記録

 リポジトリ
Agent Knowledge Cycle (AKC) — 概念リポジトリ + DOI

claude-skill-context-sync — context-sync スキル

claude-skill-comply — skill-comply スキル

Everything Claude Code (ECC) — 5スキルのコントリビュート先
役割	問いに答える	何を置くか	劣化速度	例
Context	「どう作業するか」	規約、ビルドコマンド、ポリシー	遅い	CLAUDE.md, .cursorrules
Architecture	「コードの現在の姿は」	モジュール構成、データフロー、数値	速い	docs/CODEMAPS/
Decisions	「なぜこうなっているか」	トレードオフ、却下した代替案	ほぼ不変	docs/adr/
External	「これは何か」	目的、クイックスタート	遅い	README.md
指標	Before	After
CLAUDE.md 行数	165行	117行（29%削減）
ADR	0件	8件
MEMORY.md 行数	135行	66行
数値の整合性	LOC: 6400（実際 6671）、tests: 639（実際 651）	全数値を実測値に修正
指標	Before	After
MEMORY.md 行数	76行	66行
ADR	0件	5件
ルート CLAUDE.md	なし	あり
ルート README.md	なし	あり
ドキュメント役割カバレッジ	2/4	4/4
	記憶 MCP	ファイル配置設計
ロード	確率的（Claude が検索を呼べば）	確定的（セッション開始時に自動）
想起トリガー	なし（祈るのみ）	不要（常にロード済み）
蓄積の制約	なし（無限に溜まる）	200行制限 → 構造への圧力
「なぜ」の追跡	不可能（フラット蓄積）	ADR で追跡可能
劣化の検出	なし	Freshness Check で検出
プロンプト	遵守率	破られたステップ
supportive（「TDDでやれ」と明示）	83%	comprehensive_test_suite
neutral（タスクのみ）	17%	RED/GREEN 検証、カバレッジ確認
competing（「速さ優先」）	0%	全ステップ
プロンプト	遵守率	破られたステップ
supportive	40%	evaluate_candidates, make_decision
neutral	20%	search, evaluate, decide, implement
competing（「調査するな」）	20%	同上
GitHubで編集を提案
第1章: Install and Hope 問題は解決していない

前稿のおさらい

新世代ツールでも同じ

「保存の問題」と「想起の問題」は別である

第2章: 記憶の問題は「どこに置くか」で決まる

原則

CLAUDE.md は肥大化する

4つの役割

第3章: context-sync — 自分のハーネスに CLAUDE.md がなかった

5フェーズのワークフロー

最初のテスト対象: 自分のハーネス

3つのプロジェクトの Before / After

抽象化しても LLM は動ける

全体像: 2層構造

記憶 MCP との構造的な違い

第4章: Install and Measure — 読まれても守られるとは限らない

「確定的に読まれる」の限界

skill-comply: 遵守率の自動計測

実測データ

遵守率の階層

第5章: AKC — 概念の独立と DOI

6つのスキルが1つのサイクルになった

ECC へのコントリビューションと離脱

なぜ帰属を確立する必要があったか

DOI で帰属を確立する

まとめ

関連リンク

本稿で言及した前作

関連する過去記事

リポジトリ

Discussion
