私の Claude Code ベストプラクティス

Claude Code を使った AI プログラミングを継続的に行う中で、効率的な開発ワークフローをまとめました。この Claude Code ベストプラクティスは、Session 管理、プランニングモード、バージョン管理、品質保証、コードレビューなどの核心的なプロセスをカバーしています。

Claude Code の核心テクニック

1つの Session で1つのタスクを完了し、各タスク完了後に /clear でコンテキストの圧縮を避けます。
単一ファイルの簡単な修正以外は、すべてプランモードを使用します。さらに複雑な場合はスペック駆動のアプローチを使います。
think、think hard、ultrathink を使って、Claude に複雑な問題をより深く考えさせます。
変更のたびに Git で管理し、各タスクごとにブランチを作成して、完了後にマージします。
Claude Code Hooks や pre-commit などのツールチェーンでコード品質を保証し、Claude にフォーマットチェックなどを任せません。
数回のやり取りで問題が解決しない場合は、新しい Session を開いてやり直します。
タスクに大きな問題が発生した場合は、git checkout . で前回のコミット状態に戻してやり直します。
worktree を使って複数のタスクを同時に処理し、Claude Code にマージさせます。ただし、より多くの場合は複数のウィンドウを開いて複数のプロジェクトを並行処理します（例：同じ機能のフロントエンドとバックエンド）。
Claude Code はプログラミングだけでなく、情報の整理や収集にも活用できます。
claude --dangerously-skip-permissions で全権限を付与しています。今のところ問題に遭遇したことはありません。
各タスク完了後に新しいウィンドウを開き、コードレビュー用の Subagent でコードレビューを行います。

Claude Code スラッシュコマンド完全ガイド

Claude Code のスラッシュコマンドは、プログラミング効率を高めるための重要なツールです。ここでは、Claude Code で最もよく使われるスラッシュコマンドとその使い方を紹介します。

`/init`

CLAUDE.md ファイルを初期化し、プロジェクトの背景、要件、制約などを記録します。
私はプロジェクトがある程度進んでからこのコマンドを使うようにしています。

`/memory`

個人またはプロジェクトの汎用メモリを表示・管理します。つまり CLAUDE.md ファイルの内容を管理します。
ターミナルで # から始めることで素早く呼び出せます。
開発中に汎用的な制約として使えると思った内容があれば随時追加します。変更後に Claude に追加させるだけでOKです。

`/add-dir`

指定したディレクトリ内のすべてのファイルを Claude のコンテキストに追加し、複数プロジェクトの連携を実現します。
個人的にはターミナルでパスをコピーして Claude に見てもらうようにしています。このコマンドはあまり使いません。こうすると強制的に見させることができるからです。
複数プロジェクトの連携が多い場合は、CLAUDE.md にパスを直接書いておくと、/clear の後も記憶が保持されます。

`/clear`

現在の Session のコンテキストをクリアし、新しいタスクを開始します。
タスク完了のたびにこのコマンドを使い、コンテキストが大きくなりすぎて自動圧縮されるのを防ぎます。
情報を失うことを心配する必要はありません。重要な情報は CLAUDE.md に書くべきです。1つの Session は1つのタスクのためのものです。

`/compact`

現在の Session のコンテキストを圧縮し、要点を保持しながら現在のタスクを続行します。
基本的に自分から使うことはありません。圧縮すると詳細情報が失われ、後続のレスポンス品質に影響するからです。
タスクが大きすぎる場合は、コンテキストを圧縮するのではなく、タスクを分割すべきです。

`/mcp`

MCP の制御と管理を行います。
最もよく使う MCP は Context7 と chrome-devtools-mcp です。

`/agent`

Subagent の使用を表示・管理します。
GitHub 上の Agent リポジトリで定義済みの Agent を使用できます。
最もよく使う SubAgent は /code-review-ai:ai-review で、主にコードレビューに使用します。

`/hooks`

Claude Code Hooks の表示と管理を行います。

例えば、コード完了後に自動でフォーマットを実行する設定です。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && make format",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

例えば、メッセージ完了後のシステム通知の設定です。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title '🚀 通知' -subtitle '需要你的指令' -message 'Claude 正等待下一步操作' -sound 'Pop' -execute '/usr/local/bin/code /Users/wyx/code'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title '✅ 通知' -subtitle '任务已完成' -message '当前任务已完成' -sound 'Pop' -execute '/usr/local/bin/code /Users/wyx/code'"
          }
        ]
      }
    ]
  }
}

`/tasks`

バックグラウンドタスクの一覧表示と管理を行います。! で素早くトリガーできます。
手動で使うことはほとんどありません。新しいウィンドウを開いて実行状況を確認し、エラーを手動でコピーする方が好みです。

`/export`

現在の Session の内容をエクスポートします。
他の AI ツールで内容を分析する必要がある場合に使用します。エクスポートして他の AI ツールに貼り付けることができます。

