CTS-KB
AI駆動開発 📚 シリーズ 4/9

実装・完了編：TodoWrite 連携と tasklist.md 同時更新、アーカイブ運用

⏱ 約 6 分で読めます
#ステアリング駆動開発 #TodoWrite #TDD #Claude Code #アーカイブ
ステアリング作成編：M/L 規模のドキュメント設計と TDD タスク分解 コンテキスト設計編：AI に渡すコンテキストを最適化する skills と prepare-context

🛠️ ドキュメントだけ書いて実装が崩れる問題

ステアリングを作成しただけでは実装品質は保証されません。CTS-EC で繰り返し起きた失敗は次の 3 つです。

  1. tasklist.md が放置される（TodoWrite だけ更新して満足する）
  2. Phase 完了時の検証をスキップして次フェーズに進み、バグを持ち越す
  3. 完了ステアリングがアクティブに残り続ける（ACTIVE.md と整合しない）

実装・完了フェーズは「ドキュメントと現実を同期し続ける」運用規律そのものです。本記事ではシリーズ第 4 回として、Phase 0 から /steering-complete までの実装ワークフローを解説します。

🔄 TodoWrite と tasklist.md は「同時更新」が必須

最も重要なルール：タスク完了時は TodoWrite と tasklist.md を同時に Edit する。片方だけの更新は禁止です。

// 1. TodoWrite 更新
TodoWrite([
  {"content": "1.1a: OAuth テスト", "status": "completed", ...},
  {"content": "1.1b: OAuth 実装",   "status": "in_progress", ...},
])

// 2. tasklist.md 更新（必須・同時）
Edit(
  file_path: ".steering/20260420-yahoo-oauth/tasklist.md",
  old_string: "| 1.1a | OAuth テスト | ❌ |",
  new_string: "| 1.1a | OAuth テスト | ✅ |"
)

なぜ両方必要か

ドキュメント役割寿命
TodoWriteセッション内の補助メモ、in_progress 可視化セッション内のみ
tasklist.md正式ドキュメント、/resume や振り返りの入力ステアリング完了まで

TodoWrite だけ更新すると、セッションが切れた瞬間に進捗が消えます。tasklist.md だけ更新すると、セッション内の in_progress が見えずタスク切替ミスが起こります。

🧩 実装フロー：Phase 0 → Phase N → 完了

実装は以下の順序で進みます。Phase 0 は固定です。

Phase 0: 参照実装レビュー
   ↓
Phase 1: 実装ループ（タスク単位で tasklist + TodoWrite 同時更新）
   ↓
Phase 1 検証（/test + /check-test-quality + implementation-validator）
   ↓
Phase 2: 実装ループ
   ↓
Phase 2 検証
   ↓
最終検証 → /steering-complete

Phase 0 の 3 タスクがすべて ✅ になるまで Phase 1 の実装コードを書きません。

🧪 Phase 完了時の 3 種検証ゲート

Phase の最終タスクを ✅ にしたら、次 Phase に進む前に 3 つの検証を必ず回します。

#検証サブエージェント/コマンド目的
1テスト実行/test（test-runner 経由）合格判定
2テスト品質/check-test-quality（test-quality-checker 経由）型別網羅性・分岐カバレッジ
3実装品質implementation-validator7 観点 + TDD/DDD 準拠

サブエージェント経由にする理由は、 メインエージェントでテスト出力を直接読まないため です。コンテキスト消費を避けつつ、失敗時のみメインに戻します。

実装完全性チェックも必須

検証の一環として、変更ファイルに対し以下の grep を必ず実行します。

Grep "TODO|FIXME|HACK|TBD"                    変更対象
Grep "NotImplementedException|NotImplementedError"  変更対象

0 件が Phase 完了条件です。1 件でもあれば修正してから次 Phase へ進みます。「方向性は合っている」で PASS にするのは禁止です。

📥 フェーズ検証記録テーブル

tasklist.md の先頭に以下の表を置き、検証結果を記録します。

Phase/testvalidator完了日
Phase 0--2026-04-18
Phase 1✅ 全パス✅ PASS2026-04-20
Phase 2⚠️ 1 件失敗❌ FAIL-

/resume 時にこの表を確認し、未実施の検証があれば提案します。

📦 フェーズ完了時のアーカイブで tasklist.md を軽量化

ステアリングが進むと tasklist.md が肥大化し、/resume 時のコンテキスト消費が増えます。Phase 完了時に tasklist-archive.md へ詳細を移動し、tasklist.md には進捗サマリー 1 行だけ残します。

## 進捗サマリー

