acquire-codebase-knowledge

コードベースの知識を取得する

プロジェクトで効果的に作業するために必要な情報を網羅した、内容のある7つのドキュメントをdocs/codebase/に作成します。ファイルやターミナル出力から検証できることだけを記載し、推測や憶測は一切しないでください。

出力要件（必須）

作業を終える前に、次のすべてを満たしている必要があります。

1. docs/codebase/に存在するファイルは、STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.mdの7つだけです。
2. すべての記述をソースファイル、設定、またはターミナル出力からたどれるようにします。
3. 不明な点には[TODO]、意図に依存する判断には[ASK USER]を付けます。
4. すべてのドキュメントに、具体的なファイルパスを記載した短い「evidence」リストを含めます。
5. 最終回答には、番号付きの[ASK USER]の質問と、意図と現状の相違点を含めます。

ワークフロー

次のチェックリストをコピーして、進捗を記録してください。

- [ ] Phase 1: Run scan, read intent documents
- [ ] Phase 2: Investigate each documentation area
- [ ] Phase 3: Populate all seven docs in docs/codebase/
- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items

対象領域モード

ユーザーが対象領域（例：「アーキテクチャのみ」「テストと懸念事項」）を指定した場合：

1. フェーズ1は必ずすべて実施します。
2. 対象領域のドキュメントを優先して完成させます。
3. まだ調査していない対象外のドキュメントは、必須セクションを残し、不明点に[TODO]を付けます。
4. 最終出力の前に、7つすべてのドキュメントについてフェーズ4の検証ループを実施します。

フェーズ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] などの同等の項目）のみです。リンター、フォーマッター、テストフレームワークは、開発用ツールとして別途記述してください。

テスト内の TODO ≠ 本番環境の負債： test/、tests/、__tests__/、または spec/ 内の TODO は、テストカバレッジの不足であり、本番環境の技術的負債ではありません。CONCERNS.md では別々に扱ってください。

変更頻度の高いファイル = 脆弱な領域： 最近の Git 履歴に最も多く登場するファイルは、変更頻度が最も高く、隠れた複雑さを抱えている可能性があります。必ず CONCERNS.md に記載してください。

---

アンチパターン

❌ しないこと	✅ 代わりにすること
（該当するディレクトリがないのに）「ドメイン層／データ層を持つクリーンアーキテクチャを採用しています。」	実際のディレクトリ構造からわかることだけを記載してください。
（package.json を確認せずに）「これは Next.js プロジェクトです。」	まず dependencies を確認してください。実際にあるものを記載してください。
dbUrl のような変数名からデータベースを推測する	マニフェストで pg、mysql2、mongoose、prisma などを確認してください。
dist/ や build/ の命名パターンを規約として記載する	ソースファイルのみを対象にしてください。

---

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

scan.py スクリプトは、従来の出力に加えて、次のセクションも出力するようになりました。

• コードメトリクス — ファイル総数、言語別のコード行数、最大のファイル（複雑さを示す情報）
• CI/CD パイプライン — 検出された GitHub Actions、GitLab CI、Jenkins、CircleCI など
• コンテナーとオーケストレーション — Docker、Docker Compose、Kubernetes、Vagrant の設定
• セキュリティとコンプライアンス — Snyk、Dependabot、SECURITY.md、SBOM、セキュリティポリシー
• パフォーマンスとテスト — ベンチマーク設定、プロファイリング用マーカー、負荷テストツール

これらのセクションを Phase 2 で活用し、調査に関する質問を検討するとともに、ツール固有のパターンを特定してください。

---

バンドルされているアセット

アセット	読み込むタイミング
scripts/scan.py	Phase 1 — コードを読む前に、最初に実行します（Python 3.8+ が必要です）
references/inquiry-checkpoints.md	Phase 2 — テンプレートごとの調査に関する質問を確認するために読み込みます
references/stack-detection.md	Phase 2 — 技術スタックが判然としない場合にのみ読み込みます
assets/templates/STACK.md	Phase 3 step 1
assets/templates/STRUCTURE.md	Phase 3 step 2
assets/templates/ARCHITECTURE.md	Phase 3 step 3
assets/templates/CONVENTIONS.md	Phase 3 step 4
assets/templates/INTEGRATIONS.md	Phase 3 step 5
assets/templates/TESTING.md	Phase 3 step 6
assets/templates/CONCERNS.md	Phase 3 step 7

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

• デフォルトモード：各テンプレートの「Core Sections (Required)」のみを完成させます。
• 拡張モード：リポジトリの複雑さに応じて、任意のセクションを追加します。