Acquire Codebase Knowledge

docs/codebase/ に7つの充実したドキュメントを生成し、プロジェクトで効果的に作業するために必要なすべての情報をカバーします。ファイルまたはターミナル出力から検証可能な内容のみをドキュメント化してください。決して推測や仮定をしないでください。

出力契約（必須）

完了する前に、以下のすべてが真である必要があります：

1. 正確に以下のファイルが docs/codebase/ に存在すること：STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.md。
2. すべての主張がソースファイル、設定、またはターミナル出力にトレーサブルであること。
3. 不明な点は [TODO] とマークし、意図に依存する決定は [ASK USER] とマークすること。
4. すべてのドキュメントに具体的なファイルパスを含む短い「証拠」リストが含まれていること。
5. 最終レスポンスに番号付きの [ASK USER] 質問と意図と現実のズレが含まれていること。

ワークフロー

このチェックリストをコピーして追跡してください：

- [ ] フェーズ 1: スキャン実行、意図ドキュメント読取
- [ ] フェーズ 2: 各ドキュメント領域を調査
- [ ] フェーズ 3: docs/codebase/ の 7 つのドキュメントをすべて作成
- [ ] フェーズ 4: ドキュメント検証、検出結果提示、すべての [ASK USER] 項目を解決

フォーカスエリアモード

ユーザーがフォーカスエリア（例：「アーキテクチャのみ」または「テストと懸念事項」）を指定した場合：

1. フェーズ 1 を常に完全に実行してください。
2. フォーカスエリアのドキュメントを完全に完成させてください。
3. まだ分析されていない非フォーカスドキュメントについては、必須セクションを存在させ、不明な点を [TODO] とマークしてください。
4. 最終出力の前に、フェーズ 4 検証ループを 7 つすべてのドキュメントで実行してください。

フェーズ 1: スキャンと意図の読取

1. ターゲットプロジェクトルートからスキャンスクリプトを実行します：

   python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt
   

   ここで $SKILL_ROOT はスキルフォルダの絶対パスです。Windows、macOS、Linux で動作します。

   クイックスタート： パスがインラインの場合：

   python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt
   

2. PRD、TRD、README、ROADMAP、SPEC、DESIGN ファイルを検索して読み込んでください。

3. ソースコードを読む前に、述べられたプロジェクトの意図をまとめてください。

フェーズ 2: 調査

スキャン出力を使用して、7 つのテンプレートそれぞれの質問に答えてください。詳細なテンプレートごとの質問リストについては references/inquiry-checkpoints.md を読み込んでください。

スタックがあいまいな場合（複数のマニフェストファイル、不慣れなファイルタイプ、package.json なし）、references/stack-detection.md を読み込んでください。

フェーズ 3: テンプレートを作成

assets/templates/ の各テンプレートを docs/codebase/ にコピーします。以下の順序で入力してください：

1. STACK.md — 言語、ランタイム、フレームワーク、すべての依存関係
2. STRUCTURE.md — ディレクトリレイアウト、エントリーポイント、重要なファイル
3. ARCHITECTURE.md — レイヤー、パターン、データフロー
4. CONVENTIONS.md — ネーミング、フォーマット、エラーハンドリング、インポート
5. INTEGRATIONS.md — 外部 API、データベース、認証、監視
6. TESTING.md — フレームワーク、ファイル構成、モッキング戦略
7. CONCERNS.md — 技術的負債、バグ、セキュリティリスク、パフォーマンスボトルネック

コードから判定できない場合は [TODO] を使用してください。チームの意図が必要な場合は [ASK USER] を使用してください。

フェーズ 4: 検証、修復、確認

最終化する前に、以下の必須検証ループを実行してください：

1. 各ドキュメントを references/inquiry-checkpoints.md に照らし合わせて検証します。
2. 重要でない各主張について、少なくとも 1 つの証拠参照が存在することを確認します。
3. 必須セクションが不足しているか、サポートされていない場合：

• ドキュメントを修正します。
• 検証を再実行します。

4. 7 つすべてのドキュメントが合格するまで繰り返してください。

その後、7 つのドキュメントすべてのサマリーを提示し、すべての [ASK USER] 項目を番号付き質問として列挙し、フェーズ 1 の意図と現実のズレを強調してください。

検証合格基準：

