開発タスク用詳細調査スキル

project.yaml（または setup.yaml）を入力として、対象リポジトリを体系的に調査し、詳細な調査結果をドキュメント化します。

SSOT: project.yaml を全プロセスの Single Source of Truth として使用します。

• 調査の背景情報: setup.description.background
• 調査結果の出力: investigation セクション

概要

このスキルは以下を実現します：

1. project.yaml から対象リポジトリ・チケット情報を取得（meta + setup セクション）
2. project.yaml の setup.description.background を調査の背景・コンテキストとして参照
3. docs/{target_repo}/investigation/ ディレクトリに詳細調査結果をファイル分割で出力（UML図含む）
4. project.yaml の investigation セクション を更新してコミット

入力ファイル

1. project.yaml（推奨・SSOT）

brainstorming スキルで生成されたプロジェクトコンテキストファイル。

yaml
1# project.yaml から参照するセクション
2meta:
3  ticket_id: "PROJ-123"
4  task_name: "機能追加タスク"
5  target_repo: "target-repo"
6  branch: "feature/PROJ-123"
7
8setup:
9  description:
10    overview: "概要..."
11    purpose: "目的..."
12    background: |                    # ← このスキルが参照
13      現在の機能では以下の課題がある:
14      - 課題1: ○○ができない
15      - 課題2: △△に時間がかかる
16    requirements:
17      functional: [...]
18      non_functional: [...]
19  target_repositories:
20    - name: "target-repo"
21      url: "git@github.com:org/target-repo.git"
22      base_branch: "main"
23  related_repositories:
24    - name: "related-repo"
25      url: "git@github.com:org/related-repo.git"
26
27# brainstorming の結果（参照可能）
28brainstorming:
29  status: completed
30  refined_requirements: [...]        # 深掘りされた要件も参照

2. setup.yaml（fallback）

project.yaml が存在しない場合のみ使用。

yaml
1ticket_id: "PROJ-123"
2task_name: "機能追加タスク"
3
4description:
5  overview: "概要..."
6  purpose: "目的..."
7  background: |
8    現在の機能では以下の課題がある:
9    - 課題1: ○○ができない
10    - 課題2: △△に時間がかかる
11  requirements:
12    functional: [...]
13    non_functional: [...]
14
15target_repositories:
16  - name: "target-repo"
17    url: "git@github.com:org/target-repo.git"
18    base_branch: "main"

3. design-document: docs/{ticket_id}.md（任意）

init-work-branchスキルで生成された設計ドキュメント。存在する場合は調査結果セクションも更新。

処理フロー

mermaid
1flowchart TD
2    A[project.yaml存在確認] --> B{project.yaml存在?}
3    B -->|Yes| C[project.yamlから情報取得]
4    B -->|No| D[setup.yamlから情報取得]
5    C --> E[setup.description.background を参照]
6    D --> E
7    E --> F[brainstorming.refined_requirements 参照]
8    F --> G[対象リポジトリの調査実施]
9    G --> H[investigation/配下にファイル生成]
10    H --> I[project.yaml investigationセクション更新]
11    I --> J[design-document更新（存在する場合）]
12    J --> K[コミット]
13    K --> L[完了レポート]

project.yaml からの情報取得

背景情報の参照

project.yaml の setup.description.background を調査のコンテキストとして活用します：

yaml
1# project.yaml から取得
2setup:
3  description:
4    background: |
5      現在の機能では以下の課題がある:
6      - 課題1: ○○ができない
7      - 課題2: △△に時間がかかる
8      
9      これらの課題を解決するため、機能Aの実装が必要。

brainstorming 結果の参照

brainstorming セクションが完了している場合、深掘りされた要件も参照します：

yaml
1# project.yaml から取得
2brainstorming:
3  status: completed
4  refined_requirements:
5    - "リフレッシュトークンによる自動更新"
6    - "OAuth2.0 プロバイダ連携"
7  decisions:
8    - question: "認証方式は？"
9      decision: "JWTベース"

活用方法:

• 調査の焦点を明確にする（どの課題に関連するコードを重点的に調査するか）
• brainstorming で決定された方針に関連する既存実装を重点的に調査
• 既存の問題点との関連性を分析する
• 調査結果レポートに背景情報を含める

調査実施項目

1. アーキテクチャ調査

• プロジェクト全体の構成把握
• ディレクトリ構造・レイヤー構成
• コンポーネント図の作成（Mermaid）

2. データ構造調査

• エンティティ・スキーマ定義の把握
• ER図の作成（Mermaid）
• 型定義・インターフェースの整理

3. 依存関係調査

• 外部パッケージ依存関係
• 内部モジュール間依存関係
• 依存関係図の作成（Mermaid）

4. 既存パターン調査

• コーディング規約・スタイル
• 実装パターン・設計パターン
• テストパターン

5. 統合ポイント調査

• 他モジュール・サービスとの接点
• API連携・イベント連携
• シーケンス図の作成（Mermaid）

6. リスク・制約分析

• 潜在的な問題点の特定
• 技術的制約・要件制約
• 影響度・発生可能性の評価

出力ファイル構成

調査結果は docs/{target_repository}/investigation/ に出力：

docs/
└── {target_repository}/
    └── investigation/
        ├── 01_architecture.md          # アーキテクチャ調査
        ├── 02_data-structure.md        # データ構造調査
        ├── 03_dependencies.md          # 依存関係調査
    ├── 04_existing-patterns.md     # 既存パターン調査
    ├── 05_integration-points.md    # 統合ポイント調査
    └── 06_risks-and-constraints.md # リスク・制約分析

各ファイルはテンプレート references/template.md に従って作成。

調査手法

アーキテクチャ調査

bash
1# ディレクトリ構造の確認
2find . -type d -maxdepth 3 | head -50
3
4# 設定ファイルの確認
5find . -name "*.config.*" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" | head -30
6
7# エントリーポイントの確認
8grep -r "main\|index\|app" --include="*.ts" --include="*.js" --include="*.py" -l | head -20

データ構造調査

bash
1# 型定義・インターフェースの検索
2grep -r "interface\|type\|class\|entity\|model\|schema" --include="*.ts" --include="*.py" -l | head -30
3
4# ORM/DBスキーマの検索
5find . -name "*entity*" -o -name "*model*" -o -name "*schema*" | head -20

依存関係調査

bash
1# パッケージ依存関係
2cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat requirements.txt 2>/dev/null
3
4# インポート文の分析
5grep -r "^import\|^from" --include="*.ts" --include="*.py" | head -50

既存パターン調査

bash
1# コーディングスタイル設定
2cat .eslintrc* .prettierrc* .editorconfig pyproject.toml setup.cfg 2>/dev/null
3
4# テストファイルの構成
5find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" | head -20

統合ポイント調査

bash
1# API定義・エンドポイント
2grep -r "router\|endpoint\|@Get\|@Post\|api\|route" --include="*.ts" --include="*.py" -l | head -20
3
4# イベント・メッセージング
5grep -r "emit\|publish\|subscribe\|event\|listener" --include="*.ts" --include="*.py" -l | head -20

design-document更新内容

docs/{ticket_id}.md の「1. 調査結果」セクションを更新：

markdown
1## 1. 調査結果
2
3### 1.1 現状分析
4
5{アーキテクチャ・データ構造・依存関係の要約}
6
7詳細は [investigation/](./{target_repo}/investigation/) を参照。
8
9### 1.2 関連コード・ファイル
10
11| ファイル | 役割 | 備考 |
12| -------- | ---- | ---- |
13| ...      | ...  | ...  |
14
15### 1.3 参考情報
16
17- [アーキテクチャ調査](./{target_repo}/investigation/01_architecture.md)
18- [データ構造調査](./{target_repo}/investigation/02_data-structure.md)
19- [依存関係調査](./{target_repo}/investigation/03_dependencies.md)
20- [既存パターン調査](./{target_repo}/investigation/04_existing-patterns.md)
21- [統合ポイント調査](./{target_repo}/investigation/05_integration-points.md)
22- [リスク・制約分析](./{target_repo}/investigation/06_risks-and-constraints.md)

