はじめに
本記事は「Context Engineering 完全入門」シリーズの補章 B です。本補章では、Claude Code が 2026 年に TODO ツールを TodoWrite/TodoRead(V1)から TaskCreate/TaskUpdate/TaskGet/TaskList(V2)へ大改修した事例を取り上げます。なぜこの判断をしたのか、何が問題で、どう解決したのかについて、改めて整理いたします。
本記事の目的は、この移行事例を単に紹介することではなく、「業界標準ツールの破壊的変更事例から、業務系エージェント開発に応用できる普遍的な教訓を得ること」 です。補章 A で扱った VS Code Copilot Chat が「シンプルさ重視の設計」だったのに対し、Claude Code V2 は「運用性重視の設計」を採用しています。両者を対比することで、業務系エージェントで何を参考にすべきかの判断軸が見えてきます。本記事では V1 の問題点を分析し、V2 の設計判断と移行戦略、そして業務系エージェント開発への応用について解説します。
前回：補章 A VS Code Copilot Chat 1.109 機能調査
次回：補章 C 業界研究の業務系翻訳ガイド📌 補章 B:Anthropic が 2026 年に Claude Code の TODO ツールを V1 → V2 へ大改修した経緯と教訓を解析します。SDK 移行・破壊的変更を経験する全てのエンジニアに役立つ視点 を提示します。
🗺️ 単独でも読めます:SDK 移行戦略の事例研究として、Claude Code に詳しくない方でもお読みいただけます。
📝 本記事は、生成 AI で作成した草案をベースに、筆者が加筆・修正し、技術的な正確性を確認した上で公開しています。
📝 本記事の要点
- 問題: なぜ Anthropic は TODO ツールを V1→V2 へ大改修したのか、業務系エージェント設計に何を活かせるか
- 解決: 段階的移行 + 本番テレメトリ駆動 + 最初から永続化前提 という 5 つの普遍的教訓
- 業務系への示唆: 第 7 回の C# 実装は V2 互換、さらに Nag Reminder / Recitation / イベントソーシング拡張で業務系必須要件(監査・分析)まで対応
破壊的変更を予定している SDK 開発者・アーキテクトには §4 の 5 つの教訓 が直接役立ちます。
🎯 本記事の対象者
- なぜ Anthropic がこの大改修を決断したのか知りたい
- 自社の AI SDK にも将来同じ移行が必要か判断したい
- 破壊的変更を最小コストで顧客に届ける方法を学びたい
- TODO ツール(第 7 回)が「なぜ V2 互換設計か」を理解したい
- 業務系エージェントで長時間タスク・監査要件・マルチプロセス共有に対応したい
- Microsoft / Anthropic / OpenAI の文化の違いを把握したい
1. 移行の背景
なぜこの移行事例が業務系エージェント開発者にとって重要か
Claude Code の V1 → V2 移行は、「個人利用ツール」から「業務利用対応ツール」への進化過程を可視化した貴重な事例 です。V1 の課題(インメモリのみ、操作粒度が粗い、マルチエージェント共有不可)は、業務系エージェントを本番運用する際に必ず直面する課題そのものです。
本節では、この移行事例を 業務系エージェント設計の教訓の宝庫 として位置付け、以下の 3 つの観点から解析します:
- V1 で顕在化した問題(§2):業務系エージェント設計で最初から回避すべきアンチパターン
- V2 の設計判断(§3):業務系必須要件(永続化・監査・並行制御)への対応
- 移行戦略の教訓(§4):将来の SDK 破壊的変更を最小コストで実施する方法
公式アナウンス
Claude Code Docs - Tools reference より:
"(訳) TypeScript Agent SDK 0.3.142 および Claude Code v2.1.142 以降、セッションでは
TodoWriteの代わりに、構造化された Task ツール群(TaskCreate、TaskUpdate、TaskGet、TaskList)が使用されます。"
タイムライン
この 1 年半のタイムラインからは、Anthropic が本番ユーザーの声を蓄積してから設計を検討し、後方互換モードを用意してから段階的にデフォルトを切り替えた ことがわかります。業務系 SaaS で破壊的変更を行う際の教科書的な移行プロセスとして参考になります。
2. TODOツール V1 の問題:なぜ作り直したか
本節の位置付け
本節では、V1 で顕在化した 3 つの問題を、業務系エージェント設計で最初から回避すべきアンチパターン として位置付けます。第 7 回で解説した「持続性・更新粒度・並行制御の 3 軸評価」で見ると、V1 は 3 軸すべてで問題を抱えていました。業務系エージェント設計では、これらの問題を PoC 段階から意識して回避すること が推奨されます。
問題 1:インメモリのみ(プロセス終了で消える)
「昨日の続きから」が不可能で、長時間タスクが事実上できない状態でした。これは第 7 回で扱った Plan Persistence 問題を インフラレベルで悪化させる 設計でした。
業務系エージェント開発者への教訓: セッション終了で進捗が失われる設計は、業務系では致命的です。特に 監査要件のあるシステム では、エージェントの実行履歴を後から追跡できないという問題も発生します。第 7 回の 3 軸評価の「持続性」に該当し、業務系では 最初からファイル永続化(または DB 保存)を組み込むこと が必須です。
問題 2:操作粒度が粗い
V1 の TodoWrite は 完全置換のみ でした。1 タスクを更新するために全リストを送信する必要があり、大量タスクでは毎回フルリスト送信になります。また、並行更新時の競合検出が困難で、「A さんが完了マーク中に B さんがタスクを追加すると片方が消える」という致命的なバグも発生していました。
業務系エージェント開発者への教訓: 完全置換方式は、トークン浪費と競合バグの二重リスク を抱えます。特にマルチテナント SaaS では、複数のエージェントプロセスが同時にタスクを操作するケースが多く、競合バグは重大なデータ損失につながります。第 7 回の 3 軸評価の「更新粒度」と「並行制御」に該当し、業務系では 個別タスク操作(Create/Update/Get)と全体取得(List)を分離する ことが必須です。
問題 3:マルチエージェント共有不可
サブエージェントが「親の TODO」を見ることができないため、第 5 回で扱った 並列サブエージェント実行 が TODO の文脈では機能しない設計でした。
業務系エージェント開発者への教訓: プロセス間で共有できない状態管理は、マイクロサービス化や水平スケーリング時に破綻 します。業務系エージェントを Kubernetes などのコンテナ環境で運用する場合、Pod 間で状態を共有する必要があるため、インメモリ設計はスケーラビリティの上限を最初から作り込んでしまいます。この問題は補章 C で扱う予定の Redis / DynamoDB 等のマネージドストレージ活用で解消できます。
3. V2 の設計判断
本節の位置付け
本節では、V2 で採用された 3 つの設計判断が、業務系必須要件(永続化・監査・並行制御・後方互換性)にどう対応しているか を解説します。特にイベントソーシングパターンは、業務系での監査要件対応において非常に重要な設計であり、そのまま業務系エージェントに応用できます。
4 つのツールへの分解
判断 1:単一責任原則(Single Responsibility)
各ツールが 1 つの操作のみ担当することで、トークン削減・並行制御・LLM の精度向上を実現しました。
業務系エージェント開発者への教訓: この設計思想は、業務系エージェントのツール設計全般に応用できます。第 2 回のベストプラクティス「description は LLM への手紙」と組み合わせることで、LLM がツールを正しく選択できる精度が大幅に向上 します。
判断 2:ファイル永続化
~/.claude/projects/<project>/tasks/
├── tasks.json # 全タスクのスナップショット
├── events.jsonl # 全操作のイベントログ
└── snapshots/ # 定期的なバックアップ
イベントソーシングパターンで 過去の状態に巻き戻し可能 になりました。
業務系エージェント開発者への教訓: この イベントソーシング設計は業務系エージェントの監査要件対応において非常に重要 です。「いつ・誰が・どのタスクを・どう変更したか」を全て記録することで、GDPR / 個人情報保護法対応や、業務プロセスの再現性確保が可能になります。§5 で MAF での実装例(EventSourcedTodoStore)を示します。
判断 3:後方互換モード
# V1 互換モードで動作させる(移行期間用)
export CLAUDE_CODE_ENABLE_TASKS=0
破壊的変更を顧客に強制せず、選択的に移行できる 設計です。
業務系エージェント開発者への教訓: 業務系 SaaS では、顧客が自分のペースで移行できる仕組み を用意することが重要です。特にエンタープライズ顧客は変更管理プロセスを持っているため、「即座に新機能に強制移行」は嫌われます。テナントごとに機能フラグで新旧を切り替えられる設計が、業務系での長期運用の鍵となります。
状態モデルの拡張
V2 で追加された cancelled 状態により、「やらないと決めたタスク」と「まだやってないタスク」を明確に区別できるようになりました。
業務系エージェント開発者への教訓: 業務系では、「なぜそのタスクを実行しなかったか」の理由記録 が監査要件で必要になるケースがあります。cancelled 状態に加えて、キャンセル理由をフィールドとして持つ拡張 も業務系では有用です(例:cancelled_reason: "承認却下")。
4. SDK 移行から学ぶ 5 つの教訓
本節の位置付け
本節では、Claude Code V1 → V2 移行から抽出した 5 つの普遍的教訓 を整理します。これらは業務系 SaaS で破壊的変更を計画する際に、そのまま応用できる知見です。
教訓 1:破壊的変更は「段階的に」
| フェーズ | 内容 |
|---|---|
| Phase 1 | V2 追加、V1 は警告付きで継続 |
| Phase 2 | V2 をデフォルトに、V1 は環境変数で復活可能 |
| Phase 3(将来) | V1 完全削除 |
各フェーズを数ヶ月かけて進めることで、顧客への混乱を最小化できます。
業務系エージェント開発者への教訓: 業務系 SaaS では、Phase 3(旧版完全削除)を宣言してから実施までさらに 6〜12 ヶ月の猶予を持たせる ことが推奨されます。エンタープライズ顧客の変更管理プロセスは長期間かかるため、突然の削除は契約違反や解約リスクにつながります。
教訓 2:「設計の正しさ」より「移行の容易さ」
V2 の設計は理論的に「正しい」ですが、それだけでは移行は完了しません。詳細な移行ガイド、CLI ツールによる自動変換支援、コミュニティサポートへの投資が同等に重要です。
業務系エージェント開発者への教訓: 業務系 SaaS では、移行ガイド・CLI ツール・顧客向けサポート の 3 点セットで顧客体験を向上させることが重要です。「正しい設計」で自己満足するのではなく、「顧客が移行できる設計」まで含めて完了と考える視点が長期運用の鍵となります。
教訓 3:本番テレメトリで優先順位を決める
Anthropic は 本番ユーザーの行動データ を基に改修を決断しました。「自分が良いと思う設計」ではなく「ユーザーが求める設計」へ。これは VS Code Copilot Chat の grep_search 最適化(補章 A 参照)と同じ姿勢です。
業務系エージェント開発者への教訓: 業務系 SaaS でも、Application Insights や Azure Monitor などで本番ユーザーの行動データを最初から蓄積 することが重要です。定量的なデータに基づいて設計判断を行うことで、「開発者の思い込みで作った機能」を回避できます。特にエージェントの Context Engineering においては、どの機能がどれだけトークンを消費しているか の実測データが設計改善の起点となります。
教訓 4:「インメモリ → 永続化」は重要な転換点
業務系で AI エージェントを設計するなら、最初から永続化を前提に するべきです。第 7 回の MAF 実装もファイル永続化を初期から組み込んでいるのはそのためです。
業務系エージェント開発者への教訓: この教訓は業務系エージェント設計で最も重要です。PoC 段階からインメモリで作ってしまうと、後から永続化に変えるコストが膨大 になります(全 API の再設計、テストコードの書き直し、既存データの移行)。業務系では 最初から IStateStorage などの抽象インターフェースを用意し、ローカルファイル実装 → Cosmos DB 実装 → Redis 実装への差し替えを容易にする設計 が推奨されます。
教訓 5:API 設計と SDK バージョニング
Claude Code は SDK と CLI のバージョンを揃えた 移行を実施:
TypeScript Agent SDK: 0.3.142 → V2 対応
Claude Code CLI: v2.1.142 → V2 対応
統一バージョンでリリースすることで、「どの組み合わせで何が動くか」の複雑さを避けられます。
業務系エージェント開発者への教訓: 業務系 SaaS で複数のコンポーネント(API サーバ、バックエンドエージェント、フロントエンド SDK など)がある場合、Semantic Versioning に従って統一的にバージョン管理 することが重要です。特に メジャーバージョン(破壊的変更)は全コンポーネントで揃えることで、顧客の変更管理コストを最小化 できます。
5. Microsoft Agent Framework (MAF) への応用:V2 思想を MAF で実現する
本節の位置付け
本節では、Claude Code V2 の設計思想を MAF でどう実現しているか、そして業務系エージェント向けにどう拡張しているかを解説します。第 7 回の MAF 実装は Claude Code V2 の設計を踏襲しつつ、業務系必須要件(Nag Reminder、Recitation、イベントソーシング)まで拡張 した集大成として位置付けられます。
本編第 7 回の C# 実装は V2 互換
本編第 7 回で示した実装は Claude Code V2 の設計をそのまま再現しています。V2 のベストプラクティスは既に MAF で実装可能です。
MAF 独自の拡張:Nag Reminder
Claude Code V2 にはない、本書独自の拡張です:
public string? AttentionCheck()
{
_roundsSinceUpdate++;
if (_roundsSinceUpdate < 3) return null;
var pending = _items.Count(i => i.Status != TodoStatus.Completed
&& i.Status != TodoStatus.Cancelled);
return pending > 0
? $"[Reminder] You have {pending} incomplete tasks."
: null;
}
業務系エージェント開発者への意義: Nag Reminder は、業務系エージェントの 「タスク完了忘れ」を防ぐ重要な仕組み です。例えば「顧客の問い合わせを 3 ラウンド更新しない」というケースを検知して警告を出すことで、SLA 違反を未然に防ぐことができます。
MAF 独自の拡張:Recitation Pattern
public class RecitationContextProvider : AIContextProvider
{
// 3 ラウンドごとに計画を末尾に再掲
}
Plan Persistence 対策(arXiv 2606.22953)を MAF に実装したものです。Claude Code V2 にない、業務系向けの拡張です。
業務系エージェント開発者への意義: Recitation Pattern は、業務系での 長時間タスクのドリフト防止 に直結します。特にマルチステップの業務プロセス(承認フロー、複数部署をまたぐ処理など)では、エージェントが途中で計画を見失うと業務プロセスが破綻します。Recitation Pattern による定期的な計画再掲は、業務系での長期運用の鍵となります。
各実装の位置付け
| 機能 | Claude Code V2 | VS Code Copilot Chat | MAF(本書) |
|---|---|---|---|
| ファイル永続化 | ◎ | × | ◎ |
| 4 ツール構成 | ◎ | × | ◎ |
| cancelled 状態 | ◎ | × | ◎ |
| Nag Reminder | × | × | ◎(独自拡張) |
| Recitation Pattern | 一部 | × | ◎(独自拡張) |
| ContextProvider 統合 | × | × | ◎(MAF 独自) |
この表が示す業務系への示唆: MAF(本書)実装は、Claude Code V2 と VS Code Copilot Chat の良い部分を統合しつつ、業務系必須要件(Nag Reminder、Recitation)まで拡張 した集大成です。業務系エージェントで TODO ツールを実装する際は、この 3 つの拡張機能を最初から組み込むことが推奨されます。
業務系での活用:イベントソーシング拡張
Claude Code V2 が採用したイベントソーシングは、業務系でも有効です:
// 拡張:すべての操作を events.jsonl に追記
public class EventSourcedTodoStore : TodoStore
{
private readonly string _eventsLogPath;
public override TodoItem Create(string title, string description = "",
Priority priority = Priority.Medium)
{
var item = base.Create(title, description, priority);
// 🔑 操作をイベントとして記録
var evt = new
{
timestamp = DateTime.UtcNow,
operation = "create",
task = item,
};
File.AppendAllText(_eventsLogPath,
System.Text.Json.JsonSerializer.Serialize(evt) + "\n");
return item;
}
}
利点:
- ✅ 過去の状態に巻き戻し可能
- ✅ 監査要件への対応(業務系で必須)
- ✅ 分析・可視化が容易(イベント数で生産性を測れる)
業務系エージェント開発者への意義: このイベントソーシング拡張は、業務系での 監査要件と生産性分析の両立 を実現する重要な設計です。特に金融・医療・法律など規制業界では、「エージェントがなぜその判断をしたか」を後から検証できることが必須要件となります。イベントログをそのまま監査証跡として提出できる設計は、コンプライアンス対応コストを大幅に削減できます。
6. ⚠️ アンチパターン
本補章で扱った Claude Code V1 → V2 移行の教訓を、業務系エージェント設計時のセルフレビュー用チェックリスト(アンチパターン)としてまとめました。
実装時は本表を「やってはいけないことリスト」としてご参照ください。特に #4・#5 は業務系での長期運用と破壊的変更対応に直結する重要項目です。
| # | アンチパターン | 問題点 |
|---|---|---|
| 1 | 全部自前でやろうとする | ベンダー API ネイティブ最適化を享受できない |
| 2 | 単一ベンダー固定でハードコード | 将来モデル切替が必要になると破綻する |
| 3 | フォールバックを持たない | BYOK・ローカル LLM 対応で破綻する |
| 4 | 最初からインメモリ設計 | 後から永続化に変えるコストが大きくなる |
| 5 | 破壊的変更を一括で行う | 顧客への混乱が大きくなる |
おわりに
本補章では、Claude Code の TODO ツール V1 → V2 大改修から、SDK 設計と移行戦略について解説しました。「段階的な移行」「本番テレメトリに基づく優先順位付け」「永続化を最初から前提にする設計」は、どの AI エージェント開発にも応用できる普遍的な教訓です。
特に重要な発見は、Claude Code V2 の設計思想が、業務系エージェント必須要件(永続化・監査・並行制御・後方互換性)と完全に一致している ことです。補章 A の VS Code Copilot Chat(シンプルさ重視)と対照的に、Claude Code V2 は「運用性重視」の設計を採用しており、業務系エージェントで参考にすべき部分が多く含まれています。
一方で、Claude Code V2 も個人利用ツールの範囲内であり、業務系 SaaS で本番運用するにはさらなる拡張 が必要です:
- マルチテナント分離: テナントごとに独立した TODO ストア
- 監査ログの永続化: イベントソーシングを Blob Storage 等へ長期保管
- 分散処理対応: Redis / DynamoDB 等でマルチプロセス共有
- PII マスキング: タスク内容の個人情報を保存前にマスキング
これらの業務系拡張は、次の補章 C「業界研究の業務系翻訳ガイド」で、体系的に整理します。補章 A(VS Code Copilot Chat)、補章 B(Claude Code V2)で紹介した業界標準ツールの知見を、業務系エージェント設計に安全に適用するための 翻訳マトリクス をご紹介します。
参考文献
Claude Code 公式ドキュメント
- Claude Code Docs「Tools reference」
- Claude Code Docs「Todo Lists (Agent SDK)」
-
Claude Code Docs「Changelog」(v2.1.142 — 2026/5/14: Fast mode が Opus 4.7 デフォルト化、
claude agentsに8新フラグ追加など24変更)- 補足: 一次ソースは anthropics/claude-code Releases (GitHub) を参照。
-
Claude Code Docs「Agent SDK reference — TypeScript」(0.3.142 で V2 session API を削除、
query()API に統一)- 補足: TypeScript SDK の完全な changelog は anthropics/claude-agent-sdk-typescript
CHANGELOG.mdを参照。
- 補足: TypeScript SDK の完全な changelog は anthropics/claude-agent-sdk-typescript
Anthropic Engineering Blog
- Anthropic Engineering「Effective context engineering for AI agents」(2025/9/29)
- Anthropic Engineering「Building effective agents」(2024/12/19)
イベントソーシング・SDK 設計
- Martin Fowler (2005/12/12).「Event Sourcing」
- Microsoft Learn「Event Sourcing pattern」(Azure Architecture Center)
- Semantic Versioning 2.0.0
コミュニティ実装・解説
-
shareAI-lab/learn-claude-code
s05_todo_write/(TodoWrite and Planning)- 補足: Web 版テキストは Learn Claude Code を参照。
学術論文
- Mehta, A., & Datta, A. (Snowflake AI Research, 2026). "Plans Don't Persist: Why Context Management Is Load Bearing for LLM Agents." arXiv:2606.22953
- Manus AI / Yichao "Peak" Ji (2025/7/18). "Context Engineering for AI Agents: Lessons from Building Manus" — Recitation Pattern (Recite Your Objectives)
Microsoft Agent Framework 公式
-
Microsoft Learn「Microsoft Agent Framework — Context Providers」
- 補足: Python API リファレンスは
agent_framework.ContextProviderclass も参照。
- 補足: Python API リファレンスは
- microsoft/agent-framework — GitHub repository
業務系コンプライアンス
- GDPR Article 5「Principles relating to processing of personal data」(GDPR-info.eu, 公式英訳)
-
個人情報保護委員会 (PPC)「法令・ガイドライン等」
- 補足: 法律本体は e-Gov 法令検索「個人情報の保護に関する法律(平成十五年法律第五十七号)」 を参照。