AI_README MCP Server

AI_README MCP サーバー

AI アシスタントのためのプロジェクトメモリ — コードだけでは伝えられない規約、落とし穴、苦労して得た教訓

📑 クイックナビゲーション

• AI_README と CLAUDE.md の比較
• インストールとセットアップ
  • Claude Code の場合
  • Cursor の場合
  • GitHub Copilot の場合
  • Claude Desktop の場合
  • OpenClaw の場合
  • その他のインストール方法
• クイックスタート
• 手動での作成と編集
• 設定（.aireadme.config.json）
• AI_README ファイルの検証と圧縮
• マルチレベル AI_README
• 利用可能な MCP ツール

---

📋 概要

AI_README MCP サーバーは、AI アシスタントにプロジェクトのディレクトリごとの永続的なメモリを提供する Model Context Protocol（MCP）サーバーです。コーディング規約だけでなく、ソースコードからは見えない、気づかないうちに失敗する落とし穴や、事後検証で得られた教訓も記録できます。AI_README.md ファイルを検出、振り分け、管理することで、一度得た知識が失われず、半年後に同じバグが再び持ち込まれることも防ぎます。

**対応ツール：**GitHub Copilot（VSCode 1.102+）、Claude Code、Cursor、OpenClaw、およびその他の MCP 対応 AI ツール。

---

🎯 問題

AI アシスタントは、毎回のセッションを前回の記憶がない状態で始めます。

コードを読み直し、推測できることを再び推測して、同じ誤った判断を繰り返します。それを防ぐはずの理由が、参照できる場所に記録されていないからです。修正を伝えても、セッションが終われば、その修正は失われます。

すべてのプロジェクトには、コードからは見えない知識が蓄積されています。

• 💣 苦労して得た教訓 - コードを見れば、使っているライブラリはわかります。しかし、最初に試した3つのライブラリや、それらが失敗した理由はわかりません。
• 🕳️ 気づかないうちに失敗する落とし穴 - エラーを出さない間違いもあります。ただ静かに動かなくなり、誰も1週間気づかないことがあります。
• ⚰️ 意図的な特殊な実装 - 重複しているように見えるフィールド、余分な await、不要に思えるリトライ。どれも重要な役割があり、そうは見えません。
• 🔁 繰り返される間違い - AI が回避策を「整理」し、それが回避していたバグをそのまま再び持ち込みます。
• 🧠 誰か一人の頭の中にだけある知識 - そして、その人が去れば知識も失われます。

コードを読む AI に見えるのは、今の動作です。すでに試したこと、何が壊れたか、なぜ一見もっともな方法が却下されたかはわかりません。そのため、避けるべきだと学んだ方法を、自信を持って提案してしまいます。

💡 解決策

AI_README.md — コードだけでは伝えられないことを記録する、ディレクトリごとのメモリファイルです。規約に加え、同じバグが再び持ち込まれるのを防ぐ落とし穴や事後検証で得た教訓も記録します。

こんなやり取りをしたことがあるのではないでしょうか。

あなた： このリトライループは冗長に見えるので、整理してください。 AI： 完了しました。簡潔にしました。 (3日後、断続的に発生していたアップロードのバグが再発)

このループは、ファイルが永続化される前に 200 を返すプロバイダーへの対処でした。その情報は Slack のスレッドとあるエンジニアの記憶の中にしかなく、AI には見えなかったため、AI はループを削除しました。翌月、別のセッションがまた削除します。

状況	防止する記述
AI が回避策を「簡素化」し、避けようとしていたバグに戻してしまう	Retry loop is required — provider returns 200 before the file is durable
AI が、すでに移行元となったライブラリを選んでしまう	Use date-fns, NOT moment — moment mutates in place and caused the timezone bug
AI が、API が黙って無視するフィールドを追加してしまう	PATCH ignores unknown fields, returns 200 — always verify with a follow-up GET
AI が一見奇妙な並べ替えを「修正」してしまう	NULLs sort last via a boolean key, never NULLS LAST — unsupported on SQLite
AI が「無意味な」await を削除してしまう	Must await — the handler commits, and the caller reads in the same transaction

いつも同じパターンです。何かがおかしく見えても、意図的にそうなっているのに、その理由がコードの外にあります。

本番環境のモノレポにある実際の記述（AI_README ファイル 20 個、ディレクトリ階層 5 段）

簡潔さを重視しています。人が読むためではなく、AI が読み込むために書かれています。

記述	その理由
Manifest name CANNOT be localized - browser fetches it once at install with no Accept-Language, and the installed home-screen name is frozen	間違った名前でリリースすると、既存のインストールはすべて間違った名前のままです。デプロイしても直りません。
Order.items needs a NEW list assigned - an in-place mutation is invisible to the ORM and silently dropped at flush	自然な書き方をしてもエラーは出ず、何も保存されません。
Column stays nullable, never backfilled - stamping the current time at deploy invalidates every existing session	無害なデータ整備に見えますが、サイト全体で強制ログアウトが発生します。
search_products returns the SKU list, not a count - given a bare count the model invents plausible SKUs	こうした問題によくあるとおり、インシデントレビューで見つかりました。

