icm-architect

ICM Architect

フォルダー構造そのものがオーケストレーションを担うワークスペースを構築します。適切なタイミングで適切なファイルを読み込む単一のエージェントが、マルチエージェントフレームワークに取って代わります。番号付きフォルダーが順序を示し、階層がコンテキストの範囲を定め、プレーンな Markdown ファイルが状態を保持します。状態は単なるファイルなので、誰でも任意のフォルダーを開いてシステムの状態を確認できます。ルーティングファイルがカタログです。小さく安定したファイルで、コンテンツが置かれた棚を指し示します。

手法：Interpretable Context Methodology（Van Clief & McDermott、arXiv:2603.16021、MIT ライセンス）。ファイルを読み込めるエージェントやモデルなら、どれでも実行できます。ワークスペース内のものが、特定のベンダーのツールに依存することはありません。

不変条件

すべての ICM は、この 10 項目から始めます。これらはデフォルトです。何が有効かを把握したうえで、細かな変更が必要な場合は、意図的に項目を破り、その理由を最も近い CONTEXT.md または AGENTS.md に記述してください。

1. 1 つのフォルダーに 1 つの役割（Unix、Parnas）。各フォルダーは単一のステップを実行するか、単一の種類のものを格納し、自身の目的を内部のファイルに記述します。構造そのものがドキュメントです。
2. 小さく安定したエントリーファイル。 ルートの AGENTS.md には、「ここはどこか、すべてのものはどこにあるか、タスク X の場合はどこへ進むか」だけを記述します。約 60 行未満に収め、ルーティングのみを担い、コンテンツは格納しません。別のファイル名を探すツールには、そのファイルへの 1 行の案内を記述し、二重に内容を持たせません（references/core.md の Naming を参照）。
3. 番号で順序を示す。 順序が重要な場合は 01_、02_、…を使います。
4. 作業用フォルダーには必ず契約を置く。 CONTEXT.md に、読み込むもの（入力）、実行すること（プロセス）、書き出すもの（出力）、確認方法を記述します。assets/templates/stage-CONTEXT.md を参照してください。
5. ファクトリーとプロダクト（継続的デリバリー）。参照資料（ルール、文体、スキーマ、テンプレート：実行ごとに変わらないもの）は、作業成果物（出力、下書き：実行ごとに新しく作られるもの）とは分けて配置します。モデルへの要求が異なるためです。参照資料は制約を与え、入力は処理対象となります。ファクトリーは一度設定し、プロダクトは実行のたびに生成されるものです。
6. すべてのステップはチェックで終える（Horvitz、Shneiderman）。各出力は、人が開いて編集し、保存できるプレーンファイルにします。ステージの ## Check に記載されたチェックに合格するまで、先へ進みません。チェックは人、スクリプト、または小規模なモデルが行います。人以外がチェックする場合は、出力の隣に check.md を作成し、1 行目に pass または fail: <why> と記述します。失敗した場合、実行はそこで止まります。ここで止めることが重要です。誤った方向への進行をこの段階で検出すれば、その影響が後続に広がりません。
7. ステップに必要なものだけを読み込む。 ステップでは、契約、参照資料、入力だけを読み込み、ワークスペース全体は読み込みません。約 8,000 トークン未満に収めます。圧縮するのではなく、読み込みを防ぎます。
8. プレーンテキスト、リンク可能、クエリ可能（Kernighan、Pike）。Markdown と YAML frontmatter を使います。リンクでグラフを作り、frontmatter のラベルでクエリできるようにします。各事実の格納場所は 1 か所にします。コピーよりリンクを優先します。リンクと入力パスは相対パスにし、解決可能でなければなりません。wikilink は、明示的に指定された Obsidian vault 内でのみ使用します。最初の見出しには、ファイル名とその役割を記述します。これにより、grep -rm1 '^# ' . で任意のツリーを一覧表示できます。
9. 状態はディスク上に置く。 存在するものを状態として扱うか、そのファイルが説明する内容と同じファイル内に状態を 1 行で記述します。生成されるインデックス（_index.md、ファイルマップ）はスクリプトで再生成し、手作業で編集しません。
10. コピーしてインスタンス化する。 新しい作業単位は、白紙のページではなくテンプレートのコピーです。テンプレートは _templates/ に、スクリプトは _tools/ に置きます。

