prelude

Prelude

AI エージェントのためのプロジェクトメモリとコードマップ：どこを見ればよいか、コードがそのような形になっている理由、変更がどこに影響するかを示します。

grep を使えば、ある単語がどこに現れるかは見つけられます。しかし、コードがそのような形になっている理由、あるファイルをどのテストがカバーしているか、そのファイルに依存するほかのファイルがいくつあるか、前回のセッションで何を学んだかはわかりません。こうした情報はソースにはありません。

Prelude はその情報をリポジトリ内に保持します。プロジェクトを一度スキャンし、スタック、アーキテクチャ、制約、決定事項、各モジュールとそのエクスポート、インポート関係を示すコードマップを、少数の JSON ファイルとして .context/ に書き込みます。それらのファイルをコミットし、エージェントは作業しながら情報を追加します。それ以降のセッションはすべて、MCP サーバー、生成された CLAUDE.md / AGENTS.md、または標準出力を通じて、それらの情報を基に開始できます。

埋め込みも、ホストするサーバーも、ネットワーク呼び出しもありません。TypeScript/JavaScript、Python、Go、Rust に対する正規表現ベースのヒューリスティックを使用します。

クイックスタート

cd your-project
npx prelude-context init        # writes .context/

またはインストールすると、この README の以降で使用する prelude コマンドが利用できるようになります。

npm install -g prelude-context
prelude init

次に、タスクを表すフレーズを渡します。

prelude locate preserve manual edits during update --limit 2

1. src/core/merger.ts  ·  src/core (Core business logic)  ·  score 32
   exports: MergeResult, MergeChange, ContextMerger, trackMapFields
   why: decision: Manual edits are sacred, content preserve×25, manual×31, edit×9, update×6, matches all terms
   impact: imported by 4 files  ·  tests: tests/map-merge.test.ts, tests/mcp-server.test.ts, tests/merge-preserve.test.ts
   decisions: Manual edits are sacred
2. src/core/state-manager.ts  ·  src/core (Core business logic)  ·  score 26
   exports: StateManager
   why: decision: Manual edits are sacred, content manual×9, edit×4, update×6, matches all terms
   impact: imported by 7 files  ·  tests: tests/map-merge.test.ts, tests/mcp-server.test.ts, tests/merge-preserve.test.ts
   decisions: Manual edits are sacred

1 回の呼び出しで、読むべきファイル、それぞれが選ばれた理由、それらに依存するもの、その後実行すべきテスト、変更を制約する記録済みの決定事項が返されます。これはこのリポジトリからの実際の出力であり、リポジトリ自身の .context/ がコミットされています。Prelude が書き込む内容を確認するには、こちらを参照してください。

Node.js >= 20.19 が必要です。

利用できる情報

your-project/
└── .context/
    ├── project.json        what the project is
    ├── stack.json          language, runtime, frameworks, tooling
    ├── architecture.json   type, patterns, directories, entry points, routes
    ├── constraints.json    rules and preferences
    ├── decisions.json      architecture decisions and their rationale
    ├── map.json            modules, exports, import graph, hub files
    ├── changelog.md        project timeline
    └── .prelude/           state: which fields were inferred, which you edited

