Claude Code ベストプラクティス完全ガイド

目次

  1. Claude Code とは
  2. 環境セットアップ
  3. 機能拡張（bash／MCP／スラッシュコマンド）
  4. 基本ワークフロー
  5. ワークフロー最適化テクニック
  6. ヘッドレスモードと自動化
  7. マルチ Claude 運用
  8. まとめ・段階的導入指針

1. Claude Code とは

  • agentic coding：AI がコード読み書き・テスト・Git 操作を自律実行

  • 低レベル & アンオピニオネイテッド：既存環境に柔軟に溶け込む

  • 主なユースケース

    • ログ解析から修正 PR 作成まで一気通貫
    • 大規模コードマイグレーションの並列自動化

2. 環境セットアップ

2-1. CLAUDE.md を作成

# Bash コマンド
- npm run build   : ビルド
- pytest tests/   : テスト実行

# コードスタイル
- ES Modules を使用
- 関数 snake_case, クラス PascalCase

# ワークフロー
- 変更後は typecheck
- 単体テストを優先
  • ルート／親／子／~/.claude の階層読み込み対応
  • # キーで 動的追記 → ナレッジを継続蓄積

2-2. allowlist（ツール許可リスト）

推奨許可理由

Edit ファイル編集（容易に元に戻せる）
Bash(git commit:*) Git コミット
Bash(npm run:*) NPM スクリプト
  • .claude/settings.json を Git 共有 でチーム統一管理

2-3. GitHub CLI 連携

# macOS
brew install gh
gh auth login

  • Claude が gh を呼び出し Issue/PR 自動化

    • Issue 作成 → 分析 → ブランチ生成 → PR まで全自動

3. 機能拡張

3-1. bash ツールの認識

  1. ツール名と例を説明
  2. --help 実行を指示
  3. CLAUDE.md に登録
# カスタムツール
- deploy-staging --env production
- check-deps

# カスタムツール

- `deploy-staging`: ステージング環境へのデプロイ実行
- `run-migration`: データベースマイグレーション実行
- `check-deps`: 依存関係の脆弱性チェック

# ツール使用例

## 環境別デプロイ

deploy-staging --env production --version v1.2.3

## マイグレーション確認

run-migration --dry-run --target latest

3-2. MCP サーバー

サーバー 用途 設定ファイル
Puppeteer ブラウザ自動操作 .mcp.json
Sentry エラー監視 .mcp.json
Slack 通知 グローバル 
{
 "servers": {
   "puppeteer": { "url": "http://localhost:8123" }
 }
}

テストが終わったら、Slackの #dev-team に「✅ テスト完了しました！」って投稿して。

3-3. カスタムスラッシュコマンド

.claude/commands/fix-github-issue.md

GitHub 課題を分析・修正 : $ARGUMENTS
1. gh issue view
2. 原因分析 → ファイル検索
3. 修正 → テスト → コミット
4. PR 作成

呼び出し例

/project:fix-github-issue 1234

4. 基本ワークフロー

4-1. 探索 → 計画 → 実装 → コミット

  1. 探索：「ログ処理のファイルを読んで、まだ書かないで」
  2. 計画：think hard で詳細プラン作成
  3. 実装：コード生成＋テスト
  4. コミット：自動メッセージ → PR

think → think hard → think harder → ultrathink の順で計算資源増

4-2. TDD 徹底

  1. 期待 I/O を渡し 失敗するテストを生成
  2. テストだけコミット
  3. 実装 → テスト通過まで反復
  4. サブエージェントで 過剰フィット防止レビュー

4-3. UI 開発ループ

  1. モック画像を貼る
  2. Claude がコード作成 → スクショ取得 → 差分確認
  3. イメージと一致するまで反復 → コミット

4-4. Safe YOLO モード

claude --dangerously-skip-permissions
  • 権限確認を全スキップ
  • 推奨：ネット遮断コンテナ内で lint 修正などバッチ実行

4-5. Codebase Q&A

  • 「CustomerOnboardingFlowImpl のエッジケースは？」
  • 「333 行目で foo() ではなく bar() を呼ぶ理由は？」 → Claude が agentic に検索し答える

4-6. Git & GitHub 自動化

  • commit 指示 ➡ 差分解析＋履歴から高品質メッセージ
  • pr 指示 ➡ ブランチ push & PR 作成
  • レビューコメント修正 → 再 push も一括

5. ワークフロー最適化テクニック

5-1. 明確な指示

悪い例 良い例
「テスト追加」 「foo.py にログアウト状態のテストを追加。モック禁止」
「ウィジェット作成」 「HotDogWidget.php のパターンを参考にカレンダーウィジェットを実装。既存ライブラリのみ使用」

5-2. 画像・ファイル・URL 活用

  • cmd+ctrl+shift+4 → ctrl+v で スクショ貼付
  • Tab 補完でファイル指定
  • /permissions add url:docs.example.com でドメイン許可

5-3. コース修正 4 つの技

  1. 計画確認を強制
  2. Esc で実行停止→追記
  3. EscEsc で 履歴編集
  4. 「変更を元に戻してやり直し」

長時間作業後は /clear でコンテキスト整理

5-4. チェックリスト & データ入力

  • lint エラー一覧 → Markdown チェックリスト化 → 項目ごと自動修正
  • 大量ログ：cat error.log \| claude で一括投入

6. ヘッドレスモード & 自動化

claude -p "lint エラーを修正" --output-format stream-json
  • CI/CD・pre-commit・ビルドスクリプトで無人実行
  • --verbose でデバッグ⇔本番切替

6-1. Issue トリアージ例

def on_issue(issue):
    prompt=f"...{issue['title']}..."
    subprocess.run(['claude','-p',prompt,'--allowedTools','Bash(gh:*)'])

6-2. カスタムリンター

  • 変数名の妥当性・誤字・コメント乖離を検出
  • 既存リンターと 段階的品質改善 を実現

7. マルチ Claude 運用

7-1. コード作成 + 検証の分離

  1. Claude A：テスト生成
  2. Claude B：実装
  3. Claude C：レビュー → 修正

7-2. 並列実行戦略

  • 複数チェックアウト：3-4 つのディレクトリ × タブ
  • iTerm2 通知で承認待ち把握

7-3. Git worktree で軽量化

git worktree add ../feature-auth feature-auth
cd ../feature-auth && claude
  • 役割ごとにディレクトリ分離 → コンテキスト混在防止

7-4. ヘッドレス＋ハーネス

ファンアウト

  1. Claude がタスクリスト生成
  2. ループで並列 claude -p "移行 $file"

パイプライン

cat build.log | claude -p "ビルドエラー分析" --json | next_step

8. まとめ & 導入ステップ

  1. CLAUDE.md と allowlist を整備
  2. 小さなタスクで 探索→計画→実装 を試行
  3. MCP／スラッシュコマンドでチーム共有
  4. ヘッドレス化 → CI/CD へ組込み
  5. マルチ Claude で大規模並列 & 品質向上

段階的に適用し、学習コストを抑えながら最大効果を獲得しよう！

Made with Slides.com