この記事は playpark Blog からの転載です。
この記事で分かること
- Claude Code Skillsの会話コンテキストが揮発する問題の本質
- ファイル永続化というアプローチを選んだ理由
- 状態スキーマ設計で重要な3つの判断ポイント
背景: こういう課題があった
Claude Codeで6フェーズのワークフローを実行していると、Phase 3（実装）の途中でauto-compactが発生し、会話コンテキストがリセットされることがあります。「どこまで終わったか分からない」状態になり、最悪の場合やり直しに。
AIの記憶は会話に依存しており、会話が消えると記憶も消える。これが長時間ワークフローの根本的な課題です。
選択肢の検討
状態を保持する方法はいくつか考えられます。
| アプローチ | メリット | デメリット |
|---|---|---|
| 会話内で記憶 | 実装不要 | auto-compactで消える |
| 環境変数 | 軽量 | セッション終了で消える、構造化しにくい |
| JSONファイル | 永続化、構造化可能、人間も読める | ファイルI/Oが必要 |
なぜJSONファイルを選んだか
判断基準は3つでした。
1. 永続性: auto-compact、セッション終了、/clearのいずれでも消えない。ファイルシステムに書けば確実に残ります。
2. 構造化: JSON Schemaで状態の形を定義でき、不整合や必須フィールドの欠落を防げます。「フェーズ名がphase3だったり3_implementだったりバラバラ」という問題を根本的に解決。
3. 可読性: 人間がデバッグ時に直接ファイルを開いて状況を把握できます。機械だけでなく、開発者にとっても透明性がある。
実装例
{
"version": "1.0",
"issue": 123,
"current_phase": "3_implement",
"phases": {
"1_prepare": { "status": "done", "result": "Worktree created" },
"2_analyze": { "status": "done", "result": "Identified 5 files" },
"3_implement": { "status": "in_progress" }
},
"next_actions": ["Continue implementation"]
}
ポイントはcurrent_phase（今どこか）とnext_actions（次に何をすべきか）の分離です。前者はフェーズの特定、後者は具体的なアクション指示。復帰時の曖昧さを排除します。
3つの重要な設計判断
判断1: statusを5段階にした理由
pending、in_progress、done、failed、skippedの5状態を定義しました。特にin_progressとdoneの区別が重要で、これがないと「途中で止まった」のか「完了した」のかが判断できません。
判断2: next_actionsを別フィールドにした理由
current_phaseが分かっても「次に何をすべきか」は自明ではありません。Phase 3がin_progressのとき、「実装を続けるのか」「テストを先に書くのか」は状況次第。明示的に記録することで、復帰時の判断コストをゼロにします。
判断3: versionフィールドを入れた理由
スキーマは変わります。versionがあれば、旧フォーマットの状態ファイルを検出して適切にマイグレーションできます。未来の自分への保険です。
まとめ: どういう場面で使うべきか
Claude Code Skillsの状態管理は、3フェーズ以上の長時間ワークフローで効果を発揮します。短いワークフローであればauto-compactのリスクは低く、状態管理のオーバーヘッドに見合いません。「途中で止まっても続きから再開したい」場面で導入を検討してください。
さらに深掘りしたい方へ
この記事ではClaude Code Skillsに状態管理が必要な理由と設計判断を解説しました。
【Claude Code】Skillsの状態管理とリカバリ - auto-compact対策の設計パターン ではさらに：
- 人間可読なSTATE.md出力パターンとデバッグ時の活用法
- PRレビューループを追跡するイテレーション状態管理の詳細設計
- skill-creatorへの伝え方と自作Skillへの応用ステップ
playpark について
playpark LLC - 業務自動化・AI活用・Web開発
