メインコンテンツへ移動
AIチュートリアル

プロジェクトルール、エージェント、フック、MCP、CIを使いこなすClaude Code

Claude Codeのインストール方法、リポジトリのスターターキットの適用、プロジェクトコンテキストの管理、信頼性の高いワークフローの作成、権限設定、スキル、サブエージェント、フック、MCP、ヘッドレスモード、並列ワークツリーの活用方法を学びます。

約21分で読了
プロジェクトルール、エージェント、フック、MCP、CIを使いこなすClaude Code

Claude Code PROコースで提供されるもの

Claude Code PROは、Claude Code向けのロシア語による実践コース兼設定キットです。インストールとプロンプト作成から、チーム全体の設定、再利用可能な自動化、外部連携、CIワークフローまで段階的に学べます。

リポジトリには、12の学習モジュール、8つの実践ラボ、プロンプトライブラリ、プラグインの例、GitHub Actionsワークフロー、チートシート、FAQ、すぐにインストールできるスターターキットが含まれています。スターターキットには、8つのスキル、5つのサブエージェント、4つのフック、ルール、ステータスライン、出力スタイルが含まれます。

このチュートリアルでは、既存のプロジェクトで設定を使い始められるよう、リポジトリの主要なワークフローをまとめています。元のコースはロシア語で書かれていますが、以下の手順は英語で説明されています。

Claude Codeの仕組みを理解する

Claude Codeは、従来のオートコンプリートツールではなくエージェントです。目的を与えると、ファイルの確認、リポジトリの検索、コードの編集、コマンドの実行、結果の確認を行えます。一般的なループは次のとおりです。

  1. プロジェクトの指示、ファイル、検索結果、コマンド出力からコンテキストを収集する。
  2. 必要な変更を計画する。
  3. ファイルを編集するか、ツールを実行する。
  4. テスト、リンター、ビルド、その他のチェックを実行する。
  5. チェックに合格するか、追加の入力が必要になるまで繰り返す。

最も重要な役割は、明確な目標を示し、関連するコンテキストへClaudeを導き、制約を伝え、成功を検証する方法を定義することです。

便利なプロンプトの公式は、目標 + 調査場所 + 制約 + 検証方法です。

Claude Codeとスターターキットをインストールする

ステップ1: Claude Codeをインストールする

macOS、Linux、またはWindows Subsystem for Linuxでは、公式のインストールスクリプトを使用します。

curl -fsSL https://claude.ai/install.sh | bash

READMEにはnpmを使ったインストール方法も記載されています。

npm install -g @anthropic-ai/claude-code

ステップ2: コースのリポジトリをクローンする

git clone https://github.com/justxor/claude-code-pro-course.git

ステップ3: スターターキットをプロジェクトにインストールする

付属のインストーラーを実行し、対象プロジェクトのパスを指定します。

bash claude-code-pro-course/install.sh ~/path/to/my-project

これにより、リポジトリの再利用可能なClaude Code設定をプロジェクトで利用できるようになります。キットは複数の設定コンポーネントをインストールするため、バージョン管理にコミットする前に、適用された変更を確認してください。

ステップ4: Claude Codeを起動する

cd ~/path/to/my-project
claude

セッション内で現在のコンテキストを確認し、スターターキットのオンボーディングスキルを実行します。

/context
/onboard

/contextは、コンテキストウィンドウを消費している要素を表示します。/onboardは、インストールされたスキルを使ってプロジェクトの概要を提示します。

Claude Codeの設定を整理する

このコースでは、設定をユーザー、プロジェクト、ローカルのスコープに分けています。

  • ユーザー設定:個人用の指示、設定、スキル、エージェント、出力スタイルなど、~/.claude/以下のファイル。
  • プロジェクト設定:CLAUDE.md、.claude/rules/、.claude/settings.json、プロジェクトスキル、プロジェクトエージェント、.mcp.jsonなどの共有ファイル。
  • ローカル設定:CLAUDE.local.mdや.claude/settings.local.jsonなど、マシン固有のファイル。チーム設定として共有すべきではありません。
  • プラグイン:複数のリポジトリに配布できる、スキル、エージェント、フック、MCP設定をまとめたパッケージ。