UML/図表ガイドライン

Mermaid形式を使用して以下の図を作成：

コンポーネント図（アーキテクチャ）

mermaid
1graph TD
2    subgraph Presentation Layer
3        A[Controller]
4        B[View]
5    end
6    subgraph Business Layer
7        C[Service]
8        D[UseCase]
9    end
10    subgraph Data Layer
11        E[Repository]
12        F[Entity]
13    end
14    A --> C
15    C --> E
16    E --> F

ER図（データ構造）

mermaid
1erDiagram
2    USER ||--o{ ORDER : places
3    USER {
4        int id PK
5        string name
6        string email
7    }
8    ORDER ||--|{ ORDER_ITEM : contains
9    ORDER {
10        int id PK
11        int user_id FK
12        date created_at
13    }

シーケンス図（統合ポイント）

mermaid
1sequenceDiagram
2    participant C as Client
3    participant A as API
4    participant S as Service
5    participant D as Database
6    
7    C->>A: Request
8    A->>S: Process
9    S->>D: Query
10    D-->>S: Result
11    S-->>A: Response
12    A-->>C: Response

クラス図（オブジェクト構成）

mermaid
1classDiagram
2    class User {
3        +int id
4        +string name
5        +string email
6        +create()
7        +update()
8    }
9    class Order {
10        +int id
11        +User user
12        +List~OrderItem~ items
13        +place()
14        +cancel()
15    }
16    User "1" --> "*" Order

依存関係図

mermaid
1graph LR
2    subgraph External
3        E1[express]
4        E2[typeorm]
5        E3[jest]
6    end
7    subgraph Internal
8        I1[controllers]
9        I2[services]
10        I3[repositories]
11    end
12    I1 --> I2
13    I2 --> I3
14    I1 --> E1
15    I3 --> E2

実行手順

1. project.yaml / setup.yaml 読み込み

bash
1# project.yaml を優先、なければ setup.yaml を使用
2if [ -f "project.yaml" ]; then
3    CONFIG_FILE="project.yaml"
4    echo "project.yaml を使用"
5else
6    CONFIG_FILE="${1:-setup.yaml}"
7    test -f "$CONFIG_FILE" || { echo "Error: $CONFIG_FILE not found"; exit 1; }
8    echo "setup.yaml を使用（project.yaml なし）"
9fi

project.yaml からの情報抽出（yq 使用）:

bash
1# メタ情報の取得
2TICKET_ID=$(yq '.meta.ticket_id' project.yaml)
3TASK_NAME=$(yq '.meta.task_name' project.yaml)
4TARGET_REPO=$(yq '.meta.target_repo' project.yaml)
5
6# 調査対象リポジトリ一覧
7yq '.setup.target_repositories[].name' project.yaml
8
9# 背景情報の取得
10yq '.setup.description.background' project.yaml
11
12# brainstorming の深掘り要件（存在する場合）
13yq '.brainstorming.refined_requirements // []' project.yaml

2. design-document確認（任意）

bash
1DOCS_DIR="${options.design_document_dir:-docs}"
2DESIGN_DOC="$DOCS_DIR/${ticket_id}.md"
3if [ -f "$DESIGN_DOC" ]; then
4    echo "design-document を発見: $DESIGN_DOC"
5fi

3. 対象リポジトリの調査

各 target_repository に対して調査を実施：

bash
1for repo in "${target_repositories[@]}"; do
2    REPO_PATH="submodules/${repo}"
3    OUTPUT_DIR="docs/${repo}/investigation"
4    cd "$REPO_PATH"
5    
6    # investigation ディレクトリ作成（出力先はdocs配下）
7    mkdir -p "../${OUTPUT_DIR}"
8    
9    # 各調査を実施し、結果をファイルに出力
10    # ... (調査処理)
11    
12    cd -
13done

4. project.yaml の investigation セクション更新

調査結果の要約を project.yaml に yq で更新：

bash
1# investigation セクションの初期化（ヘルパー使用）
2./scripts/project-yaml-helper.sh init-section investigation
3
4# 各フィールドを yq で更新
5yq -i '.investigation.status = "completed"' project.yaml
6yq -i ".investigation.completed_at = \"$(date -Iseconds)\"" project.yaml
7yq -i '.investigation.summary = "アーキテクチャ・データ構造・依存関係の要約"' project.yaml
8yq -i '.investigation.key_findings = ["重要な発見1", "重要な発見2"]' project.yaml
9yq -i '.investigation.risks = ["特定されたリスク"]' project.yaml
10yq -i ".investigation.artifacts = \"docs/${TARGET_REPO}/investigation/\"" project.yaml
11
12# meta.updated_at を更新
13yq -i ".meta.updated_at = \"$(date -Iseconds)\"" project.yaml

またはヘルパーの update コマンドで簡易更新：

bash
1./scripts/project-yaml-helper.sh update investigation --status completed \
2  --summary "調査結果の要約" --artifacts "docs/${TARGET_REPO}/investigation/"

5. design-document更新（存在する場合）

調査結果の要約を docs/{ticket_id}.md の「1. 調査結果」セクションにも埋め込み。

6. コミット

bash
1# project.yaml と調査結果をコミット
2git add project.yaml docs/
3git commit -m "docs: investigation 完了
4
5- project.yaml の investigation セクションを更新
6- docs/{target_repo}/investigation/ に詳細調査結果を出力"

完了レポート

markdown
1## 調査完了 ✅
2
3### 調査対象
4- チケット: {ticket_id}
5- タスク: {task_name}
6- リポジトリ: {target_repositories}
7
8### project.yaml 更新内容
9
10\`\`\`yaml
11investigation:
12  status: completed
13  started_at: "{開始時に記録した時刻}"
14  completed_at: "{timestamp}"
15  summary: |
16    {調査結果の要約}
17  key_findings:
18    - "{発見1}"
19    - "{発見2}"
20  risks:
21    - "{リスク}"
22  artifacts: "docs/{target_repo}/investigation/"
23\`\`\`
24
25### 生成されたファイル
26
27#### 詳細調査結果
28- docs/{target_repo}/investigation/01_architecture.md
29- docs/{target_repo}/investigation/02_data-structure.md
30- docs/{target_repo}/investigation/03_dependencies.md
31- docs/{target_repo}/investigation/04_existing-patterns.md
32- docs/{target_repo}/investigation/05_integration-points.md
33- docs/{target_repo}/investigation/06_risks-and-constraints.md
34
35### 次のステップ
361. 調査結果をレビュー
372. 設計スキル（design）を使用して詳細設計を開始
383. タスク計画スキル（plan）でタスク分割を実施

エラーハンドリング

project.yaml も setup.yaml も見つからない

エラー: project.yaml も setup.yaml も見つかりません

brainstorming スキルで project.yaml を生成するか、
init-work-branch スキルで setup.yaml を作成してください。

design-documentが見つからない

警告: design-documentが見つかりません
ファイル: docs/{ticket_id}.md

design-document の更新はスキップします。
project.yaml の investigation セクションは更新されます。

対象リポジトリにアクセスできない

警告: リポジトリにアクセスできません
リポジトリ: submodules/{repo_name}

git submodule update --init を実行してください。

注意事項

• 調査対象は target_repositories のみ（related_repositories は参照用）
• 大規模リポジトリの場合、調査に時間がかかる可能性あり
• 既存の investigation/ ディレクトリがある場合は上書き確認を行う
• project.yaml を SSOT として使用し、investigation セクションを更新
• brainstorming が完了している場合、refined_requirements も参照

参照ファイル

• テンプレート: references/template.md - 各調査ファイル用テンプレート
• 前提スキル: brainstorming - 要件深掘り（project.yaml を生成）
• 前提スキル: init-work-branch - 作業ブランチ初期化
• 後続スキル: design - 詳細設計

SSOT参照

出力（project.yaml への書き込み）