---
description: L3 フェーズの受け入れ条件からテストと実装コードを TDD で生成し、Lint/テストの検証ループを回して L3 の検証記録に証跡を残す（AC チェック・status 更新まで含めて完了）。実装前に未解決 TODO や矛盾があれば最小限の確認質問を行う。gen-l3（フェーズ計画）の後に使う。
when_to_use: 実装して・コードを書いて・この機能を作って・PH-0001 を実装して・F-0003 をやって・続きを実装して・フェーズを進めて・テスト書いて実装して、と言われたとき。英語では implement the phase / generate code。フェーズ計画の作成・変更は gen-l3、実装完了後の後始末（アーカイブ）は archive-l3 を使う。
argument-hint: "<PH-ID|F-ID> - フェーズID または 機能ID（必須）"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# コード生成スキル

<tri_ssd_context>
Tri-SSD: L0(任意メモ docs/l0_ideas/) → L1(要件 docs/l1_requirements/vision.md) → L2(構成 docs/l2_foundation/foundation.md) → L3(フェーズ docs/l3_phases/PH-xxxx.md)。
ID形式: PREFIX-nnnn（REQ, PH, F）。番号は再利用しない（永久欠番）。
配置・分割・粒度の判断に迷ったら `${CLAUDE_SKILL_DIR}/../../docs/layer-rules.md` を読むこと。
</tri_ssd_context>

## 概要

L3 フェーズドキュメントを入力として、テストコードと実装コードを生成する。
テスト駆動で実装し、検証ループで品質を担保する。
**実装完了 = コード生成 + 全AC検証パス + L3ドキュメント更新（チェック・検証記録・status）までを含む。Phase 6 完了前にスキルを終了してはならない。**

## コード生成時の原則

<avoid_over_engineering>
- L3に書かれていない機能を追加しない
- 「念のため」のエラーハンドリングを過剰に入れない
- 既存コードのパターンに合わせる（新しいパターンを導入しない）
- 最小限の実装から始める
- 実装が1つしかないインターフェースを作らない（テスト差し替え用の外部依存のみ例外）
- 1-2箇所からしか呼ばれず外部公開しない処理を関数に切り出さない
- L2の設計方針（ファイル粒度）に従う
- Phase 0 の確認質問は本当に実装を左右する未解決点だけに絞る（質問のための質問をしない）
</avoid_over_engineering>

## 引数

- `$ARGUMENTS` (必須): 対象ID
  - **PH-xxxx**: フェーズID → フェーズ内の全機能を順番に実装
  - **F-xxxx**: 機能ID → 特定機能のみ実装

### 使用例

```
/gen-code PH-0001                 # フェーズ全体を実装
/gen-code F-0001                  # 特定機能のみ実装
```

## 前提条件

- L3 フェーズドキュメントが存在すること
- プロジェクト設定ファイルが存在すること（package.json, pyproject.toml 等）
  - **例外: PH-0000（準備フェーズ）の実装時は不要**（それを作るのが PH-0000。検出できなくてもユーザーに確認せず先へ進む）

### L3 の2形式への対応（重要）

L3 フェーズは**インライン1ファイル**（`PH-xxxx_*.md`）と**フォルダ形式**（`PH-xxxx_*/` に `_phase.md` + `F-xxxx_*.md`。reshape-l3 で split 済み）の2形式がある。フォルダ形式では書き込み先が分かれる:

| 更新対象 | インライン形式 | フォルダ形式 |
|---------|--------------|-------------|
| AC のチェック `[x]` | PH ファイル | 該当 `F-xxxx_*.md` |
| frontmatter `status` / `updated` | PH ファイル | `_phase.md` |
| 検証記録・Exit Criteria・完了サマリ | PH ファイル | `_phase.md` |

## 実行フロー

### Phase 0: 実装前の確認（clarify・条件付き）

対象の L3（該当 F の AC・対応 REQ）と L2 の関連箇所を確認し、**以下に該当する場合のみ**ユーザーに質問する（最大3〜5問、まとめて1回で）:

- 対象 F の AC・対応 REQ・L2 の関連節に `<!-- TODO: 要確認 -->` が残っている
- AC 同士、または AC と L2 の「確認済みの前提」が矛盾している
- 対応 REQ が存在しない（→ 実装を止めて gen-l3 の見直しを提案）
- AC の検証に必要な**外部手段が不足**している（外部 API の認証情報・テスト環境・アクセス権等。特にスパイク F で発生しやすい）

