Claude Code マスターガイド

claude
/init
/context

# プロジェクトの基本ルールを用意
touch CLAUDE.md

# 最初の依頼は「実装」ではなく「現状把握」
> このリポジトリの構成、ビルド方法、主要な制約を要約して
> CLAUDE.md の初稿を作ってください

# 悪い依頼
ログイン機能を作って

# 良い依頼
Next.js 14 / TypeScript / App Router 構成です。
メール + パスワードのログイン画面を設計してください。
まず以下を返してください。
1. 必要ファイル一覧
2. 画面の状態設計
3. API 契約
4. セキュリティ上の注意点

コードはまだ書かず、計画だけ出してください。

1. Explore
この機能に関係するファイルと既存フローを調査して要約してください。

2. Plan
変更方針を 5 項目以内で提示してください。まだコードは書かないでください。

3. Implement
承認した差分だけを実装してください。変更ごとに理由を短く添えてください。

4. Commit
実行した確認項目、残リスク、次にやるべきことをまとめてください。

# Stack
- Next.js 14 App Router
- TypeScript strict
- Tailwind CSS

# Commands
- dev: npm run dev
- build: npm run build
- check: npm run build

# Conventions
- server component を優先し、client は必要箇所だけに限定
- 既存 UI では命名を変えない
- API route では zod 相当の入力検証を必ず通す

# Git
- branch: feature/*, fix/*
- commit: Conventional Commits

# Gotchas
- 画像 URL は next.config.mjs の remotePatterns を確認
- metadata は server component 側で定義する

# Current Goal
支払い画面の API 契約を確定し、UI 実装へ渡す

# What Changed
- CheckoutForm の state を分割
- /api/checkout のレスポンス型を更新

# What Worked
- 税額計算のロジックは unit test で固定化済み

# What Failed
- 既存の coupon 処理と新しい tax フローが衝突

# Next Step
1. coupon 適用順を仕様決定
2. contract test を追加
3. UI 実装へ着手

目的:
[この変更で達成したいこと]

前提:
- Stack: [例: Next.js 14 / TypeScript / Tailwind]
- 変更してよい範囲: [ファイル or ディレクトリ]
- 変更してはいけない範囲: [例: DB schema, billing logic]

依頼:
1. まず現状を調査して要約
2. 次に実装計画を 5 項目以内で提示
3. 承認後に最小差分で実装
4. 最後に確認結果と残リスクを列挙

完了条件:
- [受け入れ条件 1]
- [受け入れ条件 2]
- [受け入れ条件 3]

役割:
あなたは Research Agent です。

目的:
既存の認証フローを調査し、変更に必要な制約だけを抽出してください。

入力:
- @CLAUDE.md
- @src/auth/*
- @middleware.ts

出力形式:
1. 現状フロー
2. 変更時のリスク
3. 触るべきファイル
4. 触ってはいけない領域

禁止:
コード変更はしない

# TEAM-CONTRACT.md
## Shared Goal
顧客向け onboarding フローを 2 週間で公開する

## Shared Interfaces
- shared/types/onboarding.ts
- docs/api/onboarding.md

## Roles
- Researcher: 既存フロー調査、外部仕様確認
- Architect: 状態遷移図と API 契約定義
- Builder: UI / API 実装
- Reviewer: セキュリティと回帰確認

## Merge Rules
- shared interface 変更時は Reviewer 承認必須
- nightly autonomous run 前に checkpoint commit を作成

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "npm|pnpm|yarn",
        "command": "scripts/verify-package.sh"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "edit|write",
        "command": "npm run build"
      }
    ],
    "Stop": [
      {
        "command": "scripts/write-handoff.sh"
      }
    ]
  }
}

skills/
  cro-methodology/
  frontend-design/

scripts/
  verify-package.sh
  write-handoff.sh

mcp/
  context7
  postgres
  playwright

ルール:
- 再利用する知識は skills
- ローカルの決まり切った処理は scripts
- 外部接続は mcp

PACKAGE="$1"

echo "1. 公開レジストリで存在確認"
echo "2. Publisher / Owner を確認"
echo "3. 最終更新日と star / download 傾向を確認"
echo "4. 既知 CVE を確認"

npm view "$PACKAGE" name version repository
npx semgrep --config p/owasp-top-ten .

git switch -c feature/checkout-tax-fix
git status

# ここで Claude に計画を出させる

git add .
git commit -m "chore: checkpoint before autonomous refactor"

# 実装後
git add .
git commit -m "feat: separate coupon and tax calculation"
git show --stat --summary

/init             # プロジェクト分析と CLAUDE.md 草案
/context          # コンテキスト状態の確認
/compact <hint>   # 会話を圧縮して主題を残す
/clear            # 新しいタスクへ完全切替
/rewind           # 以前のチェックポイントへ戻す
/rename           # セッション名を付ける
claude --resume   # 過去セッションを選んで再開
claude --continue # 直近セッションをそのまま継続

次の条件で回答してください。
- 既存コードを全面的に書き直さない
- 変更が必要なファイルだけ列挙
- 各ファイルごとに「何を変えるか」と「なぜか」を 2 行で説明
- 実装後に、不要なら削れるコードも指摘する

このタスクが Claude Code に向いているか判定してください。
以下の観点で 5 段階評価してください。
1. 要件の明確さ
2. 検証のしやすさ
3. 失敗時の被害
4. 既存パターンの有無
5. rollback の容易さ

最後に Go / Maybe / No-Go を返してください。

Week 1
- sessions: 18
- long sessions (>30 min): 6
- /compact used: 4
- heavy tasks: refactor, review, docs

月末に見るもの
- セッション回数
- 長時間セッション比率
- 複数エージェント利用の有無
- 課金に見合う成果が出たか

[作りたいもの] を作ります。
技術スタックは [stack] です。

まず以下だけ返してください。
1. 必要ファイル一覧
2. 画面 / API / 状態の設計
3. 最短で MVP にするための削減案
4. 実装順序
5. テスト / 検証方法

不具合を直す前に、次の順で返してください。
1. 再現条件
2. 原因候補を 3 つ
3. それぞれの確認方法
4. 最短で切り分ける順序

コード修正はまだしないでください。
まず「どの仮説を潰すか」だけ決めたいです。

# Session A: Writer
@CLAUDE.md @src/checkout/*
税額計算の仕様に合わせて最小差分で実装してください。
最後に reviewer 向けの確認観点を 5 つ書いてください。

# Session B: Reviewer
@CLAUDE.md @git-diff
この差分をレビューしてください。
観点は以下です。
1. 税額計算の境界値
2. coupon 適用順
3. 回帰リスク
4. 型安全性
5. テスト不足

1. よく書かれた CLAUDE.md
2. 役割が明確なプロンプト
3. タイミングの良い /compact

この 3 つが揃うと、
- 再説明が減る
- 方向違いの実装が減る
- 長い会話の品質劣化を防げる

私は開発初心者です。
作りたいものは [例: 予約フォーム付きの小さなサイト] です。

難しい言葉を減らして、次の順で手伝ってください。
1. 何を作るかを一緒に整理
2. 必要なファイルを作成
3. 1 画面ずつ確認しながら実装
4. 毎回「次に私が確認すること」を短く教える

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "readonly connection string"
      }
    }
  }
}

この PR を次の観点でレビューしてください。
1. セキュリティ
2. 性能
3. 保守性
4. テストカバレッジ
5. ドキュメント不足

各観点を 1-5 点で採点し、
- 問題箇所
- 根拠
- 直し方
- merge 可否
を返してください。