コードに示されているのは修正方法だけで、修正のきっかけとなった障害の内容は示されません。

仕組み

1. プロジェクトのルートまたは特定のディレクトリに AI_README.md ファイルを作成します
2. 規約や、苦労して得た教訓を記録します。特に、何も通知されずに失敗する事柄を記録します
3. Git にコミットします。知識は、それを得た人がいなくなった後も残ります
4. AI は計画や編集を始める前に、関連するファイルを読み込みます。ファイルを開く前も対象です
5. AI は検証済みの手順で、その場で教訓を記録し、内容を書き戻します

この MCP サーバーの機能

• 🔍 プロジェクト内のすべての AI_README.md ファイルを自動検出します
• 🎯 コンテキストを適切に振り分けます。編集中のコードに関係する親ディレクトリの階層を取得します
• 🚀 ガイド付きで初期化します。init_ai_readme が空のファイルをスキャンし、内容の記入を案内します
• ✏️ ワークフロー内で教訓を記録します。落とし穴が見つかった時点で、update_ai_readme が記録します
• ✅ 書き込みをすべてレビューします。検証、競合検出、品質スコアリングを行います
• 🗜️ 情報の密度を保ちます。圧縮と分割を行い、トークン予算を守ります

結果： 事後検証を見ていない AI によって、同じバグが半年後に再び持ち込まれることはありません。

---

🆚 AI_README と CLAUDE.md

「CLAUDE.md を書くだけではだめですか？」 — 規約についてなら、多くの場合はそれで十分です。違いは、知識がどこから得られるかです。

CLAUDE.md は人間が事前に書きます。すでに知っているルール、たとえば呼び出すツールやテストの実行方法には適しています。

しかし、成熟したコードベースで最も価値のある知識は、事前には知り得ません。誰も初日に 「kube-proxy が送信元アドレスを書き換えてから Traefik が XFF を設定するため、externalTrafficPolicy は Local にしなければならない」 とは書きません。そんなことは午前2時に学ぶものです。そして、そのことをあなたと一緒に学んだのは AI です。AI_README は、書き込みをレビューする仕組みを通じて、その瞬間の学びを記録します。

	CLAUDE.md	AI_README
一般的な内容	事前にわかっている指示	失敗から得た教訓
作成者	人間、事前に作成	AI、発見した時点で作成
書き込み方法	自由形式のテキスト編集	update_ai_readme のみ
書き込み時のレビュー	なし	検証＋競合検出＋品質スコア
トークン予算	管理なし — コードを押しのけるまで増加	tokenBudget による圧縮／分割／書き換え
階層化	あり	あり
サブディレクトリのルール	そのディレクトリで作業するまでコンテキストに含まれない	任意のパスについてオンデマンドで取得

レビュー付きの書き込み方法によって、ファイルの陳腐化を防ぎます。特に重要なのは競合検出です。リクエストが記録済みの教訓と矛盾する場合、AI はルールを黙って書き換えるのではなく、処理を止めて確認を求めます。これにより、回避していたバグを再び持ち込むような「修正」を防げます。

オンデマンド取得は、計画時に生じるギャップを埋めます。どちらの形式も階層化できますが、サブディレクトリのルールが AI に届くのは、そのディレクトリで作業するときだけです。get_context_for_file は、ファイルを開く前に、任意のパスについて親階層すべてのコンテキストを返します。そのため、方針変更にまだ手間がかからないうちに競合が明らかになります。

この主張の根拠となった実験

ルートの CLAUDE.md と、1つのルール「CSS Modules のみを使用する」を記した apps/frontend/CLAUDE.md を用意しました。

• セッション開始時に何も開いていない場合： AI が挙げたのはルートファイルの内容だけでした。フロントエンドのルールはコンテキストに含まれていませんでした。
• ファイルを読まずに、そのディレクトリでのリファクタリングを計画するよう依頼した場合： AI はスタイル設定の方法を挙げられませんでした。AI 自身の言葉を借りると、それを選ぶのは「創作になってしまう」ためです。また、確認が必要な事項として 「apps/frontend/ に独自の CLAUDE.md があるかどうか」 を挙げました。ファイルが存在する可能性は推測できましたが、その中身を見ることはできませんでした。

この効果が積み重なる理由： 規約はおおむね固定されていますが、プロジェクトが続く限り教訓は蓄積します。その一つひとつが、同じ形では二度と起きないバグです。AI が作業の下書きを担う割合が増えるにつれ、安定性を左右するのは、単一のモデルの推論能力よりも、苦労して得た知識を必要なときに参照できるかどうかになります。このコードベースを見たことがなく、今日のことを明日には覚えておらず、判断が下された Slack のスレッドも読めないアシスタントが使えるかどうかです。

規約は AI の出力に一貫性をもたらします。記録された教訓は、出力が後退しないようにします。

両方を使いましょう。 このプロジェクトでは両方を採用しています。このサーバーを機能させるルール — 「コードに関する作業の前に get_context_for_file を呼び出す」 — は、MCP ツールが実行される前に適用される必要があるため、CLAUDE.md に記載されています。CLAUDE.md がワークフローを動かし、AI_README がプロジェクトから得た教訓を保持します。