.context/ をコミットしてください。.context/*.session.json は Gitignore に追加してください。

prelude compact は、全体を各セクション 1 行にまとめて出力します。このリポジトリでは、システムプロンプト向けに数百トークン程度のサイズになります。

[project] prelude-context | The open standard for expressing and maintaining machine-readable context about a codebase
[stack] TypeScript/JavaScript Node.js >=20.19.0 | pnpm | testing: Vitest
[arch] type=cli | patterns: Utility modules | entry: bin/prelude.ts | dirs: bin (Executable entry points), src/commands (Command handlers), src/core (Core business logic), src/mcp (MCP server), ...
[decisions] Manual edits are sacred (accepted); Regex heuristics, not AST parsers (accepted); Schemas are the contract (accepted); ...
[map] hubs: src/utils/fs.ts(25), src/runtime/context.ts(20), src/schema/index.ts(18), ... | src/core (Core business logic): state-manager.ts, infer.ts, map-scanner.ts +15 | ...

grep ではエージェントにわからないこと

質問	Prelude が答えを取得する場所
このコードがこのような形になっているのはなぜですか？	decisions.json：あなた、または prelude_record_decision を使うエージェントが記録した決定事項とその根拠
このファイルに依存するものは何ですか？	map.json：解決済みのインポートグラフ、インポーター数、ハブファイル
このファイルをカバーするテストはどれですか？	map.json：このファイルをインポートするテストファイル
前回のセッションでは、このモジュールについて何を学びましたか？	モジュールメモ。prelude annotate または prelude_annotate_module で記録され、上書きされることはありません
ここでしてはいけないことは何ですか？	constraints.json
このリポジトリは、あのリポジトリとどのように連携していますか？	project.json の relatedProjects。ワークスペースモードでは、リポジトリ間で提供されます

prelude locate は、返すすべてのファイルに最初の 4 項目を付与します。初期化したばかりのプロジェクトでは、決定事項とメモは空ですが、インポートグラフとテストは最初の実行から利用できます。残りの情報は、人やエージェントが記録するにつれて蓄積されます。

locate はどの程度ファイルを見つけられますか？

bench/locate-bench.ts はリポジトリの Git 履歴を再生します。各コミットの件名をクエリとし、そのコミットで変更されたファイルを答えとして、親コミットの状態でリポジトリをチェックアウトするため、変更そのものが検索結果に影響することはありません。ベースラインは、同じファイル群から各クエリの語句を grep し、一致した異なる語句の数で順位付けする方法です。上位 8 件に正解ファイルが含まれるクエリの割合：

リポジトリ	ソースファイル	順位付けした grep	prelude locate
cobra (Go)	37	95%	96%
flask (Python)	82	83%	86%
hono (TypeScript)	361	88%	97%
ripgrep (Rust)	100	64%	79%
typer (Python)	629	76%	74%
express (JavaScript)	147	87%	90%
平均		82%	87%

最上位の結果が正解である割合は 48% で、grep の 39% を上回ります。各リポジトリ最大 100 コミットを対象にしています。スコアの重み付けはこの 6 つのリポジトリを使って決めたため、数値は学習データ内での結果として捉えてください。実際に確認するには、自分のリポジトリでスクリプトを実行してください（CONTRIBUTING.md を参照）。ここでのベースラインはファイル検索であり、主眼ではありません。重要なのは上の表です。

CLAUDE.md や AGENTS.md を書けばよいのでは？

そのまま使ってください。Prelude は両方を生成でき（prelude export --format claude-md、--format agents-md）、すでにあるファイルをもとに初期化することもできます（prelude init --from-claude-md）。違いは、その下にある仕組みです。

• 気付かないうちに古くなりません。 手書きのコンテキストファイルは、書いた時点では正確です。prelude diff --check は、コミット済みのコンテキストがコードと一致しなくなると終了コード 1 を返すため、CI でずれを検出できます。
• 構造化されています。 公開されたスキーマを持つ JSON なので、Markdown ファイル全体を読み込まずに、ツールから特定のセクション、ディレクトリ、モジュールを照会できます。
• 「どこにあるか」と「ほかに何があるか」に答えます。 prelude locate はタスクのフレーズを、各ファイルが選ばれた理由、それをカバーするテスト、適用される決定事項とともに、短いファイル一覧へ変換します。散文形式のファイルではこれはできません。
• 編集内容が保持されます。 Prelude は推論したフィールドと、ユーザーが記述したフィールドを追跡します。prelude update は前者を更新し、後者には一切手を加えません。
• プロジェクトをまたいで使えます。 複数のリポジトリを一度登録すれば、単一の MCP サーバーが、それらの関係も含めてすべてに対応します。
• 特定のツールに縛られません。 同じファイルを Claude Code、Cursor、Codex、Claude Desktop、または JSON を読み取るあらゆるツールで利用できます。

ほかのアプローチとの関係

• セッション内のリポジトリマップ（たとえば Aider のもの）は、セッション開始時に計算され、終了時に破棄されます。Prelude のマップはファイルなので、プルリクエストで差分を確認でき、手作業で修正でき、チーム全体で共有できます。
• ホスト型のコード検索・インデックスサービスは、より強力な検索機能を備えていますが、サービスを運用するか、料金を支払う必要があります。Prelude は静的ファイルとローカル CLI で動作します。
• 埋め込みベースの検索では、Prelude の語句照合では見つからない意味的な一致を検索できます。Prelude の結果は決定的で、理由も明確に示され、生成に費用はかかりません。

エージェントから使う（MCP）

Prelude は stdio 経由で MCP サーバーとして動作します。

1つのプロジェクト

.context/ ディレクトリがあるプロジェクトから、Claude Code にサーバーを登録します。

claude mcp add prelude-context -- npx -y prelude-context serve

ほかのクライアントでは、サーバーコマンドは npx -y prelude-context serve --root /path/to/project です。

{
  "mcpServers": {
    "prelude-context": {
      "command": "npx",
      "args": ["-y", "prelude-context", "serve", "--root", "/path/to/project"]
    }
  }
}

prelude mcp-config --client claude-code | cursor | codex | claude-desktop を実行すると、お使いの環境とクライアントに応じた正確な設定スニペットが表示されます。読み取りツールには読み取り専用の注釈が付いているため、ツールの注釈に対応するクライアントでは、確認を求めずに実行できます。

ツール	エージェントが得られる情報
prelude_compact	トークン予算に合わせた概要（デフォルトで約800トークン）。[map] 行も含まれます
prelude_locate	タスクの語句に最も関連するファイル。それぞれについて、理由、インポーター数、関連するテスト、適用される決定事項、メモも表示されます
prelude_map	ハブとモジュール、1つのモジュールの詳細、または1つのファイルのエクスポートとインポーター
prelude_query	トピック、ディレクトリの範囲、またはタイプで絞り込んだコンテキスト
prelude_record_decision	決定事項を decisions.json に追記し、後続のセッションに引き継ぎます
prelude_annotate_module	map.json のモジュールの目的を修正するか、メモを追加します。更新によって上書きされることはありません
prelude_status	存在するコンテキストファイル

リソース：prelude://context/full、prelude://context/compact、prelude://context/map、および単一ファイル用の prelude://context/{type}。

マシン上のすべてのプロジェクト

各コードベースを一度登録し、エージェントのハーネスに Prelude を一度登録すれば、すべてのセッションからすべてのプロジェクトを確認できます。各プロジェクトの概要、相互の関係、プロジェクト内で確認すべき場所がわかります。

# once per repo
cd ~/code/backend  && prelude init && prelude workspace add .
cd ~/code/frontend && prelude init && prelude workspace add .

# once per machine
prelude mcp-config --workspace --client claude-code
# prints:  claude mcp add --scope user prelude -- prelude serve --workspace

ワークスペースモードでは、各ツールで project を省略可能です。また、3つのツールが追加されます。

エージェントの呼び出し	返される情報
prelude_projects	プロジェクトごとのブロック：目的、スタック、エントリーポイント、API サーフェス、ハブファイル、関連プロジェクト
prelude_locate(query="billing checkout")	project を省略すると、すべてのプロジェクトを検索します
prelude_link_projects(from="frontend", to="backend", relation="consumes", contract="REST /api/v1, JWT bearer")	関係を frontend の project.json に記録します
prelude_workspace_refresh	ワークスペースのインデックスを再構築します

prelude workspace list | index | status | remove <name> で、~/.prelude/ のレジストリを管理します（PRELUDE_HOME で上書きできます）。

CI での整合性を保つ

GitHub Action には2つのモードがあります。Guard（check: "true"）は prelude diff --check を実行し、コミット済みの .context/ とコードに差分がある場合、ジョブを失敗させます。Update（デフォルト）は prelude update を実行し、.context/ に変更があればプルリクエストを作成します。両方を使い、プルリクエストでは Guard を、main では Update を実行してください。

# .github/workflows/prelude.yml
name: Prelude Context
on:
  pull_request:
  push:
    branches: [main]
    paths: [package.json, pyproject.toml, Cargo.toml, go.mod, "src/**"]

jobs:
  check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: adjective-rob/prelude@v1
        with:
          check: "true"

  update:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
      - uses: adjective-rob/prelude@v1

入力（version、args、working-directory、check）については、action.yml を参照してください。

コマンド

コマンド	説明
prelude init	プロジェクトを分析し、.context/ に書き込みます
prelude update	再分析してマージし、手動編集を保持します
prelude diff	書き込みを行わずに、update による変更内容を表示します
prelude history	最近の更新で変更された内容を表示します
prelude hook install	ドリフトがあると失敗する git のプリコミットフックを追加します
prelude locate <query>	タスクに関連するファイルをランク付けし、それぞれのテスト、インポーター、決定事項を表示します
prelude compact	プロンプトインジェクション用に、セクションごとに簡潔な1行を表示します
prelude query	トピック、ディレクトリ、または種類でコンテキストを絞り込みます
prelude export	Markdown、JSON、CLAUDE.md、AGENTS.md、または .cursorrules にエクスポートします
prelude annotate <module>	マップ内のモジュールの目的やメモを設定します
prelude decision <title>	アーキテクチャ上の決定事項を記録します
prelude validate	.context/ ファイルを JSON Schema に照らして検証します
prelude workspace <action>	マルチプロジェクトのレジストリを管理します
prelude serve	MCP サーバーを実行します
prelude mcp-config	クライアント用の MCP 設定を表示します
prelude watch	ファイルの変更を監視し、作業セッションを記録します
prelude share	プレビューを表示してから、コンテキストをクリップボードにコピーします

各コマンドに --help を付けると、使用できるフラグを確認できます。

prelude init

prelude init
prelude init --from-claude-md              # seed from ./CLAUDE.md
prelude init --from-claude-md docs/AI.md   # or another file

--from-claude-md を指定すると、Prelude は Markdown からプロジェクト情報、スタック、アーキテクチャ、制約を抽出し、推論した内容とマージします。

prelude update と prelude diff

prelude update              # smart merge; backs up the previous state first
prelude update --dry-run    # preview
prelude update --force      # overwrite everything except decisions and changelog

prelude diff                # drift, grouped by file
prelude diff --all          # also show preserved manual edits
prelude diff --format json  # { changed, count, changes }
prelude diff --check        # exit 1 on drift

prelude history             # what each recent update changed, newest first
prelude hook install        # pre-commit hook that runs diff --check
prelude hook uninstall

update は、直近10回の実行前の状態を .context/.prelude/history/ に保存し、history はそれらのバックアップを読み込みます。hook install はリポジトリのプリコミットフックにマーカー付きのブロックを追加します。既存のフックがある場合はシバンの後に、husky を使用している場合は .husky/pre-commit に追加します。また、prelude がインストールされていないマシンではチェックをスキップします。

prelude locate <query...>

すべてのファイルを、2種類の根拠に基づいてスコア付けします。1つはマップに記録された情報（エクスポート、パス、モジュールの目的、アーキテクチャ上の役割、そのファイルに言及する決定事項）、もう1つはクエリ語を使ったファイル内容のスキャンです。出現頻度の低い語ほど高い重みが付けられます。各結果には、選ばれた理由に続いて impact 行（そのファイルをインポートするファイル数、および対象のテスト）、そのファイルに言及する記録済みの decisions、モジュールの notes があればそれらが表示されます。--format json を指定すると、同じフィールドが返されます。

prelude locate billing checkout webhook
prelude locate mcp server tools --limit 3
prelude locate "query engine" --scope src/core --format json

フラグ	説明
--limit <n>	返すファイルの最大数（デフォルトは8）
--scope <dir>	このディレクトリ以下のファイルのみを対象にします
--tests	テストファイルを含めます（デフォルトでは、クエリにテストへの言及がある場合のみ）
--format <text|json>	出力形式（デフォルトは text）

一致するものがない場合、Prelude は開始地点としてハブファイルを表示します。

prelude query <topic> [options]

prelude query "error handling"              # topic search across everything
prelude query --scope src/api/              # architecture + constraints for a directory
prelude query --type constraints            # just constraints
prelude query "prisma" --type decisions --format json
prelude query --type stack --max-tokens 500 # budget-capped output

フラグ	説明
<topic>	すべてのコンテキストファイルを対象に検索するキーワード
--scope <path>	ディレクトリに関連するアーキテクチャと制約
--type <type>	project、stack、architecture、constraints、decisions、map のいずれか
--format <md|json>	出力形式（デフォルトは md）
--max-tokens <n>	トークン予算に収まるよう出力を切り詰めます

出力は stdout に、トークン数の推定値は stderr に送られるため、パイプでつないで使用できます。topic、scope、type のいずれかを指定する必要があります。

prelude export

prelude export                      # markdown, copied to the clipboard
prelude export --format claude-md   # CLAUDE.md
prelude export --format agents-md   # AGENTS.md
prelude export --format cursorrules # .cursorrules
prelude export --format json        # structured JSON

claude-md および agents-md 形式には、ハブファイルの 最初に読むファイル リストと、モジュールごとに1行でまとめたマップが含まれます。

prelude annotate <module>

prelude annotate src/core --purpose "Inference, merge, query and export engine"
prelude annotate src/core --notes "Regex heuristics only, no AST"
prelude annotate src/core --clear-notes

prelude decision <title>

prelude decision "Use Drizzle ORM instead of Prisma"   # opens your editor for the rationale

すべての .context/ ファイルを対応する JSON Schema に照らして検証し、1つでも失敗すると終了コード1で終了します。

prelude workspace <action>

prelude workspace add . --alias backend   # register (requires .context/)
prelude workspace list
prelude workspace index                   # rebuild ~/.prelude/index.json
prelude workspace status
prelude workspace remove backend

フォーマット

Prelude は CLI であり、フォーマットでもあります。フォーマットは spec.md で規定されており、各ファイルに対応する JSON Schema は schemas/ にあります。スキーマは npm パッケージに同梱されており、追加のプロパティが許可されているため、独自のフィールドを追加できます。

コードマップ：map.json

各モジュールの簡単な目的、各ファイルのエクスポート、解決済みの内部インポートグラフ、そしてコードベースの大部分が依存する ハブ ファイルを記録します。決定的な出力（配列はソート済みで、タイムスタンプなし）のため、Git で差分を確認しやすくなっています。

{
  "stats": { "files": 47, "modules": 10, "edges": 116, "unresolvedImports": 0 },
  "modules": [
    {
      "path": "src/core",
      "purpose": "Core business logic",
      "fileCount": 12,
      "files": [{ "file": "src/core/merger.ts", "lang": "ts", "lines": 349, "exports": ["ContextMerger"] }],
      "dependsOn": ["src/schema", "src/utils"],
      "tests": ["tests/merge-preserve.test.ts"]
    }
  ],
  "hubs": [{ "file": "src/utils/fs.ts", "importedBy": 18, "rank": 1 }]
}

手動編集

.context/ ファイルはプレーンな JSON です。直接編集できます。

{
  "$schema": "https://adjective.us/prelude/schemas/v1/constraints.schema.json",
  "version": "1.0.0",
  "mustUse": ["TypeScript strict mode", "Server Components by default"],
  "preferences": [
    {
      "category": "state-management",
      "preference": "Prefer URL state over client state",
      "rationale": "Improves sharability and reduces bugs"
    }
  ]
}

prelude update は記述した内容を保持し、推論した内容だけを更新します。

外部コンテキストディレクトリ

PRELUDE_ROOT を設定すると、.context/ をコミットできない、またはコミットしたくないリポジトリで、プロジェクト外のディレクトリにあるコンテキストを読み書きできます。

言語サポート

	スタックとアーキテクチャの推論	コードマップ（エクスポート、インポート、ハブ）
TypeScript / JavaScript	✅ package.json、モノレポ、tsconfig	✅ tsconfig の paths を含む
Python	✅ pyproject.toml、requirements.txt	✅
Rust	✅ Cargo.toml	✅
Go	✅ go.mod	✅

フォーマット自体は言語に依存しません。スキャナーへの言語追加は局所的な変更で対応できます。詳しくはCONTRIBUTING.mdをご覧ください。

FAQ

.gitignore は尊重されますか？ はい。ルートの .gitignore が対象です。無視対象のファイルやディレクトリは、マップにもアーキテクチャにも含まれません。ネストされた .gitignore ファイルは、まだ読み込まれません。

.context/ をコミットすべきですか？ はい。これは機械可読な形式で記述されたプロジェクトドキュメントです。Git では .context/*.session.json のみを無視してください。

prelude update はどのくらいの頻度で実行すべきですか？ 依存関係を追加した後や、構成を変更した後に実行してください。GitHub Action が自動で実行し、ガードモードが実行し忘れたことを知らせます。

推論が間違っていた場合はどうすればよいですか？ 間違うこともあります。これはヒューリスティックによるものです。JSON を編集するか、prelude annotate を使ってください。修正内容は以降の更新でも保持されます。Prelude がこの誤りを起こすべきでない場合は、イシューを作成してください。

コードがどこかに送信されますか？ いいえ。推論、locate、MCP サーバーはネットワークリクエストを行いません。

どの LLM でも使えますか？ はい。出力はテキストと JSON です。

ロードマップ

• locate のグラフ重み付けランキング
• エージェントがタスクを完了するために必要なトークン数とツール呼び出し回数を、Prelude の有無で比較するエンドツーエンドのベンチマーク
• コードマップでの対応言語の追加
• エージェントの利用状況から学習するヒューリスティック

リリース済みの機能は変更履歴をご覧ください。未対応の項目はイシューで管理しています。

コントリビュート

コントリビュートを歓迎します。特に、実際のプロジェクト構成に対応する推論の修正、新しいフレームワーク検出機能、コードマップへの言語追加を歓迎します。CONTRIBUTING.mdには、セットアップ、規約、それぞれの手順を段階ごとに説明したガイドがあります。good first issueラベル付きのイシューは、取り組みやすい規模に設定されています。

ライセンス

MIT © Adjective。LICENSEをご覧ください。