Claude Codeテンプレート完全入門|MCPサーバー連携とカスタムコマンドで開発を自動化する

約22分で読めます by ぽんたぬき
Claude Codeテンプレート完全入門|MCPサーバー連携とカスタムコマンドで開発を自動化する

Claude Codeテンプレート完全入門|MCPサーバー連携とカスタムコマンドで開発を自動化する

はじめに:なぜ「テンプレート」から始めるべきなのか

Claude Codeを導入した多くの開発者が、最初の数日でこんな壁にぶつかります。

  • 設定ファイルをゼロから書く負担:CLAUDE.md に何を書けばいいか分からない
  • どのMCPサーバーを入れるべきか判断できない:選択肢が多すぎて手が止まる
  • プロジェクト固有のワークフローに落とし込めない:汎用的な使い方しかできない

この問題をまとめて解決するのが、GitHub上で多くのスターを集めているオープンソースリポジトリ claude-code-templates です。実践的なテンプレート群と設定例を提供しており、「動くものからスタートして自分仕様に削る」というアプローチを取れます。

この記事では以下の3つを実際のコードつきで解説します。

  1. セキュリティ監査・テスト生成・バンドル最適化のカスタムコマンド
  2. GitHub / PostgreSQL / Stripe のMCPサーバー連携
  3. pre-commitフックによる自動品質チェック

前提環境: Node.js 18以上、Git、Claude Code CLI(最新版)がインストール済みであることを確認してください。


前提知識:Claude Codeの設定ファイル構造を3分で理解する

本題に入る前に、Claude Codeの設定ファイル体系を整理しておきましょう。

ファイル/ディレクトリ 役割
CLAUDE.md プロジェクトの「取扱説明書」。コーディング規約・アーキテクチャ概要をClaudeに伝える
.claude/commands/ カスタムコマンドの置き場所(.mdファイル1つ=コマンド1つ)
.claude/settings.json フック(Hooks)の定義。イベント駆動で外部コマンドを差し込む
.mcp.json プロジェクトスコープのMCPサーバー設定

設定にはプロジェクト単位(.claude/配下)とグローバル(~/.claude/配下)の2つのスコープがあります。チーム共有するものはプロジェクト単位に、個人のAPIキーや好みはグローバルに置くのがベストプラクティスです。


ステップ1:claude-code-templates を導入する

リポジトリの取得と構成確認

まずリポジトリをクローンして内容を確認します。

git clone https://github.com/davila7/claude-code-templates.git
cd claude-code-templates
ls -la

ディレクトリ構成はおおむね次のようになっています。

claude-code-templates/
├── templates/
│   ├── nextjs/          # Next.js プロジェクト向け
│   ├── python-fastapi/  # Python + FastAPI 向け
│   ├── react/           # React SPA 向け
│   └── ...
├── commands/            # 汎用カスタムコマンド
└── mcp-configs/         # MCPサーバー設定例

自分のプロジェクトへの適用

npx で対話的に適用することもできます。

# npxが使えないため、クローン済みリポジトリから直接テンプレートを選択・適用する
echo "利用可能なテンプレート一覧:"
ls claude-code-templates/templates/

# 使用するテンプレートを変数で指定(例:nextjs)
TEMPLATE="nextjs"
echo "選択したテンプレート: $TEMPLATE"

あるいは、目的のテンプレートディレクトリを自分のプロジェクトに手動でコピーする方法が最も確実です。

# テンプレートを適用する(TEMPLATE変数を使用)
mkdir -p ./my-project

# .claude ディレクトリが存在する場合のみコピー
if [ -d "claude-code-templates/templates/$TEMPLATE/.claude" ]; then
  cp -r "claude-code-templates/templates/$TEMPLATE/.claude" ./my-project/
fi

# CLAUDE.md が存在する場合のみコピー
if [ -f "claude-code-templates/templates/$TEMPLATE/CLAUDE.md" ]; then
  cp "claude-code-templates/templates/$TEMPLATE/CLAUDE.md" ./my-project/
fi

echo "テンプレート '$TEMPLATE' を ./my-project/ に適用しました。"

重要:「全部入れない」ことが大切です。 不要なコマンドや設定を詰め込むとClaudeのコンテキストが肥大化し、応答速度と精度の両方が落ちます。必要なものだけを選んで導入してください。


ステップ2:カスタムコマンドで開発自動化を仕込む

カスタムコマンドの仕組み

.claude/commands/ 以下に置いたMarkdownファイルが、そのままスラッシュコマンドとして使えるようになります。ファイル名 security-audit.md → コマンド /security-audit です。

ファイルの先頭にはYAMLフロントマターで挙動を制御できます。

