Claude Codeを使い始めて4ヶ月になりますが、使い方も日々アップデートされていく感覚があります。この記事は、2025年8月末時点でClaude Codeをどのように使っていたか、具体的な手順を中心に備忘録としてまとめたものです。まずは考え方を共有してから、具体の話をする構成となっています。
使い方の型を決める
Claude Codeを使用していると期待通りの挙動を引き出せず、延々と試行錯誤してしまうことがあります。しかし、実装タスクで集中するべきはツールの使い方ではなくタスク本来の内容であるため、なるべく使い方の型を決めてその通りに動かしています。
私の場合、型をつくるために以下のサイクルを回しました。
- 普段の開発フローを整理して、改善できそうな箇所を見つける
- Clade Codeを使うことでどのように改善できそうか調査をしたり、試作をつくって検証する
- 実際の開発フローに組み込んでみる
- 結果を振り返って、期待と実際の挙動にギャップが出てた場合は手順「1」に戻る
インクリメンタルに進める
AI との協業を上手に進めるうえで「如何にしてコードの出力結果を安定させるか」を考える必要があります。常に十分な情報を提供できればよいのですが、人間側が正しく問題を理解できていない状況やコンテキストサイズの問題など、不確実性の高い状況は往々にして発生します。
そのための対策として、Claude Codeを明確な作業スコープで可逆的に実行することが重要だと感じています。後述しますが、Gitのコミットとdifitというローカルレビュー用のツールでを使って、コミット単位でレビューを繰り返すことで開発を駆動します。
- コミットは細かく: プロンプトをコミットする。プロンプト単位でClaude Codeに実行結果をコミットさせる
- すべての作業を可逆にする:
git resetでいつでも特定のバージョンに戻せる状態を維持する - レビュー: 人間側に批判的な思考を行う機会をつくる
- 明確な指示: ファイルと行数を指定したうえで、明確な内容で作業を依頼する
ターミナルを広く使う
個人的な感覚ですが、Claude Codeの入力欄は狭くて使いにくいです (よくエンターキーを誤爆します)。そこで、ターミナル上で動作する特徴を活かして、他のCLIツールで補える部分は慣れたツールで行うようにしています。基本的にはリポジトリ直下のMarkdownファイルにプロンプトを書いて、それをスラッシュコマンドでClaude Codeにに渡しています。
主に使用しているCLIツール:
Claude CodeとCLIツールの組み合わせ
ナレッジを蓄積する
Claude Codeを用いた開発の悩みとして、開発タスクを通じて得られるナレッジが自分自身に蓄積されにくいと感じています。そのための対策として、個人開発で作成したプロンプトやClaude Codeのアウトプット (レビューやタスクの内容をまとめたMarkdownファイル) はObsidianで管理しています。
Obsidianはマルチデバイスの同期に対応している他、プレーンテキスト (Markdownファイル) で情報を扱えるため、ターミナル上のNeovimから簡単に編集できるといった利点を持っています。また、Claude Codeからも直接読み書きできるため、ナレッジを貯めて引き出すのに適したツールだと感じています。
Obsidianからナレッジを引き出す
結果として、振り返りが効率化 (準備の時間を大幅に削減) されることで、自身で書いていないコードでも記憶の定着に繋げることができました。一方で技術の習得を目的とする場合、AIに考えさせた内容を写経するのはあまり効果を得られませんでした。
現在の開発フロー
ここからは、Claude Codeを用いた具体的な開発フローを紹介します。本記事では扱わないため省略している箇所もありますが、大まかな手順は以下の通りです。
- 作業ディレクトリの作成
- 実装計画の作成
- 実装計画の修正
- 実装
- 実装の修正
- レビュー
- 振り返りとナレッジ管理
作業ディレクトリの作成
Anthropicのドキュメントにもある通り、異なるブランチごとにClaude Codeのセッションを起動するためにgit-worktreeを使用しています。今のところ、同時に複数の開発タスクを進めることはありませんが、以下のような場面でその利点を感じています。
- コードレビューの差込があった際、Claude Codeを別セッションで起動してレビューさせておきながら、自身はもともとのタスクを進行する
- 複数の実装方法がありどれがよいか迷っている際、Claude Codeを別セッションで起動してコンペを開催できる
しかし、ブランチ管理がやや煩雑になりルーチンワークも増えるため、開発フローに取り入れるには何らかの工夫が必要になると思います。私の場合はClaude CodeにCLIツールをつくらせましたが、ccmanagerなどを使ってもよさそうです。
# `git worktree add` でディレクトリを作成して、その中に `.gitignore` に記載されたファイルやディレクトリをコピー
$ ccgw create fix-vitest-config
Preparing worktree (new branch 'fix-vitest-config')
HEAD is now at 74c13e8 feat: implement Vitest Browser Mode with Playwright for frontend testing
Found 6 files to copy based on .gitignore rules
Copied: apps/backend/.env
Copied: apps/frontend/next-env.d.ts
Copied: apps/frontend/node_modules/@redocly/openapi-core/tsconfig.tsbuildinfo
Copied: apps/frontend/node_modules/cliui/build/tsconfig.tsbuildinfo
Copied: apps/frontend/node_modules/is-arrayish/yarn-error.log
Copied: apps/frontend/tsconfig.tsbuildinfo
Worktree created successfully at: /Users/yuki/src/worktree/suibachi/fix-vitest-config
実装計画の作成 (/design コマンド)
作業ブランチができたら、実装計画のベースとなる要件定義書を用意します。私の場合はAlfredにスニペットを登録しているので、それをもとにして./tmp/context.md に簡単な要件を書いています。
要件定義書のテンプレート
ここで使用するのは、要件定義書から実装計画を作成する /design コマンドです。引数として任意のファイルパスを受け取れるため、/design ./tmp/context.md のようにして、前の手順で記載した内容をもとに、実装計画を ./tmp/plan.md として出力します。
実装計画の修正 (/revise コマンド)
前の手順にて作成した実装計画ですが、一筆書きで満足いくものができることは滅多にありません。何度かレビューを行い、実装方針の調整やサンプルコードの追加でレールを轢いていきます。difitを起動してみます。
# HEADとmainの差分をすべて表示する
npx difit --mode inline HEAD main
difitのレビュー画面
ローカルサーバーが立ち上がり、ブラウザ上でGtHubに似たUIからレビューができます。実装計画に対するレビューコメントを入力し、「Copy All Propmts」ボタンを押すと以下のようなテキストがクリップボードにコピーされます。
apps/frontend/package.json:L33
test
=====
apps/frontend/package.json:L40
test2
このテキストを ./tmp/context.md に貼り付け (必要に応じて編集) したうえで、実装計画の修正を行う /revise コマンドを実行します。あらかじめ定めた手順に従って実行されるため、plan.md のみを変更することや、difitからコピーしたテキストを入力として期待することなど、特定の用途に特化した具体的な指示を効率的に与えることができます。これが開発フローをスラッシュコマンドという型で表現することの強みです。
満足がいくまで実装計画の修正を繰り返し、次の実装フェーズに入ります。
実装 (/implement コマンド)
実装には /implement コマンドを使用します。実装計画の内容を理解して、受け入れ基準の達成を目標に実装してくれます。特に変わったことはありませんが、Claude Codeの書いたコードは不要なコメント (実装のアウトラインなど) が残ることが多いので、最後にこれらを削除させています。
実装の修正
前のフェーズで実装の大枠はできるため、残りをコミットとレビューで駆動 (レビュー -> 実装 -> コミット) しながら完成に近づけます。実装の修正フェーズで主に使うコマンドとして、質問用の /ask コマンドと指示用の /instruct コマンドを紹介します。
質問 (/ask コマンド)
まずは /ask コマンドですが、planモードを模した回答特化のスラッシュコマンドです。ファイルの編集を行わないことに加え、Web検索の精度を上げるための工夫 (Context 7 MCP Serverを使う/ハルシネーションの対策など) をコンテキストとして与えています。
基本的な使い方として、Claude Codeが出力したコードに対する疑問点を ./tmp/context.md に記載してから実行します。得られた回答結果を踏まえて、後続の指示につなげます。
指示 (/instruct コマンド)
/instruct コマンドは受け取った指示を1件ずつ解釈して、Explore, plan, code, commitをループで回すつくりになっています。指示の単位でコミットが分割されるため、レビュー時に変更を追いやすいです。
レビュー (/review コマンド)
実装が完了したらPull Requestを作成し、レビューを実施します。新しくClaude Codeのセッションを立ち上げ /review コマンドを実行すると、複数のサブエージェントを利用したレビューが始まります。少し時間がかかるため、この間に自分でもセルフレビューを実施することが多いです。
複数のサブエージェントが並列稼働する
各サブエージェントはレビューのスコープを特定の技術領域に限定しており、より専門的なレビューが行えます。親タスクは変更された git diff の結果からどのサブエージェントを呼び出すか決定し、受け取った結果をまとめます。以下のリファクタリング用サブエージェントなどは、変更内容に関わらず必ず呼ばれるようにしました。
レビュー結果として ./tmp/review.md が出力されるため、これを参考にしながら機能を仕上げます。
振り返り (/recap コマンド) とナレッジ管理
タスク完了後、/recap コマンドで実施した内容の振り返りを行います。結果はテンプレート化した内容に従って ./tmp/recap.md として出力されるため、自分でも軽く覚書を書いておきます (後で思い出しやすくなる)。タスクで得られた副産物であるMarkdownファイル (context.md、plan.md、reivew.md、recap.md) はまとめてObsidianにコピーして、今後の学習や開発フローの改善に役立てます。
おわりに
今回はClaude Codeを用いた開発フローの一例を紹介しました。好みのツールや開発環境が人それぞれ違うように、エンジニアの数だけClaude Codeの適した使い方があるのだと思います。記事の中で取り上げたスラッシュコマンドやサブエージェントはGistで公開しているので、何かの参考になれば幸いです。
Discussion