• サポートされていない主張がないこと。
• 空の必須セクションがないこと。
• 不明な点が仮定ではなく [TODO] を使用していること。
• チームの意図のギャップが明示的に [ASK USER] とマークされていること。

---

落とし穴

モノレポ： ルート package.json はソースがない場合があります。workspaces、packages/、または apps/ ディレクトリを確認してください。各ワークスペースは独立した依存関係と規約を持つ場合があります。各サブパッケージを個別にマップしてください。

古い README： README は多くの場合、現在のアーキテクチャではなく意図されたアーキテクチャを説明します。実際のファイル構造と相互参照した上で、README の主張を事実として扱ってください。

TypeScript パスエイリアス： tsconfig.json の paths 設定は @/foo のようなインポートがファイルシステムに直接マップされないことを意味します。構造をドキュメント化する前に、エイリアスを実際のパスにマップしてください。

生成／コンパイル出力： dist/、build/、generated/、.next/、out/、または __pycache__/ からのパターンをドキュメント化しないでください。これらはアーティファクトです。ソース規約のみをドキュメント化してください。

.env.example が必要な設定を明かします： シークレットはコミットされません。.env.example、.env.template、または .env.sample を読んで、必要な環境変数を発見してください。

devDependencies ≠ 本番スタック： dependencies のみ（または同等のもの、例：[tool.poetry.dependencies]）が本番環境で実行されます。linter、フォーマッター、テストフレームワークを開発ツールとして個別にドキュメント化してください。

テスト TODO ≠ 本番の技術的負債： test/、tests/、__tests__/、または spec/ 内の TODO はカバレッジギャップであり、本番の技術的負債ではありません。CONCERNS.md で分離してください。

頻繁に変更されるファイル = 脆弱な領域： 最近の git 履歴に最も多く出現するファイルは修正率が最も高く、隠れた複雑性の可能性があります。常に CONCERNS.md でそれらをメモしてください。

---

アンチパターン

❌ しないこと	✅ 代わりにこうしてください
「Domain/Data レイヤーを持つクリーンアーキテクチャを使用しています」（そのようなディレクトリが存在しない場合）	ディレクトリ構造が実際に表示するものだけを述べてください。
「これは Next.js プロジェクトです」（package.json をチェックせずに）	dependencies を最初にチェックしてください。実際に存在するものを述べてください。
dbUrl のような変数名からデータベースを推測する	マニフェストで pg、mysql2、mongoose、prisma などをチェックしてください。
dist/ または build/ のネーミングパターンを規約としてドキュメント化する	ソースファイルのみ。

---

拡張スキャン出力セクション

scan.py スクリプトは、元の出力に加えて以下のセクションを生成します：

• CODE METRICS — 総ファイル数、言語別コード行数、最大ファイル（複雑性シグナル）
• CI/CD PIPELINES — 検出された GitHub Actions、GitLab CI、Jenkins、CircleCI など
• CONTAINERS & ORCHESTRATION — Docker、Docker Compose、Kubernetes、Vagrant 設定
• SECURITY & COMPLIANCE — Snyk、Dependabot、SECURITY.md、SBOM、セキュリティポリシー
• PERFORMANCE & TESTING — ベンチマーク設定、プロファイリングマーカー、ロードテストツール

フェーズ 2 中にこれらのセクションを使用して、調査質問を知らせ、ツール固有のパターンを特定してください。

---

バンドルアセット

アセット	いつロードするか
scripts/scan.py	フェーズ 1 — 最初に実行し、コードを読む前に（Python 3.8+ 必須）
references/inquiry-checkpoints.md	フェーズ 2 — テンプレートごとの調査質問用
references/stack-detection.md	フェーズ 2 — スタックがあいまいな場合のみ
assets/templates/STACK.md	フェーズ 3 ステップ 1
assets/templates/STRUCTURE.md	フェーズ 3 ステップ 2
assets/templates/ARCHITECTURE.md	フェーズ 3 ステップ 3
assets/templates/CONVENTIONS.md	フェーズ 3 ステップ 4
assets/templates/INTEGRATIONS.md	フェーズ 3 ステップ 5
assets/templates/TESTING.md	フェーズ 3 ステップ 6
assets/templates/CONCERNS.md	フェーズ 3 ステップ 7

テンプレート使用モード：

• デフォルトモード：各テンプレートの「コアセクション（必須）」のみを完成させます。
• 拡張モード：リポジトリの複雑性が正当化する場合のみ、オプションセクションを追加します。