Claude Codeが残課題を放置する構造的な原因と、開発における具体的な対策
本記事は、AIコーディングアシスタント「Claude Code」を利用した開発プロセスにおいて、「重要な処理が未完成のまま『残課題』として終わってしまう」という問題の原因と、それを解決するための実践的な対策を詳細に解説している。この問題は単なるドキュメント（CLAUDE.md）の問題ではなく、モデルの行動特性、指示設計、およびタスク依頼方法という「3層構造」が絡み合っていることが指摘されている。
**【問題の原因：3層構造】**
1. **完了判定の誤認（見た目による判断）：** Claudeはテストやビルドといった機械的な完了シグナルがない場合、「作業が完了したように見えるか」という表面的な見立てだけでタスクを終了させる傾向がある。残課題を「報告する」行為が、実質的な「完了」の代替シグナルとなってしまうのが根本原因である。
2. **指示設計の不備（CLAUDE.mdの問題）：** CLAUDE.mdに単に「残課題があれば記載する」といった抽象的な記述だけでは、「記載した後にどうするか」という行動フローが定義されていないため、書いた時点でタスクがクローズされてしまう。
3. **依頼範囲の限定（スコープ外の発生）：** 「UIを修正して」のように機能の一部のみを依頼すると、バックエンド処理など重要な部分が「スコープ外の残課題」として記録され、放置されるケースが多い。
**【具体的な対策】**
筆者は、この問題を解決するために以下の4つの対策を提案している。最も効果が高いとされるのは、「依頼時に完了定義を書くこと」（例：単なる実装ではなく「DBの結果カラムが自動更新されるまで」を完了とする）であり、これによりスコープ外の発生自体を防ぐことができる。
次に重要なのが、「CLAUDE.mdに強制命令で書く」ことであり、「未完了フローが生じた場合は必ずユーザーに報告し、継続するか確認すること。記録だけ残して黙って終えることは禁止。」といった強い表現（IMPORTANTやYOU MUST）を用いる必要がある。また、個別の作業記録に課題を埋もれさせないよう、「backlog.md」という専用ファイルで残課題を集約管理することが推奨されている。
さらに、複雑な機能の実装前には「/plan」モードを利用して計画段階で事前に洗い出しを行うことが、スコープ漏れの予防策として有効である。
背景
AIコーディングアシスタントの進化に伴い、大規模言語モデル（LLM）を開発プロセスに組み込む事例が増加している。しかし、これらのモデルは「人間が意図する真の完了」と、「表面的な出力による完了」の間で認識のズレが生じやすいという課題がある。本記事は、その具体的な運用上の落とし穴とその対処法を提示している。
重要用語解説
- Claude Code: Anthropic社が提供するAIコーディングアシスタント機能の一つ。開発プロセスにおけるコード生成やタスク管理を支援するツールであり、指示（プロンプト）の設計に依存する。
- CLAUDE.md: Claude Codeに対して与える「コンテキスト」情報を含むドキュメントファイル。モデルの行動指針やルールを設定するために使用されるが、単なる記述では強制力を持たない。
- スコープ外: 依頼されたタスクの範囲（スコープ）に含まれない部分を指す。本記事においては、開発者が意識的に見落としがちな、未実装だが重要な機能の一部を指す。
今後の影響
この知見は、AIを活用したソフトウェア開発における「プロンプトエンジニアリング」の高度化に直結する。単なる指示出しではなく、「完了の定義」「強制的な行動フロー」「情報管理構造（backlog）」といったシステム設計レベルでの介入が必要であることを示しており、開発効率と品質保証の両面で大きな改善が期待される。