前提

Claude Codeで開発効率化ツール「Altary」を開発しています。

過去記事では導入のメリットについて触れることが多かったのですが、今回は現状感じている課題についてまとめました。

概要

下記が問題であると感じました

再起動時の性能低下
命令を過剰に忠実に実行する
トークン制約による、開発中断

弱点１: Claude Codeを停止して再起動すると性能が落ちる

起こったこと

Claude Codeのセッションを停止し、再起動して開発を再開すると、停止前の文脈が把握されておらず、性能が低下したように感じられます。

原因

セッションメモリの揮発
Claude Codeは内部でチャット履歴を一時的に保持しますが、プロセスを停止するとメモリ上のチャット履歴や生成された知識が全てリセットされます。
外部ドキュメントの更新タイミング
claude.md は「明示的に更新を指示」しない限り上書きされないため、新たに得られた知見や方針がドキュメントに反映されません。

対応策（現状）

重要情報を都度ドキュメント化してclaude.mdに明記する。
開発を進めるたびに、Claude Codeに対して

「新しく学んだ設計方針を `claude.md` に追記して」  
「これまでの議論を要約して `claude.md` に反映して」

と明示的に指示する。

対応策（将来的には・・・）

外部ナレッジベースの活用

RAG（Retrieval‑Augmented Generation）の仕組みを取り入れ、claude.md や他のナレッジリポジトリを常に読み込むワークフローを構築する。
再起動時にも外部ストレージ（Git リポジトリやドキュメントDB）から最新のドキュメントを自動でロードする。

弱点２: 文脈や整合性を無視して、命令を過剰に忠実に実行する

具体例

インラインCSSを書いてフロントを調整しようとする
CSRF保護の無効化を提案してしまう
A、B、C という要素がある中で「Bを直して」と言うと、A や C との整合性を無視して B の修正だけを行おうとする

原因

過度な命令従属性
LLM／Claude Code は与えられたプロンプトの命令を最優先で実行しようとするため、全体の文脈やセキュリティ要件を無視する場合があります。
ガードレール不在
セキュリティ方針やコーディング規約などが、重要な制約（例：CSRF 保護や全体整合性チェック）がプロンプトに含まれていないと守られない場合があります。

対応策（claude.md やシステムプロンプトに明記）

以下のような開発方針を claude.md に記載し、またセッション開始時のプロンプトでも毎回明示しておくことで、不要な修正や危険な提案を防止できます。

- CSS は外部スタイルシートに記述し、インラインCSSは禁止する  
- CSRF 保護は必ず有効にし、省略・削除を許可しない  
- 複数コンポーネント間の整合性を常に確認すること  
- フロントエンドとバックエンドの契約（API仕様など）は常に整合性を保つ  
- テストコードの更新を伴わない本番コードの改修は原則不可

弱点３: $20プランのトークン制約により、開発が中断される

起こっていること

Claude CodeのProプラン（$20/月）は、使用開始から約5時間ごとにトークン制限がリセットされる時間制サイクル制御になっています。

しかし、以下のような問題が発生しています：

実際の開発では開始から2〜3時間でトークンを使い切ってしまう
その後、5時間のクールタイムが明けるまで利用不能になる
特に連続して重い処理（ファイル生成・長文解析など）を行った場合、予想以上に早く制限に達し、作業が強制中断される

対応策

Claude Codeへの指示を明確かつ局所化し、探索負荷（トークン消費）を削減する
- 例：「/src/Controller/UsersControllerのこの関数について」など
仕事のサイクル自体をClaudeの5時間サイクルに合わせる
- 開始時刻を記録して次の利用可能タイミングを把握
- 制限到達後は要件整理・設計ドキュメント編集など別タスクに切り替える
大規模リファクタリングは段階的に分割
- 一機能単位・コンポーネント単位で修正し、中断しても再開可能な状態に保つ

まとめ

Claude Codeは、AIによるコード補完やリファクタリング支援において非常に優れた能力を持つ一方で、以下のような運用上の明確な弱点が存在します：

セッション停止による知識の揮発

再起動後の思考断絶を防ぐためには、claude.mdへのこまめな記録と要約の反映が必須です。
外部ナレッジとの連携（RAG構成）が将来的な改善策となります。

過度な命令従属性と整合性の欠如

指示の意図を過度に素直に受け取りすぎる傾向があるため、システムプロンプトでの制約設定や整合性チェックの意識が必要です。

$20プランの時間制トークン制約

実質的に「2〜3時間作業しただけで制限に達する」ことが多く、5時間のサイクルが開発フローを中断させてしまいます。
指示の最適化や作業のフェーズ分割、制限到達後の作業切替などでトークン節約と開発継続性の両立が求められます。

これらの課題は、Claude Codeの特性を理解し、運用で補完することで十分にコントロール可能です。
また、将来的にRAGや従量課金制などの技術・プラン面の拡張により、より実務的な開発ワークフローへの適合性はさらに高まると考えられます。

過去記事