モードを選択する

• Build：説明されたプロセス、アイデア、または問題から構築します。
• Restructure：ICM の構造が必要な既存のフォルダー、リポジトリ、または vault を再構成します。

独自のパイプラインを備えた形式もあります（System map、ソースから作成する Knowledge bundle）。どのステップを置き換えるかは、それぞれの参照資料に記載されています。

3 つのプリミティブ

すべての ICM は、次の 3 つから構成されます。

• シーケンス：番号付きのフォルダーです。各ステップの output/ が次のステップの入力になります。
• シェルフ：同じ形式のファイルをまとめたフォルダーです。各ファイルは 1 つのテンプレートからコピーされます。
• カタログ：下位を指し示し、コンテンツを保存しない小さなファイルです。AGENTS.md、CONTEXT.md、生成されたインデックスやグラフなどが該当します。

以下の形式は、これらを組み合わせたレシピです。自由に入れ子にしてください。各階層には、下位にリンクしてそこで止まる独自の小さなカタログを置きます。アンブレラとは、複数のパイプラインをまとめる 1 つのカタログで、共有シェルフをルートに置きます。どの形式にも当てはまらない場合は、3 つのプリミティブから構築し、エントリーファイルにレシピの名前を記載します。

構築モード

1. 対話から構造を抽出します。 構造はすでに、作業についての相手の説明に表れています。相手の構造を引き出し、押し付けないでください。質問は数問ずつ行います。

• 繰り返される作業単位は何ですか？（エピソード、クライアント、レポート、人物、チームなど）
• 1 回の作業を、開始から完了まで順に説明してください。続行する前に、どこで作業を止めて確認しますか？
• 毎回変わらないもの（文体、ルール、ブランド、スキーマ）と、毎回新しくなるものは何ですか？
• 「完了」とはどのような状態ですか？作業スペースからどの成果物が出ていきますか？
• ほかに誰がこの作業に関わりますか？その人たちは、あなたに尋ねずに何を見つけられる必要がありますか？

相手が立ち止まる箇所は、工程の境界になります。「Y の前に必ず X を確認する」はチェックになります。「常に Z のような文体にする／Z に従う」は、ファクトリーの参照資料になります。

2. 形式を選びます。 references/forms.md を読み、次から選んでください。

形式	構成	適した用途
パイプライン	シーケンス	同じ手順を繰り返し、毎回成果物を作る場合
レコードライブラリー	各レコードにステータス行を持つシェルフ	蓄積されていくレコードが作業単位の場合（人物、クライアント、セッションなど）
ナレッジバンドル	リンクされたノートのシェルフ。多くの場合、ソースからシーケンスで作成されます	誰かの思考法や、成果物の構築元となるアイデアなど、ナレッジ自体が成果物の場合
コンテキストマップ	チーム、プロセス、データのシェルフ。consumes: / produces: で相互にリンクします	対象が組織の場合
システムマップ	名詞と動詞のシェルフに、インパクトインデックスを加えたもの。ゲート付きのシーケンスで作成します	後からエージェントが編集するツリーの場合

3. 作業を支える最小限の構造を用意します。 assets/templates/ からひな形をコピーし、必要なスクリプトを scripts/ から _tools/ にコピーします。まだ存在しない工程のフォルダー、空の「misc」バケット、先を見越した階層は作らないでください。想像上の 7 つの工程より、実際にある 3 つの工程のほうが優れています。作業全体が保存済みのプロンプト 1 つで済むなら、その旨を伝え、作業スペースは構築しないでください。

