Repo Atlas

エンジニアとLLMエージェントが最小限の検索で任意のコードベースを迅速に理解できるよう、リポジトリ内に永続的なコンテキストシステムを構築します。

ハード制約

• 製品/ランタイムの動作を変更しないこと
• 有料/ホスト型ツール不可 — すべてリポジトリ内に存在すること
• 依存関係はゼロまたは最小限（Python 3標準ライブラリのみ）
• 生成されたコンテンツはすべてリポジトリの具体的な仕様を反映していること。汎用的なプレースホルダーは不可

ワークフロー

フェーズ1: 調査

何かを書く前に、リポジトリを理解します:

1. トップレベルのディレクトリ構造を読む
2. リポジトリタイプを特定する:
   • アプリ（Web、モバイル、デスクトップ） — スクリーン/ビュー、状態管理、ルートを持つ
   • バックエンド/API — コントローラ、ルート、ミドルウェア、モデルを持つ
   • ライブラリ — パブリック公開、モジュール構造、ビルド設定を持つ
   • モノレポ — 複数のパッケージ/サービス
   • CLIツール — コマンドハンドラ、引数パース機能を持つ
   • インフラストラクチャ — デプロイメント設定、IaCファイルを持つ
3. 主要な言語とフレームワークを特定する
4. エントリポイント、ビルド設定、CIファイルを見つける
5. 5〜10個の主要なファイルを読んでアーキテクチャパターンを理解する

フェーズ2: ジェネレータスクリプトを実行

このスキルに付属している scripts/generate_atlas.py をリポジトリの scripts/atlas/generate_atlas.py にコピーします。その後、カスタマイズして実行します:

1. スクリプトをターゲットリポジトリにコピーする
2. トップの設定セクションを確認してカスタマイズする:
   • IGNORE_NAMES — リポジトリ固有のディレクトリ名を追加（完全一致）
   • TREE_ANNOTATIONS — 主要ディレクトリの簡潔な説明を追加
   • ENTRYPOINT_NAMES — フレームワーク固有のエントリファイル名を追加
   • ENTRYPOINT_PATH_PATTERNS — パスベースのパターンを追加（fnmatchスタイル。例: cmd/*/main.go）
   • ENTRYPOINT_CONTENT_MARKERS — エントリポイントを識別するコードマーカーを追加
   • CONVENTIONAL_COMMITS — リポジトリが異なるコミット規約を使用している場合は調整
   • CHANGELOG_DAYS — changelogのルックバックウィンドウを変更（デフォルト: 14）
3. 実行: python3 scripts/atlas/generate_atlas.py --write

自動生成されるもの:

• docs/atlas/repo-map.md — ディレクトリツリー + エントリポイント + ファイル統計
• docs/atlas/08_CHANGELOG_LAST_14_DAYS.md — カテゴリ分けされた最近のコミット

フェーズ3: repo-map.md を拡張

スクリプトがスケルトンを生成した後、repo-map.md に以下のセクションを手動で追加します:

ルータテーブル — 「Xをどこで探すか」（10〜15行）:

## Where to Look for X

| Task | Start Here |
|------|-----------|
| Fix [domain concept] | `path/to/file.ext` |

このリポジトリで実行される上位10〜15のタスクを特定のファイルにマップします。

危険ゾーン — 脆弱なファイル/領域:

## Danger Zones

| File/Area | Why It's Fragile |
|-----------|-----------------|
| `path/to/file` | Reason |

フェーズ4: 手動でアトラスドキュメントを作成

docs/atlas/ に以下のファイルを作成します。各ファイルの構造ガイダンスは references/atlas-templates.md を参照してください。

ファイル	コンテンツソース
00_README.md	アトラスの使い方 + エージェント ワークフロー規約
01_ARCHITECTURE.md	エントリポイント、DI設定、モジュール境界を読む
02_DOMAIN_MODEL.md	モデル/型を読み、状態マシンを特定
03_CRITICAL_FLOWS.md	上位3〜5のユーザーフローをコード全体で追跡
04_STATE_SOURCES_OF_TRUTH.md	すべての状態ストア（DB、キャッシュ、ファイル、メモリ）を特定
05_EXTERNAL_DEPENDENCIES.md	パッケージマニフェスト + 統合コードを読む
06_GOTCHAS.md	競合状態、初期化順序、脆弱なパターンを探す
07_TEST_MATRIX.md	テスト設定を読み、テスト実行方法を説明

各ドキュメントは50〜150行で、実際のパス、実際のコード参照、コードベースからの実際の落とし穴を含むべきです。汎用的なアドバイスではなく。

フェーズ5: エージェントオンランプを追加

リポジトリの CLAUDE.md にアトラスセクションを追加します（存在しない場合は作成）。以下を含めます:

## Atlas — 永続的コンテキストシステム

`docs/atlas/` フォルダには、高速なコードベースオンボーディングのための構造化ドキュメントが含まれています。

### エージェント ワークフロー

**エージェントA（計画 + 実行）**:
1. オリエンテーションのために `docs/atlas/repo-map.md` をロード
2. タスク用のドメイン固有アトラスドキュメントをロード
3. アトラスが検索を絞った後のみソースファイルを読む
4. アトラスのパターンに従って変更を実装

**エージェントB（検証）**:
1. `docs/atlas/06_GOTCHAS.md` に対するdiffをレビュー
2. 変更が `03_CRITICAL_FLOWS.md` で説明されるフローと一致することを確認
3. `07_TEST_MATRIX.md` に従ってテストが合格することを確認
4. `04_STATE_SOURCES_OF_TRUTH.md` に対する状態の一貫性を確認

### 作業ルール
- **最初に分析**: コードを書く前に関連するアトラスドキュメントを読む
- **動作を確認**: 変更後、重要なフローが依然として機能することを確認
- **テストカンニング不可**: テストはコードが正しいから合格する必要がある
- **アトラスを更新**: 変更がアーキテクチャ/フロー/状態を変更する場合、関連ドキュメントを更新
- **再生成**: 構造的な変更後に `make atlas-generate` を実行

フェーズ6: ビルドターゲットを追加

Makefile に追加します（必要に応じて作成）:

atlas-generate:
	python3 scripts/atlas/generate_atlas.py --write

atlas-check:
	python3 scripts/atlas/generate_atlas.py --check

リポジトリが package.json を使用している場合は、スクリプトにも追加します:

"atlas:generate": "python3 scripts/atlas/generate_atlas.py --write",
"atlas:check": "python3 scripts/atlas/generate_atlas.py --check"

フェーズ7: 検証

1. atlas-generate を実行 — エラーなしで完了する必要があります
2. atlas-check を実行 — 生成直後に終了コード0で終了する必要があります
3. すべてのアトラスドキュメントが実際のファイルパスとリポジトリ固有のコンテンツを持つことを確認
4. ランタイム/製品コードが変更されていないことを確認

出力サマリー

すべてのフェーズを完了した後、以下をレポートします:

• 作成されたファイルのリスト
• アトラスの生成/チェック実行方法
• 「エージェントがこのアトラスを使用すべき方法」の10行クイックリファレンス

リソース

• ジェネレータスクリプト: scripts/generate_atlas.py を参照 — ターゲットリポジトリにコピーしてカスタマイズ
• ドキュメントテンプレート: 各手動ドキュメントの構造ガイダンスは references/atlas-templates.md を参照