Claude Code と ソフトウェア開発の全フェーズ
計画から運用まで、各フェーズで Claude Code をどう使うかの考え方と判断軸
Claude にインタビューしてもらう(推奨パターン)
大きめの機能開発では、最初に Claude へ大まかなアイデアを伝え、詳細を聞き出してもらう。
[ユーザー認証機能を追加したい] と伝えた後: I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.
インタビューが終わったら 新しいセッションを開始 して実装に移る。実装セッションのコンテキストが要件定義の会話で汚染されない。
未知のコードベースに参加するとき
既存プロジェクトに参加した直後は、Claude Code をシニアエンジニアへの質問相手として使う。
give me an overview of this codebase
アーキテクチャ・パターン・データモデルを質問する
look through ExecutionFactory's git history and summarize how its api came to be
「なぜこうなっているか」を git 履歴から読み解く
/init # セッション内で実行。CLAUDE.md が既にあれば上書きせず改善案を出す
プロジェクト構造を解析して CLAUDE.md のたたき台を自動生成
Explore → Plan → Implement → Commit の 4 ステップ
- Explore(探索): Plan mode に入り、Claude にファイルを読ませて現状を把握させる。ファイルは一切編集されない。
claude --permission-mode planまたは セッション中にShift+Tab - Plan(計画): 実装プランを作らせる。
Ctrl+Gでプランをテキストエディタで直接編集できる。
「What files need to change? Create a plan.」 - Implement(実装): Plan mode を解除してコーディングさせる。プランに沿って進んでいるか確認しながら進める。
- Commit: 実装が終わったら commit と PR を作らせる。
CLAUDE.md にはリポジトリから読み取れない判断を書く
リポジトリを読めばわかる構成やファイル配置は書かない(Claude が自分で読む)。書くのは、読んでもわからない決定(使用ライブラリの選択・禁止事項)・紛らわしい箇所・確認用のコマンド。公式は1ファイル200行未満を勧めている。毎セッションで Claude が読み込むため、「毎回同じことを説明する」手間がなくなる。
# CLAUDE.md の例 # Code style - Use ES modules (import/export), not CommonJS (require) - Prefer functional components over class components # Architecture - API calls go through src/api/ — never fetch() directly in components - State management: Zustand only (no Redux)
調査をサブエージェントに委ねる
広い範囲のコード検索は、Claude が組み込みの Explore エージェントに自分で委ねる。サブエージェントを明示的に使う価値があるのは、並列化・長い出力の隔離・独立したレビューのとき(そのぶんトークンはかかる)。最近のモデルはコンテキストが大きく圧縮も自動なので、コンテキストの枯渇を防ぐ目的だけで使う必要は少なくなっている。
Use a subagent to investigate how our auth system handles token refresh, and whether we have any existing OAuth utilities.公式: Plan before editing
プロンプトに具体的なコンテキストを与える
| 戦略 | 曖昧な指示(Bad) | 具体的な指示(Good) |
|---|---|---|
| スコープを絞る | "add tests for foo.py" |
"write a test for foo.py covering the case where the user is logged out. avoid mocks." |
| 既存パターンを参照 | "add a calendar widget" |
"look at HotDogWidget.php for the pattern, then implement a calendar widget following it" |
| 症状と場所を伝える | "fix the login bug" |
"users report login fails after session timeout. check src/auth/, write a failing test, then fix it" |
@ でファイルを参照する
Explain the logic in @src/utils/auth.js What's the structure of @src/components?
並行作業: ワークツリーで複数セッション
「フィーチャーAを開発しながら、別のセッションでバグ修正」をファイルの衝突なしにできる。
claude --worktree feature-auth # ターミナル1 claude --worktree fix-payment-bug # ターミナル2(別ブランチ・別チェックアウト)
auto mode で割り込みを減らす
対話型のターミナル・VS Code のセッションは既定で auto mode で始まる。-p の非対話実行は既定が Manual なので、スコープが明確なタスクでは --permission-mode auto を付ける。分類器は、依頼の範囲を超える操作・見覚えのないインフラへの操作・読み込んだ内容に誘導されたように見える操作をブロックする(会話で示した「push しない」なども考慮される)。auto mode は確認を減らすが、安全を保証するものではない。
claude --permission-mode auto -p "fix all lint errors"
スキルで繰り返しワークフローを標準化
チームや個人で何度も使う手順は .claude/skills/ にスキルとして定義する。
# .claude/skills/fix-issue/SKILL.md --- name: fix-issue description: Fix a GitHub issue end-to-end disable-model-invocation: true --- 1. Use `gh issue view` to get details 2. Search relevant files 3. Implement fix with tests 4. Create a PR
コンテキスト管理の判断基準
- 関係ないタスクに切り替えるときは
/clearでリセット - 同じ修正を 2 回以上やり直したら
/clearして新しいプロンプトで再スタート /rewind(または空のプロンプトで Esc を2回)で前のチェックポイントに戻れる。Bash コマンドだけで変更したファイルは戻らない- 脇道の質問は
/btwで聞く(回答がコンテキストに残らない)
検証手段を渡す(最重要)
| 検証の種類 | プロンプト例 |
|---|---|
| テストスイート | "write tests for the auth module, run them, and fix any failures" |
| ビルド終了コード | "the build fails with [error]. fix it and verify the build succeeds. fix the root cause, don't suppress the error" |
| UI のスクリーンショット比較 | "[デザイン画像を貼る] implement this design. take a screenshot and compare it to the original. fix differences." |
| スクリプトで fixture と diff | 出力を fixture と比較するスクリプトを渡す |
検証をどこで実施するか選ぶ
- プロンプト内: 1 回のメッセージでテスト実行 + 修正を依頼する(最もシンプル)
- /goal 条件: 目標条件を設定し、条件を満たすまで Claude が繰り返す
- Stop hook: ターンが終わるたびにテストスクリプトを実行。失敗すると Claude が続ける(完全自律)
- サブエージェントによる二次検証: 実装したエージェントとは別のエージェントがレビュー(バイアスなし)
テストファーストパターン
実装前にテストを書かせ、別のセッションで実装させる手法も有効。
# セッション A: テストを書く "find functions in NotificationsService.swift that are not covered by tests, then add tests for edge cases" # セッション B: テストを通す実装を書く (新しいセッションで @テストファイルを渡す)
Writer / Reviewer パターン(公式推奨)
2つのセッションで役割を分担する。
| セッション A(Writer) | セッション B(Reviewer) |
|---|---|
"Implement a rate limiter for our API endpoints" |
(実装後) |
| — | "Review @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with existing patterns." |
"Here's the review: [Session B output]. Address these issues." |
— |
/code-review スキル(組み込み)
Claude Code 組み込みの /code-review コマンドは、現在の diff に対してサブエージェントが独立してバグチェックを行い、結果をセッションに返す。
/code-review # 現在の diff をレビュー /code-review ultra # マルチエージェントクラウドレビュー(深い)
CI での自動レビュー
PR が開かれたときに自動でコードレビューするには、GitHub Actions 統合か、マネージドサービスの GitHub Code Review を使う。下の例は CI のスクリプトから claude -p を直接呼ぶ方法。
git diff main --name-only | claude -p \ "review these changed files for security issues"
レビューの指示精度を上げる
レビュアーに「ギャップを探せ」と指示すると問題がなくても何か報告する。正確さや要件に影響するものだけを報告させる。
Use a subagent to review the rate limiter diff against PLAN.md. Check that every requirement is implemented, listed edge cases have tests, and nothing outside scope changed. Report gaps that affect correctness, not style preferences.公式: Review against your spec
claude -p は Unix コマンドとして他のツールと連携できる。
PR 作成・コミット
claude "commit my changes with a descriptive message" claude "create a pr"
claude --from-pr <number> で、その PR に紐づくセッションに絞ったセッション一覧が開く(Claude が gh pr create などで PR を作った場合に紐づく)。
CI / CD に組み込む(非インタラクティブモード)
claude -p で Claude をスクリプトやパイプラインに組み込める。
# ログ異常の検知 tail -200 app.log | claude -p "Slack me if you see any anomalies" # CI での翻訳 claude -p "translate new strings into French and raise a PR" # セキュリティチェック git diff main --name-only | claude -p "review for security issues" # JSON 出力(パーサー向け) claude -p "List all API endpoints" --output-format json
定期タスクの自動化(スケジュール実行)
| 方法 | 実行場所 | 向いている用途 |
|---|---|---|
| Cloud scheduled tasks(旧 Routines) | Anthropic クラウド(CLI では /schedule で作成。API 呼び出しや GitHub イベントでも起動できる) |
PC がオフでも動かしたいタスク(毎朝 PR レビュー・週次依存関係チェック等) |
| Desktop scheduled tasks | 自分のマシン | ローカルファイルや未コミット変更へのアクセスが必要なタスク |
| GitHub Actions | CI パイプライン | PR オープン・push などリポジトリイベントに連動するタスク |
| /loop | 現在の CLI セッション | セッション中の短期ポーリング |
スケジュールタスクのプロンプトの書き方
例: 「Review open PRs labeled `needs-review`, leave inline comments, and post a summary in #eng-reviews Slack channel.」
どこからでも作業できる
- Remote Control: スマホ・タブレット・ブラウザから、ローカルで動いているセッションを操作・承認(Pro / Max / Ultra / Team / Enterprise、API キー認証では不可)
- Web / iOS app: ブラウザやスマホで長時間タスクを開始し、ターミナルで
claude --teleportして引き継ぐ - Slack:
@Claudeにバグレポートをメンションすると PR が返ってくる
旧版の公式 best-practices にあった「避けるべきパターン」を元に整理したもの。現行版では「Steer the session」(修正が2回うまくいかなければ /clear してプロンプトを書き直す)と「What you can stop doing」(古くなった助言)に引き継がれている。
| パターン名 | 何が起きるか | 対策 |
|---|---|---|
| キッチンシンクセッション | 1つのタスクをしながら関係ない質問を混ぜる → コンテキストが無関係な情報で汚染される | 関係ないタスクへの切り替えは /clear でリセット |
| 繰り返し修正ループ | 同じ間違いを 2 回以上修正 → コンテキストが失敗した試みで汚染 | 2 回失敗したら /clear → 学んだことを含めたより具体的なプロンプトで再スタート |
| 肥大化した CLAUDE.md | CLAUDE.md が長すぎて重要な指示が無視される | 「これがないと Claude が間違えるか?」→ NO なら削除。フック化できるものはフックに移す |
| 信頼して検証しないギャップ | もっともらしい実装がエッジケースを処理していない | 常に検証手段(テスト・スクリプト・スクリーンショット)を渡す |
| 無限探索 | 「調査して」とだけ指示して数百ファイルを読まれる → 不要なコンテキストに料金がかかる | 調査の範囲と目的を絞る。/usage で消費を確認し、区切りで /clear や焦点を指定した /compact を使う |
| フェーズ | Claude Code の使い方 | 核心の判断基準 |
|---|---|---|
| 計画・要件定義 | インタビュアー / 質問相手 | SPEC.md ができるまでコードを書かせない |
| 設計 | Plan mode で探索・プラン生成 | 差分を 1 文で説明できないなら Plan mode を使う |
| 実装 | 具体的なコンテキストを与えて実装 | コンテキストが汚れたら /clear、2 回失敗したら再スタート |
| テスト | 検証手段を渡して自律ループ | 「言葉で成功を報告」ではなくエビデンスを出させる |
| レビュー | 別セッション・サブエージェントでレビュー | 実装したエージェントにレビューさせない |
| デプロイ・運用 | 非インタラクティブ・スケジュール実行 | 自律タスクは「成功とは何か」「結果をどこへ」を明示 |