最近のClaude Codeの使い方

この記事では最近（2025/08時点）でKurogoma4DがClaude Codeを使うときにどういうフローで使っているかという話をしていきます。

既存プロジェクトの調査のとき

1. serena MCPを導入する
2. 調査結果はMarkdownに出力してもらう

serena MCPを導入する

https://github.com/oraios/serena

最近話題のやつです。プロジェクトの構造や依存関係を素早く把握できるので、既存プロジェクトに初めて触る時は特に重宝します。

調査結果はMarkdownに出力してもらう

「このプロジェクトの認証フローを調査してMarkdownにまとめて」のように依頼すると、なにかしらの調査レポートが得られます。これを最初からplan modeではなくedit modeでやらせるのが肝です。
結果をファイルとして書き出しておけば、その時点で外部メモリとして機能させることが可能なので、ブラッシュアップがしやすくなります。

また、このときフォーマットを指定したいときはプロンプトに例を含めるか、テンプレを作ったうえで「docs/report_template.mdの形式で出力して」と付け加えます。few-shot^[1]はこういうときに役に立つ。

ファクトチェックは手動で実際のコードと照合したり、Claude Codeの別セッションに投げ返して再検証したりします。

新規開発のとき

1. まず仕様書的なものとして以下を用意する（docs/ディレクトリとか作ってまとめる）
   1. 仕様概要
      • フォーマットはだいたい要求を伝えて出力させたものに従う（出してから過不足を修正するスタイル）
   2. 技術的な詳細を書いたドキュメント
      • 使用する技術スタック、アーキテクチャ、外部サービス連携などの詳細。特殊な実装要件がある場合は必ず書いておく
   3. ユースケース一覧
2. 仕様概要とユースケース一覧をもとに、手元で行うべきタスク一覧を tasks.md として作成する
   • tasks.mdはチェックボックスつきのリストとして出力してもらう
   • tasks.mdはプロジェクトルート（あるいはモノレポのときはClaude Codeを起動するディレクトリ）に置く
3. 後述のSubagentを作る
4. あとはSubagentを起動してイテレーションを回す
   • 適宜フィードバックを各種ドキュメントやプロンプトに加える

開発に使うSubagent

以下のような指示をSubagentに与えます。Subagentを作るときは /agents コマンドから指示を与えて自動生成する方法で大丈夫ですが、出てきたmdファイルの中に不要な指示が入っている場合もあるので必ず自分がやりたいことが反映されているかどうかチェックしましょう。
また、これはプロジェクトの事情に合わせてチューニングしてください。

以下の手順でタスクを実行してください：
1. mainからブランチを作成してチェックアウト
2. tasks.mdから未完了のタスクを1つピックアップ
3. docs/配下のドキュメントを参考にしながら実装
   - 使ってほしいtoolがあれば明示的に書く
   - e.g. `Use dart tool to investigate Dart code.`
4. test, lintを実行してオールグリーンを目指す
   - エラーがあれば修正を繰り返す（iterateして対応）
5. tasks.mdでピックアップしたタスクにチェックを入れ、完了状態にしてもらう
6. 完了したらコミットを作成
   - 必要に応じてPRも作成（手元確認のみならコミットだけでOK）

「iterateして」という指示は重要です。これがないとSubagentはエラーを一度修正しただけで完了してしまうことがあります。

Slash Commandで効率化

Subagentを起動するだけのSlash Commandを作成しておくと便利です。

<!-- .claude/commands/task.md -->
Use task-executor subagent.

これで /task と入力するだけで次のタスクが自動実行されます。

注意点

上のフローだとSubagentをメインで利用していきますが、Subagentを使わずに指示した内容はSubagentに引き継がれるのでそこで変なコンテキストが入りこまないようにする必要があります。
この点を考慮しないと、例えばブランチを勝手に切ってくれなかったり最後にコミットがされなかったり、移動したファイルを探して勝手に過去のリビジョンにチェックアウトしたりといったことをされます（n敗）。

対策としては、Claude Codeのプロセスを2つに分けてSubagentを使うプロセスと修正指示を加えるプロセスに分けることが挙げられます。
今のところはこれでうまいことできている気がします。

Subagentsのメリット

Subagentsを活用することで感じたメリットを一応書いておきます。

1. 独立したコンテキストでの実行

Subagentはタスクを実行する際に毎回ほぼまっさらな状態（メインプロセスから引き継いだコンテキストのみが入った状態）から開始され、タスク内容自体のコンテキストは独立したものになります。これは一見デメリットに見えますが、well-documentedなプロジェクトであれば、ドキュメントから必要な情報を取得できるため問題ありません。

長時間Claude Codeを使っていると、過去のコンテキストに引きずられて余計な処理をしてしまうことがあります。

「このリストから指定した地点までカメラを動かしたい！」

...と思ってタスクを依頼したら、なぜか前に話していた認証機能の改修まで始めてしまった、みたいなことが防げます。

2. 並列実行の可能性

理論上、複数のSubagentを同時に起動して並列でタスクを処理することも可能です。

自分はまだ本格的に試していませんが、独立性の高いタスクなら並列実行で開発速度を大幅に向上できそうです。

3. 再現性の向上

同じ仕様書とタスク定義があれば、誰が実行しても（どのSubagentが実行しても）同じような結果が得られます。これは特にチーム開発において重要なメリットです。

まとめ

Claude Codeは単なるコーディング支援ツールではなく、適切に使えば開発プロセス全体を効率化できる強力なツールです。特にSubagentsを活用することで、以下のメリットがあります、

• 既存プロジェクトの調査・改修が体系的に行える
• 新規開発では仕様書ベースの自動実装が可能
• 独立したコンテキストで安定した品質の成果物が得られる

まだSubagentsを使ったことがない方は、ぜひ試してみてください🫰 ←これCLAUDE.mdに書いてあるから記事書かせると毎回付けてくる

脚注

1. ここではAIへの指示を出す際に出力してほしい例を出して説明する「few-shot prompting」のことを指します。