4. 契約を記述します。 ルートの AGENTS.md（アイデンティティとルーティングテーブル。assets/templates/entry.md を使用）、所有者が使う各エージェント向けの 1 行ポインター（別の名前を読み取るもの。実行中のエージェントも必ず含めます。references/core.md の「Naming」を参照）、ルートの CONTEXT.md（パイプラインまたはスキーマ）、各作業フォルダーの CONTEXT.md、ファクトリーのユーザーごとの設定が必要な場合は setup/questionnaire.md を用意します。入力は、バッククォートで囲んだ正確なパスとして指定し、作業用（今回の実行）と参照用（毎回）に分けます。

5. ウォークテストで検証します（以下を参照）。

再構成モード

1. 触れる前に棚卸しします。 ツリーを一覧にします。各領域について、その役割、最後に変更された時期、何が参照しているかを記録します。この段階では削除も移動もしません。

2. 隠れた形式を見つけます。 オーナーに尋ねる（または推測して確認する）ことで、ここで繰り返されている単位は何か、作業はどこから入り、どこへ出るのかを明らかにします。混乱の中には、骨組みなしで成長した実際のパイプライン、ライブラリ、マップが隠れていることがよくあります。それを抽出し、置き換えてはいけません。

3. すべてのファイルを5つの役割に分類します。

• カタログ：識別と振り分けを担います（AGENTS.md やインデックスファイルになり、またはそれらに情報を提供します。既存の CLAUDE.md、GEMINI.md などは、ステップ6でその内容を AGENTS.md または棚に移した後、1行のポインターになります）
• 契約：各ステップの仕組みを記します（CONTEXT.md になります）
• ファクトリー：安定した参照情報です（_shared/ に置きます）
• プロダクト：実行ごとの成果物です（ステージの output/ または記録フォルダーに置きます）
• 不要：古くなった、重複している、または置き換えられたものです（_archive/ を提案し、削除はしません）。また、ステップ4で依存関係がないと確認できた場合に限ります

4. 移動を提案する前に、各ファイルを参照しているものを探します。 使われていないように見えることは、使われていない証拠にはなりません。ワークスペース内のリンク、兄弟ディレクトリの ../ パス、シンボリックリンク、外部の利用元（他のリポジトリ、設定、スケジュールされたジョブ、パスをハードコードしたエージェント設定）を確認します。ツリー内には外部の利用元が記載されていないため、オーナーに尋ねます。有効な参照元があるファイルはそのままにするか、すべての参照元を同じ変更で更新する場合に限り移動します。

5. 移動する前に提案します。 移行先のツリーと移行マップ（旧パス、新パス、役割、確認できた参照元）を提示します。ステップ4の調査結果に基づいて承認を得ます。確認を重ねる手法の一環として、この手順を守ってください。

6. 移行します：コピーし、検証してから削除します。 まず、ワークスペースが追跡されているか、バックアップ済みであることを確認します。コピーや名前変更の前に、移行先に大文字・小文字を区別しない場合の同名ファイルがすでに存在しないか確認します。Windows と macOS では、ファイル名を CONTEXT.md に変更すると、既存の context.md が警告なく上書きされることがあり、ファイル一覧にはこの衝突が表示されません。見つかったものはすべて承認の段階で明らかにします。新しい場所にコピーし、完全性（ファイル数とコンテンツのハッシュ。ZIP 形式のオフィスファイルは展開後の内容を比較）を検証してから元のファイルを削除し、参照されていた場所にはリンクを残します。エントリーファイルと契約を作成し、事実ごとに置き場所を1つにまとめます。構造を再利用する場合は、空のテンプレートを、この構造を適用した実体とは別に保管します。

7. ウォークテストで検証します。

ウォークテスト

何の予備知識もないエージェントとして、初見でたどります。