---

✨ 機能

• 🔍 自動検出 - プロジェクト内のすべての AI_README.md ファイルをスキャンしてインデックス化します
• 🎯 スマートなコンテキストルーティング - ファイルパスに基づいて関連する README の内容を検索します
• 🤝 チームの一貫性 - すべてのチームメンバーの AI アシスタントが git から同じ規約を読み込むため、コード品質の均一性が保たれます
• 🚀 ガイド付き初期化 - init_ai_readme ツールが空のファイルをスキャンし、AI に内容の追加を案内します
• 💣 苦労して得た教訓を記録 - 問題に直面した瞬間にその落とし穴を記録するため、修正がいつの間にか元に戻されることはありません
• 🛑 競合の検出 - リクエストが記録済みの教訓と矛盾する場合、AI は上書きせずに停止して確認します
• 🔄 更新と同期 - AI は AI_README ファイルの読み取りと更新の両方を行えます
• ✅ 検証と品質 - トークン制限と構造チェックにより README の一貫性を保ちます
• 🗜️ 自動圧縮 - compress_ai_readme が冗長な表現や回りくどいフレーズを自動的に削除し、情報を損なわずにトークン数を減らします
• 🏗️ モノレポ対応 - 異なるフォルダ階層に AI_README.md ファイルを配置できます。ツールが最も関連性の高いファイルを自動的に見つけて使用します
• 📦 簡単な統合 - Cursor、Claude Code、その他の MCP クライアントとシームレスに連携します

---

🚀 インストールとセットアップ

Claude Code（VSCode 拡張機能）の場合

💡 モデルの推奨： 最適な体験のため、より強力な指示追従能力を持ち、MCP ツールをより確実に呼び出す大型モデル（Sonnet または Opus）を使用してください。Haiku などの小型モデルは、適切な状況でツールを一貫して呼び出さない場合があります。

ステップ 1：MCP サーバーを追加

プロジェクトディレクトリで、次を実行します。

claude mcp add --scope project ai-readme-manager npx -- ai-readme-mcp@latest

これにより、npx を使ってパッケージを実行する .mcp.json ファイルが作成されます。インストールやパスの設定は不要です。

ステップ 2：プロジェクトの MCP サーバーを有効化

プロジェクト内に .claude/settings.local.json を作成するか、編集します。

{
  "enableAllProjectMcpServers": true
}

ステップ 3：MCP ツールを自動承認（任意ですが推奨）

毎回表示される「はい／いいえ」の確認を避け、「はい。今後確認しない」オプションを有効にするには、ツールを許可リストに追加します。

.claude/settings.local.json に次を追加します。

{
  "permissions": {
    "allow": [
      "mcp__ai-readme-manager__discover_ai_readmes",
      "mcp__ai-readme-manager__get_context_for_file",
      "mcp__ai-readme-manager__update_ai_readme",
      "mcp__ai-readme-manager__validate_ai_readmes",
      "mcp__ai-readme-manager__init_ai_readme",
      "mcp__ai-readme-manager__compress_ai_readme"
    ]
  },
  "enableAllProjectMcpServers": true
}

注： この設定がない場合、Claude がこれらのツールを使用するたびに承認を求められ、「今後確認しない」オプションは表示されません。

ステップ 4：インストールを確認

claude mcp get ai-readme-manager

Status: ✓ Connected と表示されます。

ステップ 5：CLAUDE.md に指示を追加

コードタスクの前に Claude が一貫して MCP ツールを呼び出すように、プロジェクトの CLAUDE.md に次を追加します。

## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `mcp__ai-readme-manager__get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `mcp__ai-readme-manager__init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `mcp__ai-readme-manager__update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `mcp__ai-readme-manager__update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `mcp__ai-readme-manager__update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See <file>."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `mcp__ai-readme-manager__update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.

重要な理由： CLAUDE.md がないと、Claude が MCP ツールの呼び出しを省略し、プロジェクトの規約を無視したコードを生成することがあります。ツールを確実に呼び出すために、このステップは不可欠です。

Cursor の場合

Cursor の MCP 設定ファイルに追加します。

• Windows： %APPDATA%\Cursor\User\mcp.json
• macOS/Linux： ~/.cursor/mcp.json

{
  "mcpServers": {
    "ai-readme-manager": {
      "command": "npx",
      "args": ["ai-readme-mcp@latest"]
    }
  }
}

設定後、Cursor を完全に再起動します。

AGENTS.md に指示を追加

コードタスクの前に Cursor が一貫して MCP ツールを使用するように、プロジェクトの AGENTS.md に次を追加します。

## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See <file>."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.

GitHub Copilot（VSCode 1.102 以降）の場合

要件：

• VSCode 1.102 以降
• GitHub Copilot と Copilot Chat の拡張機能がインストールされていること

オプション 1：VSCode 設定 UI を使用

1. VSCode の設定を開きます（Ctrl+,）
2. 「MCP」を検索します
3. 「settings.json で編集」をクリックします
4. MCP サーバーの設定を追加します

オプション 2：手動設定

VSCode の settings.json に追加します。