---
description: "コードベースのセキュリティ脆弱性を静的解析する"
allowed-tools: ["read", "bash"]
argument-hint: "[対象ディレクトリ(省略時はsrc/)]"
---

以下のディレクトリを対象にセキュリティ監査を実施してください:$ARGUMENTS

...(プロンプト本文)

$ARGUMENTS がコマンド実行時に渡した引数に置換されます。


カスタムコマンド① セキュリティ監査(/security-audit)

.claude/commands/security-audit.md として保存します。

---
description: "ハードコードされた秘密情報・依存脆弱性・入力検証漏れを検出する"
allowed-tools: ["read", "bash", "grep"]
argument-hint: "[対象パス(省略時はsrc/)]"
---

対象ディレクトリ: $ARGUMENTS(未指定の場合は `src/` 全体)

以下の観点でセキュリティ監査を実施し、深刻度(Critical / High / Medium / Low)とともに報告してください。

## チェック項目

1. **ハードコードされた秘密情報**
   - APIキー、パスワード、トークンのリテラル埋め込み
   - `.env` に移すべき設定値

2. **依存パッケージの脆弱性**
   - `npm audit` または `pip-audit` を実行して結果を解釈
   - CVSS スコア 7.0 以上を優先的に報告

3. **入力検証の漏れ**
   - ユーザー入力がサニタイズなしでDBクエリ・コマンド・HTMLに渡っている箇所
   - SQLインジェクション・XSS・コマンドインジェクションのリスク

報告フォーマット:
- 深刻度ラベル
- 該当ファイルと行番号
- 問題の説明(1〜2文)
- 推奨される修正方針

実行時はClaude Codeのチャット欄で /security-audit src/api と入力するだけです。


カスタムコマンド② テスト自動生成(/generate-tests)

---
description: "指定ファイルの単体テストをVitest/Jestで自動生成する"
allowed-tools: ["read", "write"]
argument-hint: "<対象ファイルパス>"
---

対象ファイル: $ARGUMENTS

以下の方針でテストファイルを生成してください。

## 方針

- テストフレームワーク: プロジェクトの `package.json` を確認して `vitest` か `jest` かを判断
- ファイル配置: 対象ファイルと同ディレクトリに `*.test.ts` を作成
- カバレッジ目標: 主要な分岐を網羅(ハッピーパスと異常系の両方)

## テスト設計ルール

1. `describe` ブロックで関数・クラス単位にグルーピングする
2. テスト名は「〇〇のとき〇〇を返す」という日本語仕様書スタイルで書く
3. 外部依存(DB・APIクライアント等)は必ずモックする
4. テストデータはファクトリ関数で生成し、ハードコードしない

生成後、実際に `npx vitest run <テストファイルパス>` を実行して構文エラーがないことを確認してください。

運用上の注意: 生成されたテストは「仕様の検証ツール」ではなく「実装の写し鏡」になりやすいです。テストを信用する前に、境界値や異常系が本当にカバーされているかを人間が確認してください。


カスタムコマンド③ バンドル最適化(/optimize-bundle)

---
description: "Webアプリのバンドルサイズを分析し、最適化案を提示する"
allowed-tools: ["read", "bash"]
---

以下の手順でバンドル最適化を支援してください。

## 分析フェーズ

1. `npx vite-bundle-visualizer` または `npx webpack-bundle-analyzer` を実行して結果を確認
2. `node_modules/.pnpm` または `package.json` の依存関係から肥大化している可能性のあるパッケージを特定

## 改善提案フェーズ

以下の観点で優先度付きの改善案を提示してください:

| 優先度 | 施策 | 期待効果 |
|---|---|---|
| High | 動的インポート(`import()`)への置き換え | 初期バンドルを削減 |
| High | 未使用エクスポートの削除(tree shaking改善) | デッドコード除去 |
| Medium | 重複機能の軽量ライブラリへの置き換え | 依存サイズ削減 |
| Low | 画像・フォントのCDN化 | ネットワーク最適化 |

提案ごとに「現状サイズ → 改善後の推定サイズ」を示してください。

ステップ3:MCPサーバーを設定して外部サービスとつなぐ

MCPサーバーはClaude Codeが「外の世界」(GitHub・DB・外部APIなど)に直接アクセスするための拡張機能です。設定は .mcp.json に記述します。

GitHub MCP:Issue・PRをClaude Codeから操作する

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

GITHUB_TOKEN は .env ファイルまたはシェルの環境変数に設定し、JSONには絶対に直書きしないでください。Personal Access Tokenに与えるスコープは repo と read:org の最小限に留めることをお勧めします。