適切な設定の仕組みを選ぶ

  • プロジェクトの知識やコーディングルールには、CLAUDE.mdまたは.claude/rules/を使用します。
  • 権限設定を使って安全なコマンドを許可し、機密性の高い操作では確認を求め、危険なアクセスを拒否します。
  • 再利用可能な手順やプロンプトにはスキルを使用します。
  • 専門性や分離されたコンテキストウィンドウが必要なタスクにはサブエージェントを使用します。
  • 操作を常に実行する必要がある場合はフックを使用します。
  • GitHub、ブラウザー、データベースなどの外部システムとの接続にはMCPを使用します。
  • 他のリポジトリやチームメンバーに完全な設定を配布するにはプラグインを使用します。
  • 人手を介さない実行には、claude -p、GitHub Actions、またはAgent SDKを使用します。

役立つCLAUDE.mdを作成する

CLAUDE.mdはプロジェクトの記憶として機能します。Claude Codeは/initで初期バージョンを作成でき、/memoryでメモリを編集できます。このファイルは短く具体的に保ち、コマンド、アーキテクチャの境界、コーディング規約、明確な制約を記載してください。

以下はコースをもとにした例です。

# Project: Next.js and PostgreSQL store

## Commands
- npm run dev — 開発環境を起動
- npm test — Vitestのテストを実行
- npm run lint — リンターを実行
- npm run db:migrate — 確認が必要

## Architecture
- src/app — ルート
- src/lib — ビジネスロジック
- src/db — データベースアクセス
- データベース操作はsrc/dbを経由すること

## Rules
- strict TypeScriptを使用し、anyを避ける
- 新しいコードにはテストを追加する
- 修正する前に、失敗するテストでバグを再現する
- 明示的に依頼されない限り、src/legacyを変更しない
- 完了前にnpm testとnpm run lintを実行する

CLAUDE.mdを長大なハンドブックにしないでください。詳細な指示や条件付きのガイダンスは.claude/rules/または再利用可能なスキルに記述し、重要な指示が埋もれないようにします。

基本の開発ワークフローを使う

このリポジトリでは、探索 → 計画 → コード → 検証 → コミットという手順を推奨しています。些細な範囲を超えるタスクでは、Claudeにすぐ編集を依頼するのではなく、まずPlanモードで開始してください。

  1. Shift+Tabを押して、Planモードを有効にします。
  2. 変更を加えずに、関連するコードを調査するようClaudeに依頼します。
  3. 提案されたファイル、実装手順、リスク、確認項目を確認します。
  4. 必要に応じて計画を修正します。
  5. 計画に問題がないことを確認してから、実装を許可します。
  6. テスト、リンティング、型チェック、またはスクリーンショットを必須にします。
  7. コミットやプルリクエストを依頼する前に、差分を確認します。

適切な探索プロンプトの例：

Plan mode. リポジトリを調査し、そのアーキテクチャ、
エントリポイント、/api/orders のデータフロー、テストの場所、
実行方法を説明してください。何も変更しないでください。
最後に、新しいコントリビューターが間違えやすい箇所を5つ挙げてください。

検証可能なプロンプトを書く

「バグを直して」とだけ言うのではなく、失敗の内容と期待する検証方法を説明します。

emailが空の場合、signup()がTypeErrorで失敗します。
失敗するテストで問題を再現し、妥当な範囲で最小限の変更を加えて修正し、
npm testを実行してください。

テスト駆動で機能を開発する場合：

機能：5000以上の注文に10%の割引を適用する。
まず、4999、5000、0、負の値に対するテストを書いてください。
新しいテストが失敗することを確認してから、
それらのテストを変更せずに機能を実装してください。

安全なリファクタリングの場合：

@src/services/user.tsを責務ごとのモジュールに分割してください。
動作や公開APIは変更しないでください。各ステップの後に
テストとtscを実行してください。カバレッジが不十分な場合は、まず特性テストを追加してください。

コンテキストを意図的に管理する

コンテキストウィンドウには、システム指示、プロジェクトルール、スキルとエージェントの説明、会話履歴、ファイル、コマンド出力が含まれます。無関係な情報が蓄積すると、応答の精度が低下することがあります。

  • /contextを使ってコンテキストの使用状況を確認します。
  • 無関係なタスクを始める前に/clearを使います。
  • 重要な決定を維持したまま長いセッションを要約するには、/compactを使います。
  • @src/api/client.tsのような構文でファイルを直接追加します。
  • !git statusのような構文でコマンドを実行し、その出力をコンテキストに追加します。
  • 長時間の作業では、ClaudeにPLAN.mdまたはNOTES.mdを維持させます。
  • 大規模な調査はサブエージェントに委任し、メインセッションにはその要約だけを返します。