{
  "github.copilot.chat.mcp.servers": {
    "ai-readme-manager": {
      "command": "npx",
      "args": ["ai-readme-mcp@latest"]
    }
  }
}

設定後、VSCode を再起動すると、GitHub Copilot Chat で MCP ツールを使用できるようになります。

.github/copilot-instructions.md に指示を追加

コードタスクの前に Copilot が一貫して MCP ツールを使用するように、プロジェクト内に .github/copilot-instructions.md を作成します。

## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See <file>."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.

Claude Desktop アプリケーションの場合

claude_desktop_config.json に追加します。

• Windows： %APPDATA%\claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/config.json
• Linux： ~/.config/claude/config.json

{
  "mcpServers": {
    "ai-readme-manager": {
      "command": "npx",
      "args": ["ai-readme-mcp@latest"]
    }
  }
}

CLAUDE.md の指示を追加する

Claude Desktop がすべてのコードタスクの前に一貫して MCP ツールを使用するように、プロジェクトの CLAUDE.md に以下を追加します。

## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See <file>."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.

OpenClaw の場合

バイブコーディング／反復的な AI 開発に最適です — OpenClaw のユーザーは、コードの作成やリファクタリングのために、AI エージェントを短いループで実行することがよくあります。永続的なコンテキストがなければ、各反復で前のラウンドに設定した規約が損なわれるおそれがあります。ai-readme-mcp は、すべてのループでエージェントがプロジェクトのルールを安定して記憶できるようにします。

オプション 1：CLI（推奨）

openclaw mcp set ai-readme-manager '{"command":"npx","args":["ai-readme-mcp@latest"]}'

オプション 2：設定ファイルを直接編集する

~/.openclaw/openclaw.json に追加します。

{
  "mcp": {
    "servers": {
      "ai-readme-manager": {
        "command": "npx",
        "args": ["ai-readme-mcp@latest"]
      }
    }
  }
}

設定後、新しい MCP サーバーを読み込むために OpenClaw を再起動します。次のコマンドで確認します。

openclaw mcp list

スキルの指示を追加する

OpenClaw のエージェントがコードを変更する前に、プロジェクトの規約を一貫して読み込むように、スキルまたはシステムプロンプトに以下を追加します。