• ルートを開きます。エントリーファイルと追加で最大2つのファイルを読むだけで、「ここはどこか」「現在のタスクのためにどこへ行けばよいか」が分かりますか？
• 任意の作業フォルダーを選びます。その契約には、正確な入力パス、作業内容、出力、確認方法が記されていますか？
• check.md の判定を含め、ディスク上に存在するものだけからステータスを説明できますか？
• 振り分けファイルに内容が記載されていますか？ 棚に移し、ポインターを残します。
• 同じ事実が2か所に保存されていますか？ 置き場所を1つ選び、もう一方からリンクします。
• python -I _tools/links.py は通りますか（または、Python がない場合、たどるリンクはすべて解決されますか）？ 再構成後、このスクリプトによって、ツリー内のすべてのリンクと契約の入力が引き続き解決されることを確認できます。ツリー外の利用元は、ステップ4で記録したオーナーの一覧を参照します。
• 契約1つとその入力を合わせて、およそ8,000トークン以内に収まっていますか？
• 不変条件が破られている場合、その箇所で理由が説明されていますか？

続いて、その形式に固有の確認を、参照先に記載された方法で実行します。ステップが失敗した場合は、説明を増やすのではなく、ウォークテストに合格するまでファイルを移動または分割して構造を修正します。

ガードレール

• 構造を増やしすぎないでください。 段階は、チャット、保存したプロンプトまたはスキル、フォルダーと1つのエージェントの順に進みます。下の段階が実際に自動化され、繰り返し使われている場合にのみ、次の段階へ進んでください。2回行っただけの作業のためのワークスペースは、アーキテクチャではなく足場です。
• 使いながら成熟させてください。 コードを使う手順では、ワークスペースのルートから実行するコマンドを明記します。例：3. `python _tools/count_rows.py stages/03_tally/output/rows.csv` を実行します。コマンド自体が手順です。ステージには examples/ を置き、気に入った実行結果から、実際の入力を1つと良好な出力を1つ保存して、Inputs に記載してもかまいません。運用中のICMでは、誰も編集しないステージを統合し、失敗したことのないチェックをスクリプト化し、増え続けるコントラクトを分割してください。
• ICMが不得手な領域を把握してください。 リアルタイムのマルチエージェント連携、高い並行性を持つマルチユーザー向けのサービス提供、自動化されたパイプライン途中での分岐には、実際にフレームワークのコードが必要です。ICMは、知識労働の大半を含む、逐次的で、チェック済みの、反復可能な作業向けですが、すべての作業に適しているわけではありません。

参考資料

• references/core.md：5層のコンテキスト階層、コントラクトの形式、命名、ライブラリのルールを説明します。コントラクトを書くとき、または構造上の判断に異論があるときに参照してください。
• references/forms.md：5つの形式を詳しく説明します。ひな形、移行方法、失敗パターンを扱います。Build または Restructure のステップ2で参照してください。
• references/system-map.md：System map の監査パイプラインを説明します。この形式を選んだときに参照してください。
• references/bundle-from-sources.md：引用をすべて検証しながら、文字起こし、インタビュー、または調査資料から Knowledge bundle を作成する方法を説明します。このバリエーションを選んだときに参照してください。
• assets/templates/：コピーして使えるひな形です。どの形式でも使えるもの：entry.md（ルートに AGENTS.md としてコピー）、CONTEXT.md、stage-CONTEXT.md、questionnaire.md。Context map 用：context-map-node.md、context-map-schema.md。System map 用：object.md、process.md。Bundle from sources 用：concept.md、source.md、plan.md、claim.md、bundle-schema.md、keep-out.txt。
• scripts/：任意で使える標準ライブラリのみの Python スクリプトです。ワークスペースの _tools/ にコピーします。links.py はリンクと入力パスが解決できることを確認します（--graph を指定するとグラフも書き出します）。viz.py は1つ以上のグラフを viz.html として描画します。index.py はノートから _index.md を書き出します。quotes.py は引用を出典と照合し、keep-out のフレーズが含まれないことを確認します。