どうもお久しぶりです。相変わらず元気に色々やってます。

はじめに

最近Claude Codeを使って開発ワークフローを自動化しようとしてるんですけど、ちょっと困った問題に遭遇しました。

「途中までワークフローに従ってくれるのに、作業が長くなると突然ルールを忘れて勝手に進めちゃう」

これ、地味にストレスなんですよね。今回はこの問題と戦った記録を残しておこうと思います。

何が起きたか

前提

CLAUDE.md（ワークフローガイド）にはこんな感じでルールを書いてました：

コミット・PR作成前は必ずユーザーの明示的な確認を待つ
1ステップずつ実行し、完了してから次へ進む
不明な点はユーザーに確認する

で、何が起きたか

ワークフローに従って作業を進めてると、途中から突然ルールを無視し始める：

実装作業中にauto-compact（コンテキスト圧縮）が発生
compact後、Claudeがユーザー確認なしで勝手にコミット実行
計画した作業順序を無視して、別の作業を始める

「いや、確認待ってって言ったじゃん...」ってなりました。

原因

Claude Codeには、コンテキストウィンドウがいっぱいになると自動的に会話履歴を要約・圧縮する「auto-compact」機能があります。

この圧縮時に、以下の情報が失われるみたいです：

CLAUDE.mdの詳細なルール - そもそも再読込されない
「確認を待つ」などの重要な制約 - 要約時に省略される
現在の作業フェーズの認識 - コンテキストから消える

つまり、Claudeは「やるべきこと」は覚えてても「どうやるべきか」を忘れちゃって、独自判断で進めちゃうんですね。

トライその1：TodoWriteの書き方を工夫する

考えたこと

auto-compact後も TodoWrite で作成したタスクリストは引き継がれるらしい。

じゃあタスクの書き方を工夫すれば、勝手に実行されることを防げるんじゃないか？

やったこと

CLAUDE.mdにこんなルールを追加：

### TodoWriteのルール

重要操作は「実行する」ではなく「ユーザーに確認を依頼」と書く：

| NG | OK |
|--------|----------------|
| コミット | ユーザーにコミット確認を依頼 |
| PR作成 | ユーザーにPR作成確認を依頼 |

理屈としては：

TODOリストはauto-compact後も保持される
「コミット」というタスクだと完了させようとして実行しちゃう
「確認を依頼」って書いてあれば、確認行為そのものが完了条件になる

結果

部分的に効果あり。でも根本解決には至らず。

タスク名の書き方で多少の抑止効果はあったんですけど、コンテキストが圧縮されると、そもそもワークフローの存在自体を忘れることがあって...長い作業では結局同じ問題が発生しました。

トライその2：作業の粒度を小さくする

発想の転換

トライその1でわかったこと：

auto-compactは作業が長くなると発生する
auto-compactが発生するとワークフローを忘れる
TODOリストの書き方だけでは限界がある

ここで考え方を変えました。

「auto-compactを防ぐ」のは無理。じゃあ「auto-compactが発生しても復帰できる設計」にすればいいのでは？

そして気づいたこと：

スラッシュコマンドを実行するたびにワークフローガイドを再読込させれば、たとえauto-compactが発生してもリセットできるじゃん

やったこと：ワークフローを4フェーズに分割

今までのワークフロー（重い）：

/workflow-plan → /workflow-implement（実装＋コミット＋PR作成を一括） → /workflow-close

/workflow-implement が重すぎて、この中でauto-compactが発生してたんですよね。

新しいワークフロー（軽い単位に分割）：

/workflow-plan → [/workflow-implement ⇄ /workflow-commit] → /workflow-close

ポイントは：

実装とコミットを別コマンドに分離
各コマンドは軽い単位で完結
1作業単位ごとに implement → commit を繰り返す

各コマンドでワークフローを再読込

すべてのコマンドの冒頭で、必ずワークフローガイドを読み込むようにしました：

## /workflow-implement の実行内容

1. ワークフローガイドを読み込む  ← 毎回リセット
2. ログファイルを読み込み、次の作業単位を特定
3. 1作業単位のみ実装・テスト
4. ログファイルを更新
5. 次のステップを案内（/workflow-commit へ誘導）

## /workflow-commit の実行内容

1. ワークフローガイドを読み込む  ← 毎回リセット
2. ログファイルを読み込む
3. 変更状態を確認
4. ユーザーに確認 →「コミットしてください」を待つ
5. コミット実行
6. 次のステップを案内（次の /workflow-implement へ誘導）

これで：

仮にauto-compactが発生しても、次のコマンド実行時にワークフローが復活する
各コマンドが軽いので、コマンド内でauto-compactが発生しにくい

1作業 = 1コミット単位を徹底

計画フェーズで作業を細分化することを必須にしました：

## 実装計画

### 作業1: ユーザー認証APIの追加
- [ ] 実装内容: /api/auth エンドポイント作成
- [ ] 変更ファイル: routes/api.php, AuthController.php
- [ ] テスト内容: 認証成功/失敗のテスト

### 作業2: バリデーション追加
- [ ] 実装内容: リクエストバリデーション
- [ ] 変更ファイル: AuthRequest.php
- [ ] テスト内容: バリデーションエラーのテスト

1つの /workflow-implement で扱う作業量を意図的に小さくすることで、auto-compactが発生する前にコミットフェーズに移行できます。

待機指示は明示的に

確認が必要な箇所では、Claudeが先に進まないよう明示的に書きました：

ユーザーに確認 → **回答を待つ**：「実装計画を記録しますか？（Y/N）」

**ユーザーから「コミットしてください」の指示があるまで待機**

「回答を待つ」「待機」という単語を入れておくと、多少効果がある気がします。

結果

かなり改善しました。

auto-compact発生時も復帰可能になった
勝手なコミットが激減
作業の見通しが良くなった（1作業1コミットで進捗が明確）
中断・再開が楽になった

完璧ではないですけど、実用的なレベルにはなったかなと思います。

まとめ

Claude Codeのauto-compact問題への対策として、2つのアプローチを試しました：

対策	効果
トライ1: TodoWriteに確認ステップを明記	部分的に効果あり
トライ2: 作業粒度を小さくする＋各コマンドでワークフロー再読込	かなり改善

学んだこと

auto-compactを「防ぐ」のは難しい - コンテキストウィンドウの制限がある以上、避けられない
「復帰できる設計」にすることが大事 - 各コマンドでワークフローを再読込
作業粒度を小さくする - 1コマンドで扱う作業量を減らし、auto-compactが発生する前に次のフェーズへ
待機指示は明示的に - 「回答を待つ」「指示があるまで待機」を文中に入れる

最終的なワークフロー

/workflow-plan [チケットURL or 作業説明]
↓ 調査・計画（作業を細分化）
┌────────────────────────────────────────────┐
│ /workflow-implement [ログファイル名]       │
│ ↓                                          │
│ /workflow-commit [ログファイル名]          │
│ ↓                                          │
│ ...作業単位ごとに繰り返し...               │
└────────────────────────────────────────────┘
↓
/workflow-close [ログファイル名]

各コマンドの冒頭でワークフローガイドを再読込することで、auto-compact後も正しい手順で作業を継続できるようになりました。

おわりに

Claude Codeは便利なんですけど、長時間の作業ではauto-compactによる「記憶喪失」が発生します。

これを「バグ」と捉えるんじゃなくて、「そういうもんだ」と受け入れて、復帰可能な設計にする。これが安定した運用のコツなのかなと思いました。

そのうち更にAIが進化してこの文章が無駄になりますように！！！