カスタムコマンドの共有

Claude Code はカスタムコマンドをサポートしています。md ファイルを作成して ~/.claude/commands/ ディレクトリに配置するだけです。

`/commit`

# Commit Message 生成規範

你是一位资深的软件工程师和代码审查专家，专注于生成高质量、符合 Git Conventional Commits 规范的提交信息，并且执行git add和git commit命令，不执行git push操作。

## 核心任务

根据用户提供的代码变更（diff）或暂存区内容，执行以下分析并生成提交信息：

1. **原子性分析 (Atomic Check)**:
    * 首先分析代码变更是否过于复杂或包含多个不相关的改动。
    * 如果包含多个逻辑独立的改动（例如同时修改了 UI 和后端 API，且两者无直接依赖），**请优先建议用户拆分提交**，并给出拆分建议。
    * 如果改动是原子的（Atomic），则继续生成提交信息。

2. **生成提交信息 (Commit Generation)**:
    * 严格遵循 **Conventional Commits** 格式。
    * **语言要求**: 提交信息的标题（Subject）和正文（Body）必须使用**中文**。
    * **最后说明**：这个commit是谁提交的，例如"由Claude AI助手生成"。

    * **格式结构**:

        ```text
        <emoji> <type>(<scope>): <subject>

        <body>
        ```

## 详细规则

### 1. Header 格式

* **Emoji**: 根据改动类型选择最准确的表情符号（见下表）。
* **Type**: 使用标准的英文类型（如 `feat`, `fix`），保持工具兼容性。
* **Scope** (可选): 用英文括号包裹，简短说明改动影响的模块或文件名。
* **Subject**: 简练的**中文**描述，不超过 50 个字符，不要以句号结尾。

### 2. Body 内容 (至关重要)

正文部分必须清晰分段，包含以下两部分：
* **What (做了什么)**: 使用无序列表 (`- `) 详细列出具体的代码改动点。
* **Why (为什么做)**: 解释改动的动机、解决的问题或带来的优化。

### 3. 类型映射表 (Type/Emoji Mapping)

| Type | Emoji | 含义 | 适用场景 |
|:---|:---|:---|:---|
| **feat** | ✨ | 新功能 | 引入新特性或功能 |
| **fix** | 🐛 | 修复 Bug | 修复生产环境或开发中的错误 |
| **docs** | 📝 | 文档 | 仅修改文档 (README, API doc) |
| **style** | 💄 | 格式/样式 | 代码格式化、UI 微调 (不影响逻辑) |
| **refactor** | ♻️ | 重构 | 代码结构调整，既不修 Bug 也不加功能 |
| **perf** | ⚡️ | 性能 | 提升性能的改动 |
| **test** | ✅ | 测试 | 增加或修改测试代码 |
| **build** | 📦 | 构建 | 构建系统或外部依赖变动 |
| **ci** | 👷 | CI/CD | CI 配置文件或脚本变动 |
| **chore** | 🔧 | 杂项 | 其他琐碎改动 |

## 输出示例

**输入**: 用户修改了登录逻辑，增加了验证码校验，并修复了一个空指针报错。

**输出**:

✨ feat(auth): 增加登录时的验证码校验机制

- 在 `LoginController` 中集成验证码服务
- 更新前端登录表单，增加验证码输入框
- 🐛 fix: 修复 `UserParams` 解析时的空指针异常

**原因 (Why):**
为了防止暴力破解攻击，提高账户安全性，因此引入强制验证码流程。同时顺带修复了测试中发现的潜在崩溃问题。

---

**注意**:
*   你可以执行提交commit的命令，但是最终的git push操作由用户执行，因为最终的提交信息需要用户确认。
*   最终输出只需包含建议的 Commit Message 内容，不需要额外的寒暄。

***

おわりに

現時点でのこれらの Claude Code ベストプラクティスは、主にバックエンド開発の経験に基づいています。フロントエンド部分の最適化戦略はまだ模索中です。

AI 支援プログラミングにおけるコード品質の確保についてさらに詳しく知りたい方は、「AIプログラミング品質管理：コード品質を確保する5つの防衛線」をご参照ください。Claude Code プログラミングにおける5層の品質防衛システムについて詳しく解説しています。

これらの Claude Code のテクニックとプラクティスは常に進化しており、この記事も継続的に更新していきます。

「Claude システムアーキテクチャ徹底解説」 -- Claude Code の背後にある MCP、Skills、Subagents、Hooks などのコンポーネントを深く理解する
「Claude Skills とは」 -- Skills のコア原理と応用シーン
「Claude Subagent 完全ガイド」 -- Subagent の使い方とカスタマイズをマスターする
「Eclipse から Zed へ：ある開発者のエディタ進化史」 -- 私の開発ツールの変遷