codemap

Codemap

私が行うこと

コードベース全体を分析し、.planning/codebase/ に包括的なドキュメントファイルを7つ作成します。

• STACK.md - テクノロジー、依存関係、設定
• INTEGRATIONS.md - サードパーティープロバイダー、API、データベース、認証プロバイダー
• ARCHITECTURE.md - システムのパターン、レイヤー、データフロー
• STRUCTURE.md - ディレクトリ構成、主要な場所、命名規則
• CONVENTIONS.md - コードスタイル、パターン、エラー処理
• TESTING.md - フレームワーク、構成、モック、カバレッジ
• CONCERNS.md - 技術的負債、バグ、セキュリティ、パフォーマンスの問題

使用する場面

次のことが必要な場合に、このスキルを使用します。

• オンボーディングして、新しい開発者がコードベースをすばやく理解できるようにする
• 既存のパターンを十分に把握したうえで、新機能を計画する
• 変更を加える前に、コードの規約を理解する
• 技術的負債や懸念事項を特定する
• プロジェクトの現状を文書化する

仕組み

このスキルでは、4つの観点で調査を行います。実行環境で利用できる場合は、ファイルの読み取りと書き込みを行うワーカーを並列で使用します。適切なワーカーを利用できない場合は、現在のコンテキストで同じ調査を順番に実施します。

1. Tech → 技術スタックと統合を分析 → STACK.md、INTEGRATIONS.md
2. Architecture → パターンと構造を分析 → ARCHITECTURE.md、STRUCTURE.md
3. Quality → 規約とテストを分析 → CONVENTIONS.md、TESTING.md
4. Concerns → 技術的負債と問題を特定 → CONCERNS.md

各調査では、次のことを行います。

• 担当する観点からコードベースを調査する
• $SKILL_PATH/templates/ のテンプレートを使用する
• .planning/codebase/ にドキュメントを直接書き込む
• 完了確認のみを返す（ドキュメントの内容は返さない）

オーケストレーターは次のことを行います。

• .planning/codebase/ ディレクトリを作成する
• 適切なワーカーを利用できる場合に限り、4つの調査を並列で実行する
• そうでない場合は、現在のコンテキストで調査を順番に実行する
• 完了確認を収集する
• すべてのドキュメントが作成されたことを確認する
• 設定されている場合は、コードベースマップをコミットする

プロセス

範囲と実行環境

増分マップを作成する場合は、任意で --paths <p1,p2,...> を指定できます。使用前にリポジトリ相対のパスプレフィックスを検証し、絶対パス、.. コンポーネント、シェルのメタ文字（;、バッククォート、$、&、|、<、>）を含むものは拒否してください。有効なパスが1つも指定されていない場合は、修正された範囲を尋ねて処理を停止してください。暗黙にリポジトリ全体へ範囲を広げてはいけません。正規化した同じ範囲を、すべてのマッパーと順次実行する各調査に渡してください。未検証の入力をシェルコマンドに埋め込んではいけません。

分析日を示すプレースホルダーには、実際の現在の日付を使用してください。範囲を指定して更新する場合は、範囲外の記述済み情報を保持し、再確認したプレフィックスを明記してください。

並列エージェントは、実行環境がファイルの読み取りと書き込みを行うワーカーをサポートしている場合にのみ使用してください。explore エージェントがファイルを書き込めると決めつけたり、ブラウザーエージェントをコードマッパーとして使用したりしないでください。適切なワーカーが利用できない場合は、同じ範囲とテンプレートを使用し、現在のコンテキストで4つの調査を順番に実施してください。GSD 固有の SDK コマンドやエージェントタイプは必須にしないでください。

ステップ 1: 既存のマップを確認する

.planning/codebase/ がすでに存在する場合は、次のように確認してください。

.planning/codebase/ already exists. What's next?
1. Refresh - Delete existing and remap codebase
2. Update - Keep existing, only update specific documents
3. Skip - Use existing codebase map as-is

ステップ 2: 構成を作成する

出力ディレクトリを作成します。

mkdir -p .planning/codebase

ステップ 3: 4つの観点で調査する

実行環境がファイルの読み取りと書き込みを行うワーカーをサポートしている場合に限り、調査を並列で実行してください。そうでない場合は、現在のコンテキストで順番に実施してください。並列ワーカーの使用は任意であり、必須ではありません。各調査には、検証済みの範囲、現在の日付、$SKILL_PATH/templates/ にある適切なテンプレートパスを渡す必要があります。以下の例は担当内容を示すものであり、必須の API パラメーター名を指定するものではありません。並列ワーカーの実行中は、その調査を重複して行ったり、ワーカーが担当するドキュメントを書き込んだりしないでください。

Tech エージェント:

agent_type: explore
description: Map codebase tech stack
prompt: |
	Focus: tech

	Analyze this codebase for technology stack and external integrations.

	Write these documents to .planning/codebase/:
	- STACK.md - Languages, runtime, frameworks, dependencies, configuration
	- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.

Architecture エージェント:

agent_type: explore
description: Map codebase architecture
prompt: |
	Focus: arch

	Analyze this codebase architecture and directory structure.

	Write these documents to .planning/codebase/:
	- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
	- STRUCTURE.md - Directory layout, key locations, naming conventions

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.

Quality エージェント:

agent_type: explore
description: Map codebase conventions
prompt: |
	Focus: quality

	Analyze this codebase for coding conventions and testing patterns.

	Write these documents to .planning/codebase/:
	- CONVENTIONS.md - Code style, naming, patterns, error handling
	- TESTING.md - Framework, structure, mocking, coverage

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.

Concerns エージェント:

