long-run-implement

Long-Run Implement

大きな実装タスクを TODO ファイル駆動 で段階的に進め、 各段階をサブエージェントがレビューするスキル。

コンセプト

ユーザーのタスク
  → 高レベル TODO 作成（全体の見通し）
  → 高レベル TODO ごとに:
      → 細かい TODO に分解
      → 各 TODO を実装
      → 【レビューゲート】サブエージェントが検証
      → 問題・不足があれば TODO 追加
  → 全 TODO 完了 → 最終検証

team-plan/team-implement との違い:

• 並列ではなく逐次: 1人のメインエージェントが順番に実装する
• TODO が育つ: 実装中に発見した追加作業を随時 TODO に追加する
• レビューゲート: 高レベル TODO の塊が終わるごとにサブエージェントが品質チェック

---

Step 1: TODO ディレクトリの作成

1a: 作業ディレクトリの準備

親ディレクトリ名: {YYYY-MM-DD}-{タスク名のslug}（日付+タスク内容）

.claude/long-run-implement/{YYYY-MM-DD}-{task-slug}/
├── todo.md                    ← インデックス（全体進捗・タスク一覧）
├── review-log.md              ← レビュー結果の蓄積
├── 01-{slug}/
│   └── tasks.md               ← 高レベル TODO 1 の細かいタスク
├── 02-{slug}/
│   └── tasks.md               ← 高レベル TODO 2 の細かいタスク
├── 03-{slug}/
│   └── tasks.md
...

ポイント:

• 各高レベル TODO は 独立したディレクトリ を持つ
• ディレクトリ名は {連番}-{内容のslug}（例: 01-scaffold, 02-schema）
• 細かいタスクは各ディレクトリ内の tasks.md に記載
• todo.md はインデックス（全体の俯瞰）のみ。詳細は各 tasks.md に

1b: 高レベル TODO の作成

ユーザーのタスクを分析し、高レベル TODO を作成する。 各高レベル TODO は「実装の大きな塊」を表す。

todo.md（インデックス）のフォーマット:

# TODO: {タスク名}

> 元のタスク: {ユーザーの指示原文}

## 進捗サマリー
- 総タスク数: X
- 完了: 0
- レビュー済み: 0

## タスク一覧

| # | ディレクトリ | タスク | 状態 |
|---|------------|--------|------|
| 1 | `01-{slug}/` | {タスク名} | [ ] |
| 2 | `02-{slug}/` | {タスク名} | [ ] |
...

## 依存順序

{タスク間の依存関係を記載}

各ディレクトリの tasks.md のフォーマット:

# {連番}: {高レベル TODO タイトル}

**状態**: [ ] 未着手
**概要**: {何をするか}
**依存**: {前提となるタスク}

## タスク

- [ ] {連番}-1: {具体的な変更内容}（{ファイルパス}）
- [ ] {連番}-2: {具体的な変更内容}（{ファイルパス}）
...

## 完了条件
- {このタスクが完了したと言える基準}

1c: ユーザーへの確認

高レベル TODO を作成したら、ユーザーに提示して確認を取る。 AskUserQuestion で「この TODO で進めてよいか」を確認する。

重要: ユーザーが「もっと細かく」「この部分が足りない」と言ったら修正する。 ユーザーが OK を出すまで実装を開始しない。

---

Step 2: 高レベル TODO の細分化

承認された高レベル TODO を上から順番に処理する。

2a: 細かい TODO への分解

高レベル TODO に着手する前に、まず対象ファイルを Read して現状を把握する。 その上で該当ディレクトリの tasks.md に細かい TODO を記載する。

## タスク

- [ ] 1-1: {具体的な変更内容}（{ファイルパス}）
- [ ] 1-2: {具体的な変更内容}（{ファイルパス}）
- [ ] 1-3: {具体的な変更内容}（{ファイルパス}）

細かい TODO の粒度:

• 1つの TODO = 1つの明確な変更（関数の追加、型定義の変更、etc.）
• 各 TODO は 5〜30 行程度の変更に収まるのが理想
• 不確実な部分は「調査: {何を調べるか}」として TODO に入れてよい

2b: tasks.md と todo.md を更新

1. 該当ディレクトリの tasks.md に細かい TODO を書き込む
2. todo.md（インデックス）の該当タスクの状態を [~] に変更する

---

Step 3: 実装

細かい TODO を上から順番に実装する。

実装ルール

1. 実装前に Read: Edit 対象のファイルは必ず直前に Read する
2. 1 TODO ずつ実装: 複数の TODO をまとめて実装しない
3. 完了したら即チェック: 該当ディレクトリの tasks.md を [x] に更新
4. 発見した追加作業: 実装中に「これもやらないと」と気づいたら、即座に該当ディレクトリの tasks.md に追加 TODO として書く。[+] マーカーで「後から追加された」ことを示す
5. 困ったらメモ: 懸念や判断に迷った点は tasks.md にインラインコメントとして残す

TODO の状態遷移

[ ] 未着手
 ↓
[~] 作業中
 ↓