| Phase   | 内容               | 状態      | 完了   |
| ------- | ------------------ | --------- | ------ |
| Phase 1 | OAuth コア実装     | ✅ 完了   | 10/10  |
| Phase 2 | 店舗連携・移行     | 🟡 進行中 | 3/8    |

> 詳細: [tasklist-archive.md](./tasklist-archive.md)

tasklist.md のサイズ目安は 3 KB 以下。超えたら即アーカイブ対象です。

📰 進捗報告は progress-reports/ に月次で

CTS-EC では docs/progress-reports/YYYY-MM-DD.md にステークホルダー向けの進捗報告を 月 2 回ペース で残しています。業務課題・対象件数・完了率を明文化することで、ステアリングの成果がそのまま顧客価値として可視化されます。

progress-reports/
├── 2026-01-26.md
├── 2026-02-06.md
├── 2026-02-18.md
├── 2026-03-13.md
├── 2026-03-20.md
├── 2026-04-03.md
└── 2026-04-15.md

テンプレートは .claude/templates/progress-template.md にあります。

🏁 /steering-complete の 9 ステップ

全タスク ✅ + 最終検証 PASS になったら /steering-complete を実行します。

Step内容
1.steering/ACTIVE.md から対象作業を特定
2tasklist.md 最終確認（未完了なら理由を記録）
3完了条件チェック（テスト合格 / テスト品質 / 受入テスト突合）
4git mv .steering/YYYYMMDD-xx/ → .steering/archive/YYYYMMDD-xx/
5roadmap.md 更新（該当フェーズのみ）
6roadmap-archive.md へ重要な完了タスクを追記
7chore(steering): complete xxx → archive/ で Git コミット
8Serena メモリ保存候補の提示（半自動）
9完了レポート作成

受入テスト消化ゲート

Step 3 では requirements.md の AT-*（受入テストシナリオ）と実装テストを突合 します。未消化シナリオがあれば完了を保留します。これがないと「テストは通っているが受入条件を満たさない」状態が放置されます。

🗄️ アーカイブ運用：ARCHIVE.md を更新する

git mv 後、.steering/ARCHIVE.md の該当カテゴリテーブルに行を追記します。

| [20260420-yahoo-oauth](archive/20260420-yahoo-oauth/) | Yahoo OAuth 移行 | !MR123 | 2026-04-30 |

カテゴリ判定は「モール商品登録 / DDD/SOLID / マルチテナンシー / 認証・認可 / EGAZO / AI マッピング SAGA / 基盤」から選びます。既存に合わなければ新カテゴリを作ります。

🧠 Serena メモリへの昇華判断

decision.md や実装から得た学びで プロジェクト全体で再利用可能なもの は Serena メモリに保存します。個別 ADR と違い、パターン・原則・プロセスを残すのが目的です。

保存すべき保存不要
パターン（双方向参照、Upsert 冪等性）タスク固有の詳細（API エンドポイント名）
原則（全登録→後で確認）一時的な判断（しきい値の具体値）
プロセス（データ分析先行）個別の ADR そのもの
失敗と対策進捗状況

命名規則：

  • ドメインパターン → [ドメイン名]-domain-patterns
  • トラブルシューティング → [技術領域]-troubleshooting
  • アーキテクチャ原則 → architecture-principles

⚠️ 実装・完了フェーズでやってはいけないこと

  • TodoWrite だけ更新して tasklist.md を放置する
  • 「後でまとめて更新」（リアルタイム更新が必須）
  • Phase 完了時の 3 種検証をスキップして次 Phase へ進む
  • TODO|FIXME|NotImplementedException が残ったまま Phase 完了にする
  • 未完了タスクを残して振り返りを書く
  • ACTIVE.md から削除せずに次の /steering を開始する

📚 シリーズ記事

#タイトル内容
1概要ステアリング駆動開発の全体像
2壁打ち・規模判定編壁打ちの進め方、ADR の書き方、規模判定の基準
3ステアリング作成編M/L 規模のドキュメント作成、TDD タスク分解
4実装・完了編（本記事）TodoWrite 連携、進捗管理、アーカイブ運用
5コンテキスト設計編AI に渡すコンテキストの最適化、skills 設計
6品質ゲート編doc-reviewer、テスト品質チェック、受入テスト
7Claude Code ベストプラクティスCLAUDE.md 設計、hooks、commands、rules、skills
8Agent Teams 編agents 定義、チーム構成、マルチエージェント協調
9Remote Control 編スマホ・Web から CLI セッションを操る席拘束からの解放

🔗 関連記事

📖 関連用語

  • ADR — 実装中に発生した設計判断を decision.md に残し、/steering-complete で昇華
  • ハルシネーション — TODO / stub 残りを検出する実装完全性チェックで防ぐ失敗モード