dev-impl

Dev Impl

TDDをガードレールとして、テストを先に書いてから実装するコアワークフロー。タスクファイルに基づく通常モードと、Plan不要の軽量クイックモードの2つの実行モードを持つ。

前提知識

dev-*スキルフロー内の位置

dev-context → dev-plan → [dev-impl] → dev-verify
                                  ↘ dev-debug (失敗時)

実行モード

品質優先のプライオリティ

品質 > 速度 > トークン消費 の順で判断する。

ワークフロー: 通常モード

/dev-impl <plan-name> <task-id> で実行。

Step 1: コンテキスト構築（最小限）

インターフェースファーストで必要最小限のファイルだけ読み込む:

優先順位:
1. docs/dev/context.md（プロジェクト全体像）
2. タスクファイル（インターフェース定義・テスト方針）
3. 関連する型定義ファイル ← 必要時のみ
4. 関連する既存テストファイル（パターン参考）← 必要時のみ
5. 実装ファイル（関連関数のみ）← 必要時のみ

TodoWrite でタスク進捗のトラッキングを開始する。

Step 2: テストケース生成（Red）

タスクファイルの Test Strategy に基づきテストコードを生成する:

1. 既存テストファイルのパターン（context.mdの規約）に合わせる
2. タスクのインターフェース定義に基づくテストケースを記述する
3. テスト実行コマンド（context.md から取得）でテストを実行する
4. 失敗を確認する（Red状態）

テストが先に通ってしまう場合は、要件やテストの妥当性を再確認する。

Step 3: 実装（Green）

テストを通す最小限の実装を生成する:

1. インターフェース定義に準拠したコードを書く
2. Intent コメントを付与する（後述の「Intent コメントルール」に従う）
3. テスト実行 → 成功を確認する（Green状態）
4. 失敗した場合はエラーを分析し修正する（最大3サイクル）
5. 3サイクルで解決しない場合は /dev-debug の使用を案内する

Step 4: リファクタリング + 品質チェック

テストがGreenの状態で以下を実行する:

4a. 500行ルール（厳密適用）

関連するすべてのファイルの行数を Bash で確認する（絶対パスを使用）:

wc -l "$(git rev-parse --show-toplevel)/<ファイルの相対パス>"

500行を超えるファイルがある場合:

• 責務の境界で分割する（Single Responsibility Principle）
• テストファイルも対応して分割する
• インポート/エクスポートの整合性を維持する
• 分割後にテストを再実行する

4b. セキュリティチェック

実装コードを確認し、以下の問題がないか検証する:

• インジェクション（SQL, コマンド, XSS）
• 認証・認可チェックの漏れ
• 機密情報のログ出力・エラーメッセージでの露出
• ユーザー入力のバリデーション不足

4c. パフォーマンスチェック

• N+1問題（ループ内のDB/APIクエリ）
• メモリリーク（イベントリスナー未解除、クロージャ参照保持）
• 非効率なアルゴリズム（O(n^2)以上で改善可能な箇所）

4d. コード品質

• 重複コードの排除
• 命名の改善
• 不要なコメントの削除

4e. カバレッジチェック

1. docs/dev/context.md の Test Framework セクションから Coverage Threshold を取得する
2. タスクファイルの Files セクションから対象パッケージを特定する
3. パッケージごとにカバレッジを計測する（Coverage Command をパッケージ単位で実行）
4. [no test files] は 0% として扱う
5. 閾値未達時: テストを追加し再計測する（最大3サイクル）
6. 3サイクル後も未達: 🟡 として報告し続行する（ブロッキングにしない）

テスト再実行 → 成功維持を確認する。

Step 5: 信号機レポート + 完了処理

確信度レポートの出力

実装した各ファイルに確信度を付与し、ユーザーに報告する:

## dev-impl 確信度レポート

### カバレッジ結果
| パッケージ | カバレッジ | 閾値 | 結果 |
|-----------|----------|------|------|
| internal/handler | 85.2% | 80% | OK |