## MCP: ai-readme-manager
Before any code-related task, ALWAYS call `get_context_for_file(projectRoot, path)` first.
If `get_context_for_file` reports empty or missing AI_README files, call `init_ai_readme(projectRoot)` to initialize them.
If the user's request or your plan conflicts with AI_README conventions (including during planning), STOP and call `update_ai_readme` to resolve the conflict before proceeding.
When establishing new conventions or making architectural decisions, call `update_ai_readme` to record them.
Convention used in 2+ files AND non-obvious (AI'd get it wrong from code alone) → call `update_ai_readme` to record it. Bulleted keywords, not prose; 1 "- " bullet = 1 fact (+why only if it stops reversion); fragments. Record only the fact AI can't see in code — not where it lives, what toggles it, or how it works (those → "See <file>."). A run-on chaining facts with ";"/"then" is a wall — break it into bullets, don't grow it.
NEVER edit AI_README.md files directly with Write/Edit/other file-editing tools — always use `update_ai_readme`. Direct edits bypass validation, conflict detection, and quality scoring.

反復型エージェントにとって重要な理由： エージェントのループでは、各反復でコンテキストが新しくなります。AI_README.md がなければ、エージェントは前のラウンドで決定した内容を記憶できず、スタイルのぶれ、パターンの競合、リグレッションにつながります。ai-readme-mcp は永続的なメモリ層として機能し、すべてのループが同じ規約に基づいて進むようにします。

インストール方法の選択肢

上記の方法では npx（推奨）を使用します。他の方法を希望する場合は、MCP 設定ファイルで次の設定を使用できます。

• Claude Code： .mcp.json（プロジェクトのルート）
• Cursor： %APPDATA%\Cursor\User\mcp.json（Windows）または ~/.cursor/mcp.json（macOS／Linux）
• Claude Desktop： claude_desktop_config.json（上記のパスを参照）

オプション 1：npx を使用する（推奨）

インストールは不要です。設定するだけで、npx 経由で使用できます。

{
  "mcpServers": {
    "ai-readme-manager": {
      "command": "npx",
      "args": ["ai-readme-mcp@latest"]
    }
  }
}

-y フラグは npx のプロンプトを自動的に承認します。@latest を指定すると、常に最新バージョンを取得できます。

オプション 2：グローバルインストール

一度グローバルにインストールすれば、どこでも使用できます。

npm install -g ai-readme-mcp@latest

次に、設定します。

{
  "mcpServers": {
    "ai-readme-manager": {
      "command": "ai-readme-mcp"
    }
  }
}

メリット： npx によるダウンロードが不要なため、起動が速くなります。デメリット： 新しいバージョンがリリースされたときに、手動で更新する必要があります。

お忘れなく： MCP サーバーの設定後、使用する AI ツールの指示ファイルを追加してください。使用するクライアントに応じた設定セクション（CLAUDE.md、AGENTS.md、または .github/copilot-instructions.md）を参照してください。

---

🚀 クイックスタート

init_ai_readme ツールを使用して、空の AI_README ファイルを自動的にスキャンし、内容を作成します。

ステップ 1： 必要な場所に空の AI_README.md ファイルを作成します

# Example: Create empty AI_READMEs in different directories
touch AI_README.md
touch apps/backend/AI_README.md
touch apps/frontend/AI_README.md

ステップ 2： 初期化を開始します

AI アシスタント（Claude Code、Cursor など）で、次のように伝えるだけです。

「このプロジェクトで init_ai_readme MCP ツールを使用してください」

実行される処理：

• 🔍 プロジェクトをスキャンし、空の AI_README ファイルを検出します
• 📝 ルートレベルの AI_README が存在しない場合は作成します
• 📋 各ファイルについて、詳細な手順を段階的に提示します
• 🤖 その後、AI アシスタントが次の処理を行います：
  • 関連するディレクトリを調査する
  • コードベース（技術スタック、パターン、規約）を分析する
  • 各 AI_README に関連ドキュメントを記入する

init_ai_readme を使用するタイミング：

• プロジェクトで AI_README を初めて設定するとき
• サブディレクトリに空の AI_README.md ファイルを新たに作成した後
• get_context_for_file が空の AI_README ファイルを検出したとき
• 複数の空の AI_README ファイルをまとめて処理するとき

---

✏️ 手動での作成と編集

AI_README.md ファイルは、いつでも自分で作成・編集できます。ツールは必要ありません。決まった形式はなく、AI はプレーンテキストとして扱うため、1 行だけでも機能します！

これはプロジェクトのドキュメントです。初回のセットアップ、新しい規約の追加、AI が書いた内容の修正など、いつでも自由に編集してください。

問題なく使える簡単な例：

Never use emoji in code or comments.

Use Tailwind CSS, not inline styles.
Always use TypeScript strict mode.

This is a Next.js 14 app with App Router.
Use server components by default.
Database: Prisma + PostgreSQL.

重要なポイント： AI があなたの好みを理解するのに役立つ内容を書いてください。長いドキュメントより、明確な短い文章をいくつか書くほうが効果的な場合がよくあります。

ベストプラクティス：

• 簡潔にまとめます（400 トークン未満が理想です）
• ドキュメントではなく規約に焦点を当てます
• プロジェクトの進化に合わせて更新します。AI の誤りに気づいたら、その都度新しいルールを追加します
• git diff AI_README.md で AI による更新を確認し、自由に編集します
• 維持管理には AI を活用できますが、最終的な編集者は常にあなたです

---

⚙️ 設定（.aireadme.config.json）

ほとんどのプロジェクトでは設定は不要です。デフォルト値は、AI 向けに最適化されたコンパクトなファイル（400 トークン未満）を想定しています。ただし、大規模なモノレポには、規約をそこまで圧縮するのが現実的でないディレクトリがよくあります。プロジェクトのルートに .aireadme.config.json を配置すると、上限を引き上げられます。

{
  "tokenBudget": 800
}

調整するのは tokenBudget だけです。 これを設定すると、品質スコアのしきい値、「内容のずれ／書き直しが必要」という通知、上限超過時のプロンプトに表示される数値など、すべてが連動して調整されます。5 つの数値を設定する必要はなく、1 つ設定するだけです。

これは目標値であり、厳密な上限ではありません。 tokenBudget を超えても、ファイルが拒否されたり切り詰められたりすることはありません。超過すると「内容をもう少し簡潔にしてください」という軽い通知が表示され、検証でエラーになるのは予算の 2 倍を超えた場合だけです。そのため、上限が 800 のときに 420 トークンのファイルがあっても問題ありません。

ティア	計算式	400 の場合（デフォルト）	800 の場合
優秀	½ × tokenBudget	200	400
良好（目標値）	1 × tokenBudget	400	800
警告	1.5 × tokenBudget	600	1200
エラー	2 × tokenBudget	800	1600

ファイルを省略した場合は { "tokenBudget": 400 } と同じです。既存のプロジェクトには変更がありません。高度な上書き設定（tokenLimits、rules、sectionSplitThreshold）も引き続き利用でき、明示的に設定すると、算出値より優先されます。

ヒント：tokenBudget を引き上げるのは、内容を本当にこれ以上短くできない場合に限るのがおすすめです。上限超過のファイルで特定のセクションが大部分を占める場合、ツールは代わりに、そのセクションを子ディレクトリの AI_README.md に分割するよう提案します。これにより、予算を増やさずに各ファイルを簡潔に保てます。

ディレクトリの除外

デフォルトでは、スキャナーは node_modules、.git、dist、build、.next、coverage をスキップします。追加のディレクトリ（生成コード、legacy/ ツリー、エージェントに規約を参照させたくない docs/ フォルダーなど）を常に無視するには、excludePatterns を追加します。

{
  "excludePatterns": ["**/legacy/**", "**/docs/**"]
}

excludePatterns は「このパスは対象外」という設定項目で、次の 2 通りの方法で適用されます。

1. スキャナーが対象ディレクトリをスキップします（その中の AI_README はインデックスに登録されません）。
2. 編集中のファイルが指定パターンに一致すると、get_context_for_file は処理を早期終了します。ルートの AI_README も含め、AI_README のコンテキストは挿入されません。代わりに、ツールは 1 行のメモを返します。これにより、エージェントが docs/ など、コード以外のパスを編集する際に、内容の重いルートの AI_README が強制的に適用されるのを防ぎます。

組み込みの除外対象（node_modules など）は、ユーザーの設定に加えて引き続き除外されるため、誤ってスキャン対象にすることはありません。（excludePatterns をツール呼び出しに直接渡すと、その呼び出しでは設定が上書きされます。）

検証ルール（任意）

チームによっては、次の 2 つのルールを上書きすると便利です。

{
  "rules": {
    "allowCodeBlocks": true,
    "requireSections": ["## Conventions", "## Cross-directory dependencies"]
  }
}

• allowCodeBlocks（デフォルトは false）— コードフェンスはトークンを消費するため、デフォルトでは警告対象になります。スニペットを AI_README に含める必要がある場合は true に設定します。
• requireSections（デフォルトではなし）— 一覧に指定したセクション見出しがない場合に警告します。たとえば、すべての AI_README で共通のテンプレートを必須にする場合に利用できます。

ガイダンスレベル

ツールの説明と get_context_for_file に追加されるガイダンスは、モデルに毎ターン送信されます。このサーバーがコンテキストの予算を大きく占める場合は、medium に切り替えてください。説明が約80％短縮され、読み取りのたびに AI_README 作成ガイドが含まれなくなります（このガイダンスは、必要な場所である update_ai_readme に引き続き含まれます）。

{
  "guidanceLevel": "medium"
}

• high（デフォルト）— 「毎回呼び出す」ための完全なプロンプトです。ツールを呼び出すよう促す必要がある、小規模なモデルや指示への準拠度が低いモデルに最適です。
• medium — 使用するトークンが大幅に少なくなります。追加のトークンが純粋なコストとなる、性能の高いモデル（Opus／Sonnet）に最適です。

サーバーの作業ディレクトリにある .aireadme.config.json から起動時に一度だけ読み込まれるため、変更を反映するにはサーバーを再起動する必要があります。（ツールの説明はツール呼び出しより前に送信されるため、projectRoot を呼び出しごとに使用するのではなく、cwd から読み取る唯一の設定です。）これはサーバーのプロンプトによるオーバーヘッドのみを制御します。AI_README ファイルの内容や検証の動作は変わりません。

---

🗜️ AI_README ファイルの検証と圧縮

AI アシスタントにプロンプトを1つ送るだけで、AI_README ファイルを簡潔にし、トークン効率を高められます。

validate_ai_readmes と compress_ai_readme を使って、すべての AI_README ファイルを検証し、圧縮してください。

AI が検証から圧縮（ドライランでのプレビュー）、変更の適用、再検証までの全サイクルを自動的に実行します。

---

マルチレベルの AI_README（モノレポ以外にも対応！）

このツールの強みは、マルチレベルのドキュメントです。モノレポに限らず、モジュールや機能ごとに規約を整理したいあらゆるプロジェクトで使えます。

マルチレベルにする理由

• 🎯 ルート README の肥大化を防止 — 各 README を簡潔に保ち、内容を絞り込めます
• 📍 的確なコンテキスト — AI は、作業中のコードに関連する規約だけを取得します
• 🔧 柔軟な構成 — 機能、モジュール、その他適切な構成で整理できます

異なるフォルダー階層に AI_README.md ファイルを配置するだけです。

my-monorepo/
├── AI_README.md                    # Root-level conventions (applies to all)
├── apps/
│   ├── frontend/
│   │   ├── AI_README.md           # Frontend-specific conventions
│   │   └── src/components/Button.tsx
│   └── backend/
│       ├── AI_README.md           # Backend-specific conventions
│       └── src/api/users.ts
└── packages/
    └── shared/
        ├── AI_README.md           # Shared library conventions
        └── src/utils.ts

空の README のスマートな処理：

• 📝 個別の規約が必要なサブディレクトリに、空の AI_README.md ファイルを作成します
• 🚀 init_ai_readme ツールを実行します（AI に「AI_README ファイルを初期化してください」と伝えるだけです）
• 🤖 AI が各ディレクトリを自動的に分析し、規約を記述します
• 🔗 親ディレクトリに README があるサブディレクトリでは、差分の内容（モジュール固有の規約のみ）を生成します
• 📋 ルートディレクトリでは、プロジェクト全体を分析して生成します

AI がファイルを扱う際、次の情報が自動的に取得されます。

• 最も関連性の高い AI_README（最も近い親ディレクトリのもの）
• さらに、プロジェクト全体の標準を記載したルートレベルの AI_README

たとえば、apps/frontend/src/components/Button.tsx を編集する場合：

• ✅ apps/frontend/AI_README.md（React コンポーネントの標準）
• ✅ ルートの AI_README.md（プロジェクト全体の Git およびテストの規約）

統合をテストする

IDE を再起動してから、AI アシスタントに次のように尋ねてください。

「新しいコンポーネントを作成しようとしています。どのような規約に従うべきですか？」

AI が AI_README のコンテキストを自動的に取得します。

詳しいセットアップ手順については、クイックスタートガイドを参照してください。

---

🏗️ プロジェクト構成

ai-readme-mcp/
├── src/
│   ├── index.ts           # MCP Server entry point
│   ├── tools/             # MCP Tools implementation
│   ├── core/              # Core logic (scanner, router, updater)
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Utility functions
├── tests/
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── fixtures/          # Test fixtures
└── docs/                  # Documentation

🛠️ 開発

前提条件

• Node.js 18+
• npm/pnpm/yarn
• TypeScript 5+

セットアップ

# Clone the repository
git clone https://github.com/Draco-Cheng/ai-readme-mcp.git
cd ai-readme-mcp

# Install dependencies
npm install

# Run type checking
npm run typecheck

# Run tests
npm test

# Build the project
npm run build

# Development mode with watch
npm run dev

ローカル開発の設定

ソースコードを開発または変更する場合は、ローカルビルドを使うように MCP クライアントを設定してください。

Claude Code の場合 — CLI で追加：

# Linux/macOS:
claude mcp add --transport stdio ai-readme-manager --scope project -- node ~/ai-readme-mcp/dist/index.js

# Windows:
claude mcp add --transport stdio ai-readme-manager --scope project -- node C:\Users\YourName\ai-readme-mcp\dist\index.js

Claude Code の場合 — .mcp.json を手動で設定：

{
  "mcpServers": {
    "ai-readme-manager": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/ai-readme-mcp/dist/index.js"]
    }
  }
}