[x] 完了
 ↓ （レビュー指摘があれば）
[!] 要修正 → 修正 TODO を追加 → 修正後 [x]

[+] 後から追加された TODO（上記と同じ遷移をたどる）

実装中の todo.md 更新例

### 細かい TODO
- [x] 1-1: UserType に newField を追加（src/types.ts）
- [x] 1-2: createUser 関数で newField を処理（src/services/user.ts）
- [~] 1-3: UserForm コンポーネントに入力欄を追加（src/components/UserForm.tsx）
- [ ] 1-4: バリデーションロジックの追加（src/utils/validation.ts）
- [+] 1-5: 既存テストの修正が必要と判明（src/__tests__/user.test.ts）
  <!-- 1-2 実装中に既存テストが壊れることが分かった -->

---

Step 4: レビューゲート

高レベル TODO 内の全ての細かい TODO が完了したら、レビューゲートに入る。

4a: レビュー用サブエージェントの起動

Agent ツールを使ってレビューエージェントを起動する。

Agent(
  subagent_type: "long-run-implement:reviewer"
  prompt: "{レビュープロンプト}"
)

レビュープロンプトに含める情報:

• 該当ディレクトリの tasks.md の内容全体
• 変更したファイルの一覧とパス
• 元のタスクの説明（todo.md 冒頭の「元のタスク」）
• 特に確認してほしいポイント（懸念メモがあれば）

4b: レビューの観点

レビューエージェントは agents/reviewer.md の指示に従い、以下を検証する:

1. 完了性: TODO に書かれた全変更が実装されているか
2. 正確性: 変更がタスクの目的と合致しているか
3. 整合性: 変更したファイル間で矛盾がないか（型、import、API 呼び出し等）
4. 品質: 明らかなバグ、セキュリティ問題、パフォーマンス問題がないか
5. 副作用: 変更対象外のコードに意図しない影響がないか

4c: レビュー結果の処理

レビューエージェントは結果を返す。結果は以下のいずれか:

PASS（問題なし）:

• review-log.md にレビュー結果を追記
• 高レベル TODO の状態を [x] 完了 に更新
• 次の高レベル TODO に進む

FAIL（問題あり）:

• レビュー指摘を todo.md に修正 TODO として追加（[!] マーカー）
• 高レベル TODO の状態を [!] レビュー指摘あり に更新
• 修正 TODO を実装（Step 3 に戻る）
• 全修正 TODO 完了後、再度レビューゲート（Step 4）に入る

### レビュー指摘 (2026-03-07)
- [!] 1-R1: createUser の型が UserType の新フィールドを反映していない（src/services/user.ts:45）
- [!] 1-R2: バリデーション関数に null チェックが必要（src/utils/validation.ts:12）

4d: レビューループの制限

同じ高レベル TODO に対するレビューは 最大 3 回 まで。 3 回目でも FAIL の場合、ユーザーに状況を報告して判断を仰ぐ。

---

Step 5: 進捗サマリーの更新

各高レベル TODO 完了後に todo.md の「進捗サマリー」を更新する。

## 進捗サマリー
- 総タスク数: 15 (+3 追加)
- 完了: 8
- レビュー済み: 2/4
- 現在: 3. API エンドポイントの実装

ユーザーに現在の進捗を簡潔に報告する（1〜2行）。

---

Step 6: 全 TODO 完了後の最終検証

全ての高レベル TODO が完了・レビュー済みになったら:

6a: ビルド＆テスト

CLAUDE.md やプロジェクト設定に検証コマンドがあれば実行する。 なければ一般的なコマンド（npm run build, npm test 等）を試す。

6b: 最終レポート

todo.md に最終セクションを追加:

---

## 完了レポート

### 変更ファイル一覧
| ファイル | 変更内容 |
|---------|---------|
| {パス} | {概要} |

### レビュー結果サマリー
- レビュー回数: N 回
- 指摘事項: M 件（全て解決済み）

### ビルド＆テスト
- {結果}

### 注意事項
- {実装中に気づいた懸念点}

6c: ユーザーへの報告

最終レポートの要約をユーザーに伝える。

---

注意事項

TODO ディレクトリが真実の源泉

• 全体の進捗は todo.md（インデックス）で俯瞰
• 各タスクの詳細は {NN}-{slug}/tasks.md に記録
• 「何をやったか」「何が残っているか」は todo.md + 各 tasks.md を見れば分かる状態を維持する
• tasks.md を更新し忘れない。実装の前後で必ず更新する

実装の順序は柔軟に

• 基本は上から順番だが、依存関係で順序を変えるのは OK
• 変更した場合は todo.md にコメントで理由を残す

サブエージェントの使い方

• レビューには必ず Agent ツールを使う（自分でレビューしない）
• レビューエージェントは変更ファイルを直接 Read して検証する
• レビュー結果が返ってきたら、メインエージェントが todo.md を更新する

コスト意識

• 小さなタスク（1つの高レベル TODO で全体が終わる程度）にはこのスキルは不要
• 高レベル TODO が 2 個以下になりそうなら、スキルを使わず直接実装した方が速い