### 🔵 前工程指示（レビュー低優先）
- [ファイル名](パス) — 既存パターン準拠

### 🟡 妥当な推測（要確認）
- [ファイル名](パス) — [確認すべき点]

### 🔴 AI推論補完（人間の確認必須）
- [ファイル名](パス) — [判断が必要な理由]

完了処理

1. タスクファイルの status を done に更新する
2. TodoWrite を更新する

Step 6: Docker クリーンアップ

プロジェクトルートに docker-compose.yml または docker-compose.yaml が存在するか確認する。存在する場合:

1. docker compose down を実行してコンテナを停止する
2. 停止に失敗した場合はユーザーに報告する（ブロッキングにしない）

ワークフロー: クイックモード

/dev-impl "修正指示" で実行（Plan名なし）。

用途

• テストケースの微修正 + 実装の調整
• 小さなバグ修正
• 既存テストへのケース追加
• 軽量なリファクタリング

フロー

1. docs/dev/context.md を読み込む（あれば）
2. Explore サブエージェント（haiku）で関連ファイルを探索する
3. テスト修正 → 実装修正（またはその逆）
4. テスト実行で検証する
5. 500行ルールのチェック
6. 信号機レポートを簡潔に出力する
7. Docker クリーンアップ（Step 6 と同様）

複雑度に応じた戦略

タスクファイルの estimated_complexity に応じて戦略を切り替える。詳細は references/impl-strategies.md を参照。

サブエージェント戦略

Intent コメントルール

生成するソースコードの各関数・メソッドに、設計判断の理由を示す Intent コメントを付与する。

信号機システム（🔵🟡🔴）

• 🔵 前工程指示: タスクファイル・plan.md・context.md で明示的に指示されている設計判断
• 🟡 妥当な推測: 指示された内容から推論した妥当な設計判断（ベストプラクティス準拠等）
• 🔴 AI推論補完: 前工程に根拠がなくAIが推論で補完した設計判断

コメント形式

言語のコメント構文に従い、関数・メソッドの直前に記述する:

// 🔵 Intent: タスクファイルで指定された TodoRepository インターフェースを実装。
//    RETURNING 句で INSERT と ID 取得を1クエリで完結させる。
func (r *PostgresTodoRepository) Create(ctx context.Context, todo *model.Todo) error {

// 🟡 Intent: context.md のエラーハンドリング規約に準じて fmt.Errorf でラップ。
//    リポジトリ層のエラーをサービス層で識別可能にするため。
func (s *TodoService) GetByID(ctx context.Context, id string) (*model.Todo, error) {

// 🔴 Intent: ページネーションのデフォルト値。前工程に指定なし。
//    一般的な Web API の慣習に基づき limit=20 を採用。
const defaultPageSize = 20

付与ルール

• すべての public 関数・メソッド に Intent コメントを付与する
• private 関数は設計判断がある場合のみ付与する（自明な処理は省略可）
• テストコードには付与しない
• 1コメント = 1-2行で簡潔に。冗長な説明は避ける
• 既存コードに追記する場合、既存の Intent コメントを維持する

ルール・制約

• テストを先に書く。テストが通る前に次のステップに進まない
• すべてのファイルは 500行以内。超過時はリファクタリングで分割する
• タスクファイルの dependencies に含まれるタスクがすべて done であることを確認してから開始する
• context.md が存在しない場合、先に /dev-context を案内する
• 通常モードでタスクファイルが存在しない場合、/dev-plan を案内する
• テスト実行コマンドは context.md から取得する
• セキュリティ・パフォーマンス問題の 🔴 は修正してから完了する
• Bash コマンドはプロジェクトルートの 絶対パス を使用する（$(git rev-parse --show-toplevel) でルートを取得）

追加リソース

リファレンスファイル

• references/impl-strategies.md — 複雑度別の実装戦略、インターフェースファースト読み込みの詳細、バッチモードの適用基準