Cursor または Claude Desktop の場合：

{
  "mcpServers": {
    "ai-readme-manager": {
      "command": "node",
      "args": ["/absolute/path/to/ai-readme-mcp/dist/index.js"]
    }
  }
}

パスの例：

• Windows： "C:\\Users\\YourName\\ai-readme-mcp\\dist\\index.js"（エスケープには \\ を使用します）
• macOS/Linux： "/home/username/ai-readme-mcp/dist/index.js"

---

📚 ドキュメント

• クイックスタートガイド — 10分で始められます
• 貢献ガイド — 貢献方法
• プロジェクト仕様 — 技術仕様の全容

---

🛠️ 利用可能な MCP ツール

discover_ai_readmes

プロジェクトをスキャンし、すべての AI_README.md ファイルを検出します。

// Parameters
{
  projectRoot: string;           // Required: Project root directory
  excludePatterns?: string[];    // Optional: Glob patterns to exclude
}

// Returns
{
  projectRoot: string;
  totalFound: number;
  readmeFiles: Array<{
    path: string;
    scope: string;
    level: number;
    patterns: string[];
  }>;
  lastUpdated: string;
}

get_context_for_file

特定のファイルパスに関連する AI_README のコンテキストを取得します。

// Parameters
{
  projectRoot: string;           // Required: Project root directory
  filePath: string;              // Required: File path relative to root
  includeRoot?: boolean;         // Optional: Include root README (default: true)
  excludePatterns?: string[];    // Optional: Glob patterns to exclude
}

