Claude Code ベストプラクティスの和訳と要約
概要
Claude Code は、LLM を CLI から“エージェント”として扱い、
コード編集・解析・テスト・Git操作・自動化まで担わせるためのツール。
強力だが、
事前設定・ルール化・タスク分解がないと精度が落ち、差分ノイズも増える。
そのため「環境構築」「操作ガイド」「反復手順」を整えることが重要。
1. セットアップ
✅ CLAUDE.md を置く
Claude が参照するプロジェクトルールファイル。
例:
- プロジェクト概要
- 開発手順（setup/build/test/deploy）
- コーディング規約
- よく使う CLI コマンド
- ディレクトリ構造説明
- 禁止事項（勝手に一括 rename しない等）
理由:
ルールを繰り返し説明する必要がなくなる。
コンテキスト不確定による誤変更が減る。
→ 一貫性と再現性が上がる
✅ ツール権限を明示的に管理
Claude が操作できるツールを制御
- ファイル編集
- bash コマンド
- git 操作
- npm / pip などのパッケージ操作
~/.claude/settings.json で設定可能。
理由:
AI が不用意に破壊的変更（例: rm -rf, schema drop）をしない。
安全性と制御性の担保
✅ GitHub CLI 連携
gh コマンド経由で
- PR 作成
- Issue triage
- レビュー対応
が可能になる。
理由:
AIに Git+GitHub のフル操作パイプラインを与える＝
自動 PR/自動修正ワークフローが構築できる
2. Claude にツールを学習させる
✅ Bash / CLI ツールを明示
実例提示 → help参照 → CLAUDE.md に追記
理由:
曖昧なツール操作は誤解が出るため、
再利用 “指示パターン”を固定する
✅ MCP サーバを活用
例: Puppeteer, Sentry, DBクライアント
理由:
Claude をIDE + オペレーションレイヤーに変える
→ 高度作業も自動化
✅ カスタムスラッシュコマンド
.claude/commands/*.md
例 /bugfix ISSUE_ID
理由:
頻出タスクをショートカット化し、反復を速くする
3. ワークフロー設計
✅ 探索 → 計画 → 実装 → コミット
悪い例:「これ直して」→いきなり変更
良い例:
- 関連コードを読ませる
- 変更方針を文章化
- ファイル変更
- diff 確認
理由:
LLMは“すぐ書く”がデフォルト
→ 先に方向性を固定することで誤実装を回避
✅ TDD 型運用が効果的
- テストを書く
- 失敗を確認
- 実装
- 再実行
理由:
AI の“表面的成立”を防ぎ、
実行可能品質に寄せる
✅ UIループ: コード→スクショ→修正
視覚情報でチェック
理由:
レイアウト/余白/崩れは文字説明より早く発見
✅ Safe YOLO モード
--dangerously-skip-permissions
使う時:
- 一括rename
- 大量ファイル生成
- scaffold 出力
理由:
一括作業は安全判断が不要 → スピード最優先
（ただし隔離環境で）
4. 操作コツ
✅ 指示は明確に
NG:
APIの処理を改善
OK:
error時は retry (3回)
timeout=5s
log を構造化出力
理由:
曖昧だとLLM は“もっともらしい別物”を作る
✅ 対象ファイルを限定
- 参照するファイル明示
- 読む→計画→編集
理由:
大規模コードベースでは文脈誤推論が起こる
✅ /clearで定期リセット
理由:
長時間セッションは“意図汚染”が溜まり精度低下
✅ チェックリスト活用
例: 大規模リファクタ
[ ] 型改善
[ ] 例外処理
[ ] ログ統一
[ ] Lint fix
理由:
LLMはタスクが散る → 構造で縛る
5. 自動化
✅ ヘッドレス利用
- CI コメント生成
- PR ラベル付け
- 静的分析＋AI lint
- 破壊的差分検出
理由:
チームの継続的 AI 補助を実現
6. 複数 Claude 戦略
✅ 実装 Claude + レビュー Claude
人間チーム同様、役割分離
理由:
Self‑critique より役割分離の方が精度が高い
✅ 複数ワークツリー
別ブランチ/フォルダで複数タスク同時
理由:
LLM の“コンテキスト上書き”を避ける
まとめ
| 原則 | 理由 |
|---|---|
事前設定 (CLAUDE.md) |
指示の永続化、品質安定 |
| ツール権限制御 | 破壊的操作防止 |
| 計画→実装→確認フロー | LLM の暴走防止 |
| TDD & diff 文化 | 実行品質担保 |
| UI画像反復 | 精度向上 |
| 多Claude構成 | 役割分離で性能上昇 |
| 自動化パイプライン | 継続改善と再現性 |
AI を
**「コマンド応答型」→「開発プロセスの一部」**へ拡張する思想が重要。
Discussion