実践例: Issueを読んで修正ブランチまで作らせる

/create-branch #123 のIssueを読んで、修正ブランチを作成し、
関連するファイルを特定して変更の骨格をコメントとして残してください。

PostgreSQL MCP:スキーマを理解させてクエリ品質を上げる

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

セキュリティ上の重要事項: 本番DBには絶対に接続しないでください。開発用DB、または読み取り専用ユーザーで接続することを強く推奨します。GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly; のように権限を最小化してください。

実践例: スキーマを根拠にマイグレーションSQLを書かせる

現在のusersテーブルのスキーマを確認した上で、
email_verifiedカラムを追加するマイグレーションSQLを書いてください。
既存データへの影響と、ロールバック用のDOWNスクリプトも含めてください。

Stripe MCP:決済実装のミスを減らす

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/agent-toolkit"],
      "env": {
        "STRIPE_SECRET_KEY": "${STRIPE_SECRET_KEY}"
      }
    }
  }
}

StripeのAPIキーは必ずテスト用(sk_test_...)と本番用(sk_live_...)を分けて管理し、開発環境では絶対に本番キーを使わないようにしましょう。


MCPサーバーが反映されないときのチェックリスト

# 接続状況の確認
claude mcp list

# 特定サーバーの詳細確認
claude mcp get github

よくある原因:

  • 環境変数がシェルに読み込まれていない(source .env を忘れた)
  • JSONに末尾カンマが残っている(JSON構文エラー)
  • npx でパッケージ名が間違っている(@を忘れるなど)
  • claude mcp list に出るが stdio の起動に失敗している(Node.jsバージョン不整合)

ステップ4:pre-commitフックで品質チェックを自動化する

Claude Code Hooksは、ツール実行の前後や処理完了時などのイベントに合わせてシェルコマンドを差し込む機能です。.claude/settings.json に定義します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx lint-staged"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '✅ Claude Code セッション終了' | notify-send -"
          }
        ]
      }
    ]
  }
}

設定例①:編集後に自動フォーマット+Lint

PostToolUse で write_file イベントをキャッチし、保存直後にフォーマットをかけます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_PATH\" && npx eslint --fix \"$CLAUDE_TOOL_INPUT_PATH\""
          }
        ]
      }
    ]
  }
}

設定例②:秘密情報のコミットを機械的にブロックする

PreToolUse で bash コマンドを監視し、git commit 実行前に gitleaks でスキャンします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -q 'git commit' && gitleaks detect --staged --no-banner || true"
          }
        ]
      }
    ]
  }
}

スキャンが異常終了(exit code 非ゼロ)した場合、Claudeはそのツール実行を中断します。

huskyとの役割分担

役割 担当
コード品質・フォーマット(AIが判断できること) Claude Code Hooks
秘密情報スキャン・コミットメッセージ規約(決定論的に止めるべきもの) husky + lint-staged

両者は競合しません。huskyはgit操作時に必ず発動する「最後の砦」、Claude Code Hooksはエディタ操作に近いレイヤーで動作する「早期検知層」として使い分けましょう。


ステップ5:チームで運用する

CLAUDE.md にコーディング規約を集約する

CLAUDE.md はClaudeへの指示書であると同時に、チーム全員が参照するリビングドキュメントです。

# プロジェクト概要
このリポジトリはNext.js 14 App Router + TypeScriptで構築された
ECサイトです。

# コーディング規約
- 関数コンポーネントのみ使用(クラスコンポーネント禁止)
- 状態管理はZustand。ReduxやContextは新規で使わない
- CSS-in-JSは使用不可。Tailwind CSSを使う
- APIルートのエラーハンドリングは必ずtry-catchでラップし、
  `AppError` クラスでスローする

# ディレクトリ構成
src/
├── app/         # App Router ページ・レイアウト
├── components/  # UIコンポーネント
├── lib/         # ユーティリティ・ヘルパー
└── types/       # 型定義

.gitignore の設計

# コミットするもの(チームで共有する設定)
# .claude/commands/    ← コミットする
# .claude/settings.json ← コミットする(APIキーを含まない)
# CLAUDE.md            ← コミットする

# コミットしないもの(個人の設定・秘密情報)
.env
.env.local
.mcp.json          # APIキーが入る可能性があるため個人管理
~/.claude/         # グローバル設定はそもそもgit管理しない

APIキー・トークンを漏洩させないための3原則

  1. .mcp.json のAPIキーは必ず ${ENV_VAR} 形式の環境変数参照にする
  2. .mcp.json 自体を .gitignore に追加し、.mcp.json.example(ダミー値)だけをコミットする
  3. gitleaks または truffleHog をCI/CDに組み込み、プッシュ前にスキャンする