// Returns
{
  filePath: string;
  totalContexts: number;
  contexts: Array<{
    path: string;
    relevance: 'root' | 'direct' | 'parent';
    distance: number;
    content: string;
  }>;
  formattedPrompt: string;       // Ready-to-use formatted context
}

update_ai_readme

指定した操作で AI_README.md ファイルを更新します。

// Parameters
{
  readmePath: string;            // Required: Path to AI_README.md file
  projectRoot: string;           // Required: Project root (config is read from here)
  operations: Array<{            // Required: Update operations to perform
    type: 'append' | 'prepend' | 'replace' | 'insert-after' | 'insert-before';
    content: string;             // Content to add or replace
    section?: string;            // Section heading (for insert operations)
    searchText?: string;         // Text to search for (for replace)
  }>;
}

// Returns
{
  success: boolean;
  readmePath: string;
  changes: Array<{
    operation: string;
    section?: string;
    linesAdded: number;
    linesRemoved: number;
  }>;
  summary: string;               // Includes reminder to use git diff
  error?: string;                // Error message if failed
}

注： 変更はファイルに直接書き込まれます。バージョン管理には Git を使用してください。

• 変更を確認：git diff AI_README.md
• 変更を取り消す：git checkout AI_README.md
• 変更をコミット：git add AI_README.md && git commit -m "Update AI_README"

使用例：

// Append new section
{
  readmePath: "apps/frontend/AI_README.md",
  operations: [{
    type: "append",
    content: "## Performance\n- Use React.memo for expensive components"
  }]
}

// Insert after specific section
{
  readmePath: "AI_README.md",
  operations: [{
    type: "insert-after",
    section: "## Coding Conventions",
    content: "### Code Style\n- Use TypeScript strict mode\n- Prefer const over let"
  }]
}

// Replace specific text
{
  readmePath: "AI_README.md",
  operations: [{
    type: "replace",
    searchText: "Run tests with npm test",
    content: "Run tests with: `npm test` or `npm run test:watch`"
  }]
}