ログをパイプで渡して、Claude Codeを一度だけ呼び出すこともできます。

cat error.log | claude

安全な権限を設定する

権限ルールはdeny → ask → allowの順に評価されます。拒否は許可より優先されます。このコースでは、権限チェックを無効にするのではなく、安全なコマンドを許可リストに登録することを推奨しています。

チーム設定では、.claude/settings.jsonにルールを配置できます。

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(curl:*)"
    ]
  }
}

この例では、通常のテストと調査を許可し、プッシュ時には確認を求め、シークレットへのアクセスと一部の危険なコマンドをブロックします。

  • CLAUDE.mdにシークレットを記載しないでください。
  • プッシュ、デプロイ、マイグレーションには確認を必須にします。
  • 自律的なジョブは、本番環境にアクセスできないコンテナまたはサンドボックスで実行します。
  • WebサイトやMCPシステムから返されたコンテンツは、信頼できる指示ではなくデータとして扱います。
  • 変更をコミットする前にgit diffを確認します。

繰り返す作業をスキルにする

同じ手順を何度も繰り返す場合は、それをスキルに変換します。スキルは、リリースノートの作成、プルリクエストのレビュー、プロジェクトのオンボーディングなどのワークフローに適しています。

このコースでは、プロジェクトのスキルを.claude/skills/に保存します。スキルには、名前、Claudeが使用タイミングを判断するのに役立つ説明、指示の手順を含めることができます。手順は狭い範囲に保ち、期待する出力を定義してください。

たとえば、リリースノートのスキルでは、Claudeに最新のGitタグを見つけ、そのタグ以降のコミットを収集し、変更をカテゴリ別に分類するよう指示できます。スターターキットには、インストール後に確認できる再利用可能なスキルがすでに用意されています。

分離された作業や専門的な作業にはサブエージェントを使う

サブエージェントは独自のコンテキストウィンドウを受け取り、結果をメインセッションに返します。これは、ノイズの多いリポジトリ調査、テスト実行、セキュリティ分析、独立したレビューに役立ちます。

このリポジトリのレビュアー例は.claude/agents/reviewer.mdに保存されており、エージェントに読み取り、検索、シェルの各ツールを与えます。その役割は、git diffを調査し、バグ、エッジケース、シークレットの漏えい、プロジェクトのスタイル違反を確認することです。

実用的なライターとレビュアーのパターン：

  1. 1つのClaudeセッションで変更を実装します。
  2. クリーンなセッションまたはサブエージェントを開き、差分をレビューします。
  3. 指摘事項を実装セッションに返します。
  4. 問題を修正し、検証を再実行します。

クリーンなコンテキストにより、長時間の実装セッション後には見落としやすい問題にレビュアーが気づきやすくなります。

フックで保証を強制する

プロジェクト指示はガイダンスを提供しますが、フックを使うとアクションを自動的に実行したり、ブロックしたりできます。コースで説明されている便利なフックイベントには、次のものがあります。

  • ブランチやタスクの情報を読み込むための SessionStart。
  • プロンプトにコンテキストを追加するための UserPromptSubmit。
  • 危険なコマンドや保護対象ファイルの編集をブロックするための PreToolUse。
  • フォーマット、Lint、対象を絞ったテストを実行するための PostToolUse。
  • Claudeの入力が必要なときにデスクトップ通知を表示するための Notification。
  • 最終確認を行うための Stop。
  • コンテキストの圧縮前に重要な情報を保存するための PreCompact。

次の例では、ファイルの編集または書き込み後にPrettierを実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

重要な保護対策では、記述した指示だけに頼らず、permissions.denyとPreToolUseフックを組み合わせてください。

​​MCPで外部システムに接続する

Claudeがローカルリポジトリの外部にあるツールやデータを必要とするときは、MCPを使用します。このコースでは、GitHub、ブラウザー、データベース、カスタムMCPサーバーとの連携を扱います。