agent_type: explore
description: Map codebase concerns
prompt: |
	Focus: concerns

	Analyze this codebase for technical debt, known issues, and areas of concern.

	Write this document to .planning/codebase/:
	- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas

	Use the templates from map-codebase skill. Explore thoroughly.
	Write document directly. Return confirmation only.

ステップ 4：出力を検証する

すべてのマッパーが完了するまで待ちます。想定される7つのドキュメントがすべて存在し、それぞれが20行を超えていることを確認します。ファイル名があるだけでは成功とはみなしません。欠落、短い、または失敗した出力を報告し、完了を宣言する前に修正します。日付が最新であること、および対象を絞った出力で影響を受けない情報が保持されていることを確認します。

ls -la .planning/codebase/
wc -l .planning/codebase/*.md

ステップ 5：シークレットの確認と任意のコミット

ドキュメントを表示またはコミットする前に、誤ってコピーされた認証情報がないかスキャンします。設定パスと環境変数名は記載しても、シークレットの値は記載しません。マップの作成時に .env の内容や認証情報ファイルを読み込まないでください。利用可能な場合は、リポジトリのシークレットスキャナーを使用します。最小限の補足チェックは次のとおりです。

rg -l '(sk-[A-Za-z0-9]{20,}|gh[pousr]_[A-Za-z0-9]{36,}|AKIA[A-Z0-9]{16}|xox[baprs]-[A-Za-z0-9-]+|-----BEGIN.*PRIVATE KEY)' .planning/codebase/*.md

これは一致したシークレットの値ではなく、ファイル名のみを出力します。一致がない場合の終了ステータスは正常です。スキャナーのエラーは、スキャンが問題なく完了したことを意味しません。一致が見つかった場合は作業を中断し、内容を伏せ字にしてから、続行前に再確認します。パターンマッチングだけでは、すべてのシークレットが存在しないことの証明にはなりません。ログや設定からコピーした抜粋も確認してください。

チェックに問題がなく、.planning/ が gitignore されておらず、ユーザーがコミットを希望する場合は、次のようにします。

git add .planning/codebase/*.md
git commit -m "docs: map existing codebase

- STACK.md - Technologies and dependencies
- ARCHITECTURE.md - System design and patterns
- STRUCTURE.md - Directory layout
- CONVENTIONS.md - Code style and patterns
- TESTING.md - Test structure
- INTEGRATIONS.md - External services
- CONCERNS.md - Technical debt and issues"

ステップ 6：概要

完了の概要を提示します。

Codebase mapping complete.

Created .planning/codebase/:
- STACK.md ([N] lines) - Technologies and dependencies
- ARCHITECTURE.md ([N] lines) - System design and patterns
- STRUCTURE.md ([N] lines) - Directory layout and organization
- CONVENTIONS.md ([N] lines) - Code style and patterns
- TESTING.md ([N] lines) - Test structure and practices
- INTEGRATIONS.md ([N] lines) - External services and APIs
- CONCERNS.md ([N] lines) - Technical debt and issues

Next steps:
- Review documents: cat .planning/codebase/STACK.md
- Use these as reference when planning features
- Update as codebase evolves

テンプレート

テンプレートは $SKILL_PATH/templates/ にあります。

• STACK.md.template - 技術スタック
• INTEGRATIONS.md.template - 外部連携
• ARCHITECTURE.md.template - システムアーキテクチャ
• STRUCTURE.md.template - ディレクトリ構造
• CONVENTIONS.md.template - コーディング規約
• TESTING.md.template - テストのパターン
• CONCERNS.md.template - 技術的な懸念事項

各エージェントは適切なテンプレートを読み、コードベースを調査した内容に基づいて記入します。

エージェントのガイドライン

マッパーエージェントとして起動された場合：

調査コマンド

補足：利用可能であれば fd を使用し、なければ find にフォールバックします

# Define finder helper (fd if available, otherwise find)
_finder() { command -v fd >/dev/null 2>&1 && fd "$@" || find "$@"; }
_rg() { command -v rg >/dev/null 2>&1 && rg "$@" || grep -r "$@"; }

技術面の重点項目：

# Package manifests
cat package.json pyproject.toml Cargo.toml go.mod 2>/dev/null

# Config files
ls -la *.config.* tsconfig.json 2>/dev/null

# Find SDK/API imports
_rg "import.*stripe|import.*supabase|import.*aws" src/ 2>/dev/null | head -50

アーキテクチャ面の重点項目：

# Directory structure (fd is faster and ignores node_modules/.git by default)
_finder -t d . | head -50

# Entry points
_finder -t f "index.*" "main.*" "app.*" src/ app/ 2>/dev/null | head -20

# Import patterns
_rg "^import" src/ 2>/dev/null | head -100

品質面の重点項目：

# Linting/formatting config
cat .eslintrc* .prettierrc* biome.json 2>/dev/null

# Test files
_finder -t f "\.test\." "\.spec\." 2>/dev/null | head -30

懸念事項の重点項目：

# TODO/FIXME comments
_rg "TODO|FIXME|HACK|XXX" src/ 2>/dev/null | head -50

# Large files (potential complexity)
_finder -t f "\.ts$" -e "\.tsx$" src/ 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -20

重要なルール

1. ドキュメントに直接書き込む - Write ツールを使用し、内容を返さないでください
2. 常にファイルパスを含める - すべての調査結果にバッククォートで囲んだファイルパスを含めてください
3. テンプレートを使用する - テンプレートの構成を正確に埋めてください
4. 徹底して調査する - 実際のファイルを読み、推測しないでください
5. 確認のみを返す - 応答はファイルパスと行数を含む約10行にしてください
6. コミットはスキップする — Git 操作はオーケストレーターが処理します

参考にしたもの

このスキルは glittercowboy/get-shit-done に着想を得て、そこから改変したものです。具体的には、map-codebase workflow と gsd-codebase-mapper agent を参考にしています。