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（ツール許可リスト）

推奨許可理由

• .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 サーバー

{
 "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. 明確な指示

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 で大規模並列 & 品質向上

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