ブラウザーMCPは、ビジュアル作業で特に便利です。ClaudeはUIを実装し、スクリーンショットを取得し、参照画像と比較して、差異を反映できます。外部コンテンツには信頼できないテキストが含まれる可能性があるため、MCPへのアクセスを慎重に確認し、プロンプトインジェクションに警戒してください。

ヘッドレスモードでタスクを自動化する

-pオプションを使うと、対話セッションなしでプロンプトを実行できるため、スクリプトやCIに適しています。たとえば、失敗したビルドのログを渡して構造化された出力を要求できます。

claude -p "Find the cause of the build failure" \
  --output-format json < build.log

プッシュする前に、現在の変更を確認します。

git diff main | claude -p \
  "Review this diff for bugs, edge cases, and security issues"

上限付きの自動化タスクでは、使用できるツールとターン数を制限します。

claude -p "Update CHANGELOG from recent commits" \
  --allowedTools "Read,Edit,Bash(git log:*)" \
  --max-turns 10

このリポジトリには、Issueやプルリクエストで@claudeを呼び出す例や、自動レビューのためのGitHub Actionsの例も含まれています。

Gitのワークツリーで複数のタスクを実行する

並行して作業する場合は、タスクごとに個別のワークツリーとブランチを作成します。各Claudeセッションは異なるディレクトリで動作するため、複数のエージェントが同じワークツリーを同時に編集するのを防げます。

git worktree add ../app-auth -b feature/auth
cd ../app-auth && claude

請求処理の作業、バグ修正、その他の独立したタスクでも、このパターンを繰り返せます。通常のGitワークフローで各ブランチをマージまたはレビューしてください。

便利なセッション操作

  • Escは、セッションのコンテキストを破棄せずにClaudeを中断します。
  • Esc Escまたは/rewindで、以前のコードと会話の状態に戻ります。
  • Shift+Tabで、通常モード、自動編集承認モード、Planモードを切り替えます。
  • /modelでアクティブなモデルを変更します。
  • /permissions、/hooks、/agents、/mcpで、関連する設定ワークフローを開きます。
  • claude --continueで、最新のセッションを再開します。
  • claude --resumeで、以前のセッションを選択できます。

高度なヒントとよくある間違い

  • 計画から始める: 複数のファイルにまたがる変更や、相応のリスクを伴う変更にはPlanモードを使用します。
  • 常にフィードバックを提供する: テスト、型チェック、Lint、ビルド、スクリーンショット、または正確な期待出力があれば、エージェントは自ら修正できます。
  • セッションをタスクに集中させる: 1つのセッションを一日中使い続けるのではなく、無関係な作業の間にはコンテキストをクリアします。
  • 失敗したアプローチを巻き戻す:修正に何度も失敗したら、悪いコンテキストを蓄積するのではなく、/rewindを使ってタスクを言い直します。
  • 差分を盲目的に受け入れない: 自分で変更を確認するか、独立したレビュアーのサブエージェントに依頼します。
  • 無制限の権限を避ける: 安全チェックを無効にするのではなく、許可リストとサンドボックスを使用します。
  • 繰り返し手順を自動化する: 繰り返しをスキルに変換し、必須の動作をフックにします。
  • 進捗を外部に保存する: 長時間のタスクでは、/clear後も作業を続けられるよう、計画ファイルやメモファイルを維持します。

学習パスを最後まで進める

このリポジトリのモジュールは、インストール、プロンプト、プロジェクトメモリ、設定、プロフェッショナルなワークフロー、スキル、サブエージェント、フック、MCP、プラグイン、ヘッドレスCI、高度なテクニックへと進みます。8つのラボでは、オンボーディング、権限、TDD、スキル作成、サブエージェント、フック、MCP、自動化を扱います。

クイックスタートのインストールと基本的なコンテキストコマンドから始めます。次に、簡潔なCLAUDE.mdと安全な権限ポリシーを作成します。その後、MCP、プラグイン、無人CI実行へ進む前に、計画、TDD、スキル、サブエージェント、フックを順に学習します。

まとめ

Claude Codeは、チャットインターフェースではなく、設定可能な開発エージェントとして扱うと最も効果を発揮します。焦点を絞ったコンテキストを与え、計画について合意し、客観的なチェックを用意し、権限とフックで重要な境界を適用してください。Claude Code PROリポジトリには、個人開発からチーム自動化まで、このワークフローを適用するための体系的なコース、実践的なラボ、再利用可能なテンプレートが用意されています。