long-run-implement

name

long-run-implement

description

エージェントを長時間稼働させて大きな実装タスクを完遂するためのスキル。 TODO ファイル (.md) を管理しながら、高レベル TODO → 細かい TODO に分解 → 実装 → サブエージェントによるレビュー → 不足分の TODO 追加 のサイクルを回す。 コンテキストが大きくなっても TODO ファイルが状態の真実の源泉として機能するため、 長時間・大規模な変更でも迷子にならずに着実に完遂できる。 team-plan や team-implement とは異なり、1人のメインエージェントが逐次的に実装し、 各段階をレビューエージェントが品質検証する。 Use when: 大きな実装タスクを段階的に進めたい、エージェントに長時間任せたい、 実装中に TODO を追加しながら進めたい、各ステップの品質をサブエージェントにレビューさせたい、 長時間の実装を構造化したい、放置しても安心して任せられる実装フローが欲しい。 Triggers: "long-run", "段階的に実装", "TODO駆動で実装", "大きな実装", "ステップバイステップで実装", "レビューしながら実装", "long run implement", "実装を進めて", "大規模実装", "iterative 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 個以下になりそうなら、スキルを使わず直接実装した方が速い