**該当がなければ質問せず、即 Phase 1 に進む**（「わからなければ TODO で進む」原則は生成時のもの。実装直前は例外的に解消のチャンスとする）。
回答で解消した内容は該当レイヤー（L1/L2/L3）に反映してから実装に入る。

**事前確認**: 対象 PH の「事前確認」節に未チェック項目がある場合、実装に入る前にその確認作業を実行する。判明した事実を L2「確認済みの前提」に出所付きで記録し、対応する `（未確認…）` 印を外し、事前確認のチェックを付ける。確認の結果、前提が崩れていたら実装に入らず L2/L3 の見直しを提案する。

### Phase 1: コンテキスト収集

1. **L3ファイル特定**: Glob で `docs/l3_phases/**/*.md` を検索（`_archive/` は除外）
   - PH-ID指定時: 該当フェーズファイル、またはフォルダ形式なら `_phase.md` と全 `F-*.md` を読み込み
   - F-ID指定時: 該当機能を含むフェーズファイル、またはフォルダ形式なら該当 `F-xxxx_*.md` と `_phase.md` を読み込み
2. L3 ドキュメントを読み込む
3. **frontmatter の status を `in_progress` に更新**（`planned` の場合。フォルダ形式では `_phase.md`）
4. **プロジェクト設定を自動検出**:
   - `package.json` あり → `npm test`, `npm run lint`
   - `pyproject.toml` あり → `pytest`, `ruff check`
   - `go.mod` あり → `go test ./...`, `golangci-lint run`
   - 検出できない場合 → ユーザーに確認（PH-0000 実装時は前提条件の例外どおり確認せず進む）
5. **L2 確認**: `docs/l2_foundation/foundation.md` から技術スタックを把握
   - 「アーキテクチャ > 設計方針」から採用パターン・ファイル粒度を取得
   - 「テスト・検証戦略」があれば、テストコマンド・検証ツールを取得
   - 「確認済みの前提」があれば、実装の前提として尊重する
   - `docs/l2_foundation/features/<機能名>.md`（機能契約）が対象 F に存在すれば読み、**「やらないこと」を契約として遵守する**（違反しそうな実装はユーザーに確認）
   - **L2 の分離ファイルは実装対象に関連するものだけ読む**（存在する場合のみ）:
     - 対象 F/AC が画面・導線・表示に触れる → `docs/l2_foundation/interface.md`
     - 永続化・データ変更に触れる → `docs/l2_foundation/data.md`
     - **両方に触れる機能（フォーム・API で永続化・フルスタック縦切り等）は両方読む**
     - 迷ったら依存グラフで決定的に絞り込む: `python3 "${CLAUDE_SKILL_DIR}/../../scripts/doc_graph.py" --focus F-xxxx` が「読むべき文書」の最小集合を返す（ID 参照から導出。無関係な分離ファイルは読まない）
6. **既存コード確認**: Glob/Grep で機能名・対応 REQ に関連する実装/テストファイルを検索
   - 対象 F を実装したとみられる既存ファイルがある場合 → **再生成モード**へ（パスの確定は Phase 3 と同じ基準: 既存コードの配置パターンから推測）

## 再生成モード（既存コードがある場合）

既存の実装/テストファイルがある場合は**再生成モード**で動作する。

### 再生成時の確認

```markdown
既存コードが見つかりました:
- テスト: tests/features/xxx.test.ts
- 実装: src/features/xxx.ts

どのように進めますか？
1. **全て再生成**: 既存を破棄し、L3から新規生成
2. **テストのみ再生成**: 実装は維持、テストを更新
3. **実装のみ再生成**: テストは維持、実装を更新
4. **差分確認**: L3との差分を表示してから判断
5. **キャンセル**: 何もしない
```

### Phase 2: 実装計画の確認

L3 から以下を抽出し、ユーザーに確認:

```markdown
## 実装計画

**対象**: [フェーズ名 / 機能名]
**検出した環境**: [package.json / pyproject.toml / etc.]

### 生成予定ファイル

| 種別 | パス | 説明 |
|------|------|------|
| テスト | tests/... | [概要] |
| 実装 | src/... | [概要] |

### 受け入れ条件 → テストケース

| AC | テストケース | 検証手段 |
|----|-------------|---------|
| AC-1 | [テスト概要] | テスト |
| AC-2 | [テスト概要] | コマンド実行 |

（AC-n は当該 F 内の記載順による**レポート表示用の呼称**。L3 ドキュメントには書かない）
（L3に `- 検証:` 行がないACはデフォルト「テスト」として扱う）
（`目視確認` のACがあれば、スナップショットテスト・DOMアサーション等で自動化できないか提案する）

### ファイル粒度チェック
L2の設計方針に照らして、生成予定ファイル数が適切か確認する。

この計画で進めますか？ (yes/no/修正)
```

### Phase 3: テスト生成

**テスト型 AC が0件の F はこのフェーズをスキップ**し、Phase 4（またはコマンド検証のみなら Phase 5）へ進む（環境構築・Lint 設定・スパイク等、PH-0000 系の F で該当しやすい。テストを無理に作らない）。

<thinking_process>
ファイルパス決定の判断基準:

1. **既存コードのパターンは？**
   - Glob で類似ファイルを検索し、配置パターンを推測
   - テストの配置: `tests/`, `__tests__/`, `*_test.py` 等

2. **インターフェース種別は？**
   - API → `src/api/`, `tests/api/`
   - UI → `src/components/`, `tests/components/`
   - CLI → `src/cli/`, `tests/cli/`
</thinking_process>

1. **ファイルパス決定**: 既存コードのパターンから決定
2. 受け入れ条件（AC）からテストコードを生成
3. 自動検出したテストツールを使用（jest, pytest 等）

**テスト生成の原則**:
- 受け入れ条件を忠実にテスト化
- 境界値・異常系も含める（L3に記載がある場合）
- モック/スタブは最小限

### Phase 4: コード生成

1. L3 の受け入れ条件を満たす実装を生成
2. 既存コードのパターンに合わせる

**コード生成の原則**:
- L3 の受け入れ条件に厳密に従う
- 既存コードのエラー処理パターンに合わせる

### Phase 5: 検証ループ

1. **Lint実行** → 失敗時は自動修正（--fix）して再実行
2. **テスト実行** → 失敗時はエラー分析・修正して再実行
3. **コマンド検証**（ACに `検証: curl ...` 等がある場合）→ Bashで実行し出力を検証
4. **最大3回失敗で中断**（circuit-breaker）

**検証手段別の処理**:

| 検証手段 | 処理 | 自動チェック |
|---------|------|-------------|
| テスト | テストランナーで実行 | Yes |
| コマンド実行 | Bashで実行し期待出力と比較 | Yes |
| 目視確認 | 自動化を提案→不可なら最後にユーザーに委任 | 原則No |

**目視確認ACへの対応**:
- まずスナップショットテスト、DOMアサーション、スクリーンショット比較等で自動検証に置換できないか検討・提案する
- 自動化できた場合: L3の `検証:` 行を自動検証手段に書き換え、テストを実行
- どうしても不可の場合のみ: ユーザーに確認を委任し、ACは未チェックのまま残す
- **後日ユーザーから「目視確認した」と報告を受けたら**: 該当 AC を `[x]` にし、検証記録の PARTIAL を `PASS（目視、YYYY-MM-DD）` に更新、全 F PASS なら status を `done` にする（archive-l3 のゲートでも同じ更新ができる）

**実装中に外部の事実が判明した場合**（例: ライブラリの制約、APIの実挙動）:
- その事実を L2「確認済みの前提」に追記する（出所付き）。L3 に書くのは自分のコードの検証結果だけ。実証ログが長くなる場合は `l2_foundation/validation/<topic>.md` に詳細を分離し、前提には結論1行＋参照を書く
- 判明した事実に対応する L2「設計判断の記録」の `（未確認…）` 印（`（未確認・PH-xxxx で検証）` 等）があれば**外す**（印の除去はスパイク AC が要求する正規の操作であり、「L3 に書かれていない編集」には当たらない）
- 検証の結果**前提が崩れた**場合:
  - **スパイク F（技術前提の事実検証）では、前提の不成立を確認することも検証の成果**。検証記録に `PASS（前提不成立を確認、YYYY-MM-DD）` と記録して正常終了し、L2 の技術選定・設計と以後のフェーズ計画の見直しをユーザーに提案する（実装フェーズには進まない）
  - 通常 F の実装中に崩れた場合: 実装を中断し、L2 の見直しをユーザーに提案する

