✏️

コンテキスト分割のための Claude Code イディオム集

2025/06/20に公開

issue

Claude Code

tech

2025年6月13日、遅まきながらついに Claude Max に課金して Claude Code デビューをしました。

現在、ある OSS のメンテナとして、Laravel 9 → 10 へのアップグレードに取り組んでいます。

最初の1週間使い倒してみた段階で、よく使ったフレーズをまとめておきます。
GitHub CLI が必要です。

プランニング

コンテキストの compact が走ると、時間もかかりますしアウトプットの品質も安定しなくなります。compact を避けて、一つのタスクが一つのコンテキストで完結するように分割してあげると、比較的うまくいくようです。

今後行うタスクを Claude Code が覚えておかなくていいように、外部記憶として GitHub Issue を使います。

以下は通常モードで実行していますが、Plan Mode で結果を確認してから書き込んでもらうのもよいでしょう。

Epic

Laravel のアップグレードに必要なマイグレーションのプラン作成など、それ自体が大きなタスクである（＝コンテキストに収まりきらないであろう）場合は、タスク分解した結果を Epic Issue として書き込みます。

Plan a testing roadmap for the transition to Laravel 10 + Reverb, make an epic issue
Laravel 10 + Reverb 構成への移行のためのテストロードマップを計画し、epic issue を作成せよ

こんな Issue ができます。依存関係の子 Issue も作成してくれます（GitHub の子 Issue 機能は使ってくれません）。

Issue 作成

1 Issue がコンテキストに収まるであろうときは、その Issue を作成します。必要なら、前提のコードを読みに行くように命令します。調査結果に応じて今後必要なステップを記録しておいてもらうことで、作業時の読み込み量を減らすよう意識させます。

Make an issue to integrate SonarQube MCP
SonarQube MCP を導入する issue を作成せよ

こんな Issue ができます。

できた Issue を確認して、必要であれば人間が直接編集します。このようにするのは編集履歴を残すためです。後で作業を行うとき、Issue のコメントは指示しないと読んでくれません。コメントするよりも、本文を編集するのがよいです。

タイトルだけの Issue の本文を書かせる

人間が作ったタイトルだけの Issue は、Claude Code がそのまま作業するには重荷です。一旦タスク分解させて、結果を Issue に書き込んでもらいます。

Fill DoD for the issue #xx
Issue #xx の完了の定義を書き込め

DoD とは definiton of done のことで、Issue の完成要件を意識させます。

こんな Issue ができます（元々本文が入っていたのでコメントされました）。こちらも必要に応じて人間が編集します。

コーディング

実際のコーディングは、まず /clear でコンテキストを削除してから、Issue を読ませます。コンテキストを削除することで、人間が Issue に行った変更を読みに行ってくれるようになります。

小さな Issue について、一気にコミットまでさせる場合はこちら。

Make a feature branch, handle #xx
フィーチャーブランチを作って #xx を処理せよ

少しサイズの大きい Issue では、まず Claude Code の ToDo リストが合っているかどうか確認したいことが多いでしょう。

View #xx and show me the todo
#xx を調べて ToDo を見せろ

この指示だと GitHub CLI を使わずに、コミットログから Issue への言及を探そうとすることがあります。頻度は高くないので、私は今のところ都度 Esc キーで止めて use gh cli と追加指示していますが、CLAUDE.md に書いておいてもいいかもしれません。

コミットフック

このプロジェクトでは、Larastan, Laravel Pint のチェックが通過することに加えて、phpunit のテストがすべて成功することをコミット要件にしています。pre-commit フックスクリプトを用意してチェックを強制させていますが、Claude Code は頻繁に --no-verify をつけてフックを迂回しようとしてきます。挙げ句の果てに、自分でフックスクリプトを書き換えてチェックが通るようにしてきたりもしました🤣

このような変更があった場合は、revert hook script などと命令して、変更を巻き戻させます。

レビュー

コーディングが終わったら PR を作るよう命令します。

Make a PR
PRを作れ

PR作成のタイミングでコンテキストを削除してもよいでしょう。ここまでで Claude Code は Issue の実装が完了しているはずだと思っているので、一旦忘れて批判的にコードを見てもらうようにします。コンテキストを削除した場合は、View #xx で PR を読ませます。

PR を作成したらユニットテストと静的解析の CI が走るとともに、CodeRabbit によるレビューが入ります。Issue の DoD を満足できているかどうかを判断してくれるので、不足していれば追加で命令します。

Check CI result
CI結果を確認せよ

Fix CodeRabbit comments
CodeRabbit のコメントを修正せよ

総括

フレームワークのバージョンアップのために、書き捨てのテストを整備する→バージョンを上げるという手順で作業させてみましたが、案外これが楽しかったです。
全く知識がない Laravel で、自前であればドキュメントとにらめっこしなければならなかったところが、ほとんど検索なしで進んでいくのは面白かったですね。あとはこれがうまく動くかどうか、人間がテストしているところです。
今後も使い倒していこうと思います。