つまずきポイントと対処法

カスタムコマンドが一覧に出てこない

チャット欄で / を入力したときにコマンドが表示されない場合:

# ファイルのパーミションと拡張子を確認
ls -la .claude/commands/
# → .md 拡張子であることを確認

# Claude Codeを再起動して設定を再読み込み

YAMLフロントマターの description フィールドが欠けていると一覧表示されないことがあります。

MCPサーバーが起動直後に落ちる

# 手動で起動してエラーを確認
npx @modelcontextprotocol/server-github
# → エラーメッセージを確認してNode.jsバージョンや環境変数を修正

コンテキストを食い過ぎて応答が遅い・精度が落ちる

  • 使わないMCPサーバーは claude mcp remove <name> で一時的に外す
  • CLAUDE.md が肥大化していないか確認。5,000文字を超えるようなら章ごとに分割して必要なものだけ @import する
  • 長いセッションは /clear でコンテキストをリセットしてから再開する

まとめ:テンプレートは「出発点」として使う

テンプレートをそのまま使い続けることが目的ではありません。重要なのは「動く設定」を素早く手に入れ、自分のプロジェクトに合わせて削り・育てていくプロセスです。

今日から試す最小構成の3点セット

優先順位 やること 所要時間
1 CLAUDE.md にプロジェクト概要とコーディング規約を書く 15分
2 /security-audit コマンドを追加して既存コードをスキャン 10分
3 GitHub MCPを設定してIssueドリブンな開発を試す 20分

この3つだけで、Claude Codeの生産性は大きく変わります。まずは1つ動かしてみることが、最速の学習です。

次に読むべきリソース

段階的に理解を深めながら、あなたのチームに最適なClaude Code環境を育てていきましょう。

関連記事

dotfiles を AI エージェント向けに再設計する — Claude Code / Codex 時代の開発環境最適化

dotfiles を AI エージェント向けに再設計する — Claude Code / Codex 時代の開発環境最適化

dotfiles を AI エージェント向けに再設計する — Claude Code / Codex 時代の開発環境最適化 AI が 1,339 回、人間が 80 回。 これは筆者が自分のシェル操作ログを集計したときに目にした数字です。Claude Code を日常的に使うようになった 2026 年、ターミナルを操作している主体はもはや人間ではなく AI エージェントになっていました。 しかし、筆...

【2026年版】AIエンジニア学習ロードマップ完全ガイド|数学基礎から本番LLMアプリ・MCPまで523レッスンで学ぶ

【2026年版】AIエンジニア学習ロードマップ完全ガイド|数学基礎から本番LLMアプリ・MCPまで523レッスンで学ぶ

【2026年版】AIエンジニア学習ロードマップ完全ガイド|数学基礎から本番LLMアプリ・MCPまで523レッスンで学ぶ 「AIエンジニアになりたいが、何をどの順番で学べばいいのか分からない」——この悩みに対する一つの決定版が登場しました。週間3,200スターを獲得した超大型オープンソースカリキュラム は、523レッスン・20フェーズ・約342時間で数学基礎から本番LLMアプリケーションまでを一気...

【緊急解説】LLMエージェントは自分の「証拠」を消せる — トレース改ざん攻撃の実証と、監査ログを守る実践設計

【緊急解説】LLMエージェントは自分の「証拠」を消せる — トレース改ざん攻撃の実証と、監査ログを守る実践設計

【緊急解説】LLMエージェントは自分の「証拠」を消せる — トレース改ざん攻撃の実証と、監査ログを守る実践設計 --- この記事の要約:AI監査の大前提が崩れた日 「エージェントは自分の実行ログを消せない」という暗黙の前提 現在のAIガバナンスや内部監査体制は、ある一つの暗黙の前提の上に成り立っています。それは「LLMエージェントは、自分が何をしたかの記録を意図的に消したり改ざんしたりすることはで...

ChatGPT の「`__obi`」クッキーとは? 広告追跡の仕組みと今すぐできる対策を解説

ChatGPT の「`__obi`」クッキーとは? 広告追跡の仕組みと今すぐできる対策を解説

ChatGPT の「」クッキーとは? 広告追跡の仕組みと今すぐできる対策を解説 > 最終更新:2026年2月時点の情報を基に執筆。制度・仕様は変更される可能性があります。 OpenAI が ChatGPT ユーザーの他サイト閲覧・購買履歴を追跡していることが明らかになりました。「マーケティングには同意していない」という設定のまま、あなたのネット上の行動が ChatGPT アカウントと紐づいている可...

コメント

0/2000