**検証ループの原則**:
- 各反復でエラー内容を分析し、異なるアプローチを試す
- 同じエラーが続く場合は早期中断

**完了ゲート（Phase 6 に進む前の必須確認）**:
- [ ] 全テストがパスしている
- [ ] コマンド検証が全てパスしている（該当ACがある場合）
- 上記を満たさない限り Phase 6 に進まない（circuit-breaker で中断した場合は失敗として終了）

### Phase 6: L3 更新と証跡記録（必須・省略不可）

**このフェーズはコマンド完了の必須条件。Phase 5 をパスした場合、必ず以下を全て実行する。**

実装完了後、L3 フェーズドキュメントを更新（**フォルダ形式では前提条件の表に従い、AC は `F-xxxx_*.md`、status・検証記録・Exit Criteria は `_phase.md` に書く**）:

1. **L3ファイルを再読み込み**して最新状態を取得
2. **受け入れ条件を1件ずつ検証結果と照合**:
   - テスト検証AC: 対応テストがパスしていれば `[x]` マーク
   - コマンド検証AC: 実行結果が期待通りなら `[x]` マーク
   - 目視確認AC（自動化に置換できなかった場合のみ）: 未チェックで残す
   - **AC 行・`検証:` 行には日付や結果を書き足さない**（Plan は Plan のまま保つ）
3. **「検証記録」セクションに事後証跡を追記**（F 単位・日付付き）:
   ```markdown
   ## 検証記録
   - F-0001: PASS（テスト6件・コマンド検証1件、2026-07-03）
   - F-0002: PASS（テスト4件、2026-07-03）
   ```
   一部のACが未チェックの F は `PARTIAL（未チェック: 目視確認「レイアウト崩れがない」）` のように**条件の要約**で記録する（AC-n の扱いは Phase 2 の注記どおり）
4. **Exit Criteria**: 該当項目に `[x]` マーク
5. **frontmatter 更新**: フェーズ内の全 F が PASS になったら `status: done`、`updated` を当日に
6. **最終確認レポートを出力**:

| AC | 検証手段 | 結果 | L3更新 |
|----|---------|------|--------|
| F-0001 AC-1 | テスト | ✓ パス | [x] 済 |
| F-0001 AC-2 | コマンド | ✓ パス | [x] 済 |

**L3ファイルの更新を確認するまでスキルを完了としない。**

## 失敗時の出力

- エラー内容（最後のエラーログ）
- 試行した修正内容（3回分）
- 推奨アクション（L3見直し、手動デバッグ検討）

（成功時の報告は「完了後の案内」に一本化）

## 注意事項

- **既存コードの上書き確認**: 対象 F の既存実装がある場合は再生成モードで対話確認
- **部分成功は認めない**: 全テスト通過 + 全AC検証 + L3更新が完了条件。**唯一の例外は自動化不能な目視確認 AC**（PARTIAL 記録＋理由の報告で正常終了してよい）
- **Phase 6 スキップ禁止**: コード生成・テストパス後にL3更新せず終了することは許容しない
- **用語注意**: 本スキル内の Phase 0〜6 は作業工程の呼称であり、Tri-SSD のフェーズ（PH-xxxx）とは別物

## 完了後の案内

- 生成ファイル一覧を報告
- テスト結果サマリを報告
- **AC検証結果レポート**（Phase 6 の最終確認レポート）を報告
- 未チェックACがある場合はその理由を報告（目視確認で自動化不可等）
- フェーズの全 F が PASS したら `/archive-l3 PH-xxxx` で完了処理を案内（フェーズ単位）

---

## エラーケース

| ケース | 対応 |
|--------|------|
| L3 フェーズドキュメントが存在しない | エラー: 「L3 が見つかりません。`/gen-l3` を先に実行してください」 |
| 指定した PH-ID / F-ID が見つからない | エラー: 「指定された ID が見つかりません」 |
| 検証ループが3回失敗（circuit-breaker） | 失敗として終了し、「失敗時の出力」を報告 |