context-map

Context Map

現在のプロジェクトの圧縮コンテキストマップを生成します。 このマップは、AI アシスタントが通常、高コストな Read／Grep 呼び出しで調べる 構造に関する情報を事前にまとめ、 セッションごとに数千トークンを節約します。

使用する場面

• セッションの開始時にプロジェクトのレイアウトを把握する
• 機能を実装する前にエントリーポイントを特定する
• 不慣れなコードベースを調べる
• Read 呼び出しによるトークンの浪費を減らす
• 変更前に影響範囲の大きいホットファイルを特定する

使用しない場面

• セッションの途中ですでにコンテキストが予算を超えている場合（ conserve:clear-context を使用）
• コードベースの肥大化を監査する場合（conserve:bloat-detector を使用）

検出対象

カテゴリ	説明
構造	ファイル数と言語を含むディレクトリレイアウト
依存関係	複数のエコシステムに対応：Python、Node、Rust、Go、Java
フレームワーク	依存関係の分析によるフレームワークの検出
エントリーポイント	main.py、index.ts、CLI スクリプトなど
インポートグラフ	ファイル間のインポート関係
ホットファイル	3 つ以上のファイルからインポートされるファイル（影響範囲が大きい）
ルート	FastAPI、Flask、Express、Hono の API エンドポイント
環境変数	デフォルト値を含む環境変数の参照
ミドルウェア	認証、CORS、レート制限、ロギングのパターン
モデル／スキーマ	SQLAlchemy、Django、Pydantic、Prisma の定義
トークン節約量	手動での調査と比べて節約できる推定トークン数

手順

1. プロジェクトルートでスキャナーを実行します。

PYTHONPATH="$(find . -path '*/conserve/scripts' -type d \
  -print -quit 2>/dev/null || \
  echo 'plugins/conserve/scripts')" \
  python3 -m context_scanner .

2. 出力をプロジェクトの概要としてユーザーに提示します。

3. コンテキストマップを使って、その後に読み込むファイルを決めます。 まずホットファイルとエントリーポイントを優先してください。

オプション

出力

• --format json で構造化された出力を指定します
• --max-tokens N で出力サイズを調整します（デフォルト：5000）
• --output FILE でファイルに保存します

モード

• --blast FILE で特定のファイルの影響範囲を表示します
• --section NAME で単一のセクションを出力します （routes、deps、env、hot-files、models、structure、 middleware、frameworks）
• --wiki-only で標準出力なしで Wiki 記事を生成します

オプトアウト

• --no-cache で新たにスキャンを実行します
• --no-wiki で Wiki 記事の生成をスキップします

Wiki 記事

スキャナーは、必要なコンテキストだけを選択して読み込めるよう、 トピックごとのナレッジ記事を .codesight/ に生成します。

python3 scanner.py .
# Creates .codesight/INDEX.md, auth.md, database.md, etc.

マップ全体ではなく、セッションごとに必要なものだけを読み込みます。

python3 scanner.py --section routes .
# ~200 tokens vs ~5,000 for the full map

出力例

# Context Map: myproject
Files: 127

## Structure
  src                  42 files (Python)
  tests                18 files (Python)
  docs                  5 files (Markdown)

## Dependencies (Python)
Package manager: uv
  - fastapi 0.104.0
  - pydantic 2.5.0
  - sqlalchemy 2.0.0
  ...12 more

## Frameworks Detected
  - FastAPI
  - SQLAlchemy
  - Pytest

## Routes
  GET    /users          (src/routes/users.py)
  POST   /users          (src/routes/users.py)
  GET    /users/{id}     (src/routes/users.py)

## Hot Files (high blast radius)
  - src/models/base.py (12 importers)
  - src/utils/auth.py (8 importers)

## Environment Variables
  - DATABASE_URL (required)
  - SECRET_KEY (has default)

## Token Savings: ~12,600 tokens saved
  Routes: ~1,200
  Hot files: ~300
  Env vars: ~200
  File scanning: ~10,200

完了条件

• スキャナーの出力には、少なくともファイル数、 ディレクトリ構造、検出されたフレームワーク、ホットファイル（3 つ以上のファイルから インポートされるファイル）が含まれていること。機能実装のためのファイル読み込みを 始める前に、出力がセッション内に表示されていること
• 出力に「トークン節約量」の行があり、数値による推定値が含まれていること（例：~12,600 tokens saved）
• --blast FILE が使われた場合、影響範囲の出力に対象の ファイル名が含まれ、インポート元が件数とともに列挙されていること
• コンテキストマップがその後のファイル読み込みの指針となっていること。セッション内の 他のファイルを読む前に、ホットファイルとエントリーポイントが参照されていること