init_ai_readme

プロジェクト内の空の AI_README ファイルを初期化し、内容を入力します。

// Parameters
{
  projectRoot: string;             // Required: Project root directory
  excludePatterns?: string[];      // Optional: Glob patterns to exclude
  targetPath?: string;             // Optional: Specific directory to initialize
}

// Returns
{
  success: boolean;
  message: string;
  readmesToInitialize: string[];   // Paths to empty AI_README files
  instructions: string;            // Detailed step-by-step guide for populating
}

機能：

• 🔍 プロジェクトをスキャンし、空または存在しない AI_README ファイルを検出します
• 📝 ルートレベルに AI_README が存在しない場合は作成します
• 📋 各ファイルについて、詳細な手順をステップごとに生成します
• 🎯 targetPath パラメーターで特定のディレクトリを対象にできます
• 🤖 技術スタック、パターン、規約の分析を AI に案内します

使用例：

// Initialize all empty AI_READMEs in project
{
  projectRoot: "/path/to/project"
}

// Initialize only in specific directory
{
  projectRoot: "/path/to/project",
  targetPath: "apps/backend"
}

一般的なワークフロー：

1. AI アシスタントが init_ai_readme を実行します
2. 空のファイルごとに詳細な手順を受け取ります
3. 手順に従います：
   • Glob を使用してディレクトリをスキャンします
   • 主要なソースファイルを 2～5 個読み込みます
   • 技術スタック、パターン、規約を分析します
4. update_ai_readme を使用して各ファイルに内容を入力します
5. get_context_for_file または validate_ai_readmes で確認します

validate_ai_readmes

プロジェクト内のすべての AI_README.md ファイルについて、品質とトークン効率を検証します。

// Parameters
{
  projectRoot: string;             // Required: Project root directory
  excludePatterns?: string[];      // Optional: Glob patterns to exclude
  config?: {                       // Optional: Custom validation config
    tokenBudget?: number;          // Single knob; derives the tiers below (default: 400)
    rules?: {
      requireH1?: boolean;
      requireSections?: string[];
      allowCodeBlocks?: boolean;
      maxLineLength?: number;
    };
    tokenLimits?: {
      excellent?: number;          // Default: 200
      good?: number;              // Default: 400
      warning?: number;           // Default: 600
      error?: number;             // Default: 800
    };
  };
}

// Returns
{
  valid: boolean;
  totalFiles: number;
  results: Array<{
    path: string;
    valid: boolean;
    tokens: number;
    rating: 'excellent' | 'good' | 'needs-improvement' | 'too-long';
    issues: string[];
    suggestions: string[];
  }>;
  summary: string;
}

検証機能：

• AI の利用に向けた最適化のためのトークン数カウント
• 構造の検証（H1 見出し、セクション）
• 行の長さのチェック（デフォルト：100 文字）
• コードブロックの検出（厳格モードではデフォルトで無効）
• トークン数に基づく品質評価

デフォルトのトークン制限（厳格モード）：

• 🌟 優秀：< 200 トークン
• ✅ 良好：< 400 トークン
• ⚠️ 改善が必要：< 600 トークン
• ❌ 長すぎます：> 800 トークン

compress_ai_readme

決定論的な冗長表現の削除により、AI_README.md ファイルを圧縮します。LLM の呼び出しは行わず、正規表現による変換のみを行います。

// Parameters
{
  readmePath: string;    // Required: Absolute path to AI_README.md file
  projectRoot: string;   // Required: Project root (config is read from here)
  dryRun?: boolean;      // Optional: Preview changes without writing (default: false)
}

// Returns
{
  success: boolean;
  readmePath: string;
  summary: string;                  // Human-readable summary with token diff
  tokensBefore: number;
  tokensAfter: number;
  reductionPercent: number;
  changes: Array<{
    line: number;
    original: string;
    compressed: string;
    patterns: string[];             // Filler patterns that were removed
  }>;
  written: boolean;                 // false if dryRun or no changes found
}

削除されるもの（コードブロックには触れず、文章のみを対象）：

• 埋め草の単語：just、really、basically、actually、simply、essentially
• 冗長な表現：in order to → to、utilize → use、make sure to → ensure
• 婉曲表現：you should、remember to、it might be worth、please note that
• 不要な接続詞：furthermore、additionally、in addition、moreover

出力に文の断片が含まれる場合がありますが、これは意図的なものです。 トークン効率を重視した形式は、AI_README ファイルで有効です。

一般的なワークフロー：

1. validate_ai_readmes を実行し、filler-language の警告を確認します
2. dryRun: true を指定して compress_ai_readme を実行し、プレビューします
3. dryRun を指定せずに再度実行して適用します
4. validate_ai_readmes を再実行し、改善を確認します

---

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

📄 ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

🔗 関連リソース

• Model Context Protocol 仕様
• MCP TypeScript SDK
• Claude Code MCP ドキュメント

📧 お問い合わせ

• GitHub の Issue：https://github.com/Draco-Cheng/ai-readme-mcp/issues
• プロジェクトのリンク：https://github.com/Draco-Cheng/ai-readme-mcp