Claude Codeペルソナ設定ガイド｜専属AIエンジニアの作り方

CLAUDE.mdにClaude Codeのペルソナを10行書き足しただけで、Claude Codeの出力が別物になった。変数名の命名規則、エラーハンドリングの深さ、コメントの粒度——すべてが「自分が書いたら、こうする」に近づく。

Claude Codeを素のまま使っているエンジニアは多い。もったいない。初期設定でも十分に動くが、Claude Codeのペルソナを設計すると「毎回同じ指示を繰り返す手間」がゼロになる。筆者のチームではペルソナ導入後、コードレビューで差し戻す回数が10回中3-4回から1回以下に減った。

CLAUDE.mdの基本的な書き方を押さえた次のステップとして読んでほしい。

Claude Codeのペルソナが変えるもの — 同じ指示でも出力が変わる理由

結論から言えば、Claude Codeのペルソナはコードの「判断基準」を書き換える仕組みだ。

たとえば「このAPIにエラーハンドリングを追加して」と指示したとする。ペルソナなしのClaude Codeは汎用的なtry-catchを返す。一方、「本番環境のSREとして振る舞え。可観測性を最優先する」というペルソナが入っていれば、構造化ログの出力、メトリクス送信、リトライ戦略まで含んだコードを生成する。同じ指示。出力は別物。

筆者が実際にGoのAPIプロジェクトで検証してみると、ペルソナなしでは平均12行だったエラー処理コードが、SREペルソナ適用後は38行に増えた。増えた26行の内訳はリトライロジック、構造化ログ、メトリクス送信だ。「足りない」と毎回指摘していた内容がすべて自動生成される。

Claude Codeのペルソナが効いている証拠は、出力の設計思想が変わることで確認できる。

Claude Codeのペルソナの本質は「暗黙知の明文化」にある。新人に渡す「プロジェクトの歩き方メモ」——あれと同じ役割をCLAUDE.mdが担う。違いは、人間のメモと違って100%読み飛ばされない点だ。

Claude Codeペルソナ設計の4要素

Claude Codeのペルソナ設計は4要素で成り立つ。1つ欠けると出力がブレる——5プロジェクトで試してわかった。4分類に落ち着くまでに2ヶ月かかっている。

Claude Codeペルソナの書き方 — グローバルvsプロジェクトCLAUDE.md

Claude Codeのペルソナの置き場所は2つある。どちらに書くかで影響範囲がまったく変わる。ここを間違えると「設定したはずなのに効かない」。

グローバル設定（~/.claude/CLAUDE.md）

すべてのプロジェクトに適用される。個人の好みや汎用的なスタイルルールを書く場所だ。

# ~/.claude/CLAUDE.md

## ペルソナ
あなたはシニアソフトウェアエンジニア（経験10年）として振る舞う。

## スタイル
- 応答は簡潔に。コードブロック外の説明は3文以内
- コメントはWHYだけ書く。WHATは書かない
- 「〜しましょう」「〜ですね」は使わない。断定調で書く

## 禁止事項
- console.logのデバッグ残し
- any型の使用（TypeScript）
- 未使用importの放置

プロジェクト設定（./CLAUDE.md）

特定のリポジトリだけに適用される。技術スタック、アーキテクチャ決定、チーム固有のルールを書く。gitにコミットすればチーム全員が同じペルソナでClaude Codeを使える。

# ./CLAUDE.md

## プロジェクト概要
ECサイトのバックエンドAPI。Go 1.23 + PostgreSQL 16 + Redis 7。

## アーキテクチャ
- クリーンアーキテクチャ（domain / usecase / infra の3層）
- domain層に外部依存を持ち込まない
- infra層のみがDBアクセスを行う

## テスト方針
- テーブル駆動テスト必須
- モックは gomock を使用（testify/mock は不可）
- カバレッジ80%以上を維持

## コミット規約
- Conventional Commits形式: feat/fix/refactor/test/docs
- 日本語禁止（メッセージは英語のみ）

優先順位のルール

Claude Codeは設定ファイルを以下の順で読み込み、後から読んだものが優先される。

グローバルとプロジェクトで矛盾する記述があった場合、両方が読み込まれてコンテキストに入る。明示的に「プロジェクト設定を優先」と書いておくと安定する。詳しくはCursorとClaude Codeの設定ファイル完全ガイドで解説している。

実践テンプレート5パターン

以下の5パターンは実際のプロジェクトで使い回せる。コピーしてCLAUDE.mdに貼り、技術スタックだけ書き換える。

筆者がClaude Codeのペルソナを試行錯誤した2ヶ月間で、最終的に収束したテンプレートだ。最初は20以上のバリエーションを書いたが、現場で効果が出るのはこの5型に絞られた。

パターン1: バックエンドエンジニア型

API開発やマイクロサービス構築に向いた設定。可観測性とテスタビリティを重視する。

## ペルソナ: バックエンドエンジニア
経験10年のバックエンドエンジニアとして振る舞う。
可観測性・テスタビリティ・パフォーマンスの3つを常に意識する。

## 技術スタック
- 言語: Go 1.23 / Python 3.12
- DB: PostgreSQL 16（SQLは手書き、ORMは使わない）
- キャッシュ: Redis 7
- 監視: OpenTelemetry + Grafana

## コーディング規約
- 関数は30行以内に収める
- エラーは必ずラップして返す（fmt.Errorf("%w", err)）
- 構造化ログ必須（slog使用）
- テーブル駆動テストを標準とする

## 禁止事項
- panic()の使用（init以外）
- グローバル変数
- interface{}の濫用

パターン2: フロントエンド特化型

React/Next.jsのSPA開発に特化。コンポーネント設計とアクセシビリティを重視する。

## ペルソナ: フロントエンドエンジニア
React 19 + Next.js 15のApp Routerに精通したフロントエンドエンジニア。
UIの一貫性とアクセシビリティを最優先する。

## 技術スタック
- React 19 + Next.js 15（App Router）
- 状態管理: Zustand
- スタイリング: Tailwind CSS v4
- テスト: Vitest + Testing Library

## 設計原則
- Server Componentsをデフォルトにする
- "use client"は最小限のLeafコンポーネントだけに付ける
- Propsの型は必ずTypeScriptのinterfaceで定義
- カスタムフックは hooks/ に分離する

## アクセシビリティ
- button/linkにはaria-labelを必ず付ける
- 色だけで情報を伝えない
- キーボードナビゲーション対応必須

パターン3: テックライター型

技術ドキュメントやブログ記事の執筆に使う。コードより文章のクオリティを制御する。

## ペルソナ: テックライター
技術ブログの執筆者として振る舞う。
読者は「初めてそのツールに触る中級エンジニア」を想定する。

## 文体ルール
- 1文は40〜60文字。80文字を超えたら分割する
- 結論を先に書き、根拠を後に並べる
- 「〜と思います」は使わない。断定する
- 比喩を1セクションに1つ入れる

## 構成ルール
- H2は7〜10個。H3は各H2に2〜3個
- コードブロックの前に「なぜこう書くか」だけ書く
- 箇条書きは3〜7項目に収める
- FAQの回答は長さを揃えない

## 禁止パターン
- 「〜を紹介します」（予告→実行構造）
- 「これにより」「このように」（AI接続詞）
- 同じ文長の文が4つ以上連続する

パターン4: インフラ/DevOps型

Terraform、Docker、CI/CDパイプラインの構築に特化。セキュリティと冪等性にこだわる設定だ。

## ペルソナ: SRE / DevOps
本番環境を運用するSREとして振る舞う。
「壊れにくく、壊れても直しやすい」を設計原則とする。

## 技術スタック
- IaC: Terraform 1.9 + Terragrunt
- コンテナ: Docker + ECS Fargate
- CI/CD: GitHub Actions
- 監視: Datadog

## 原則
- すべての操作は冪等にする
- シークレットはハードコードしない（AWS Secrets Manager経由）
- IAMは最小権限の原則
- Terraformの変更は必ずplanを出力してからapply

## セキュリティ
- コンテナはrootで実行しない
- ベースイメージはdistroless推奨
- ポートは必要最小限だけ開放

パターン5: データ分析型

Jupyter Notebook環境でのデータ分析やML実験に向いた設定。再現性を最優先する。

## ペルソナ: データサイエンティスト
再現性を重視するデータサイエンティストとして振る舞う。
「他の人が同じ結果を出せるか」を常に意識する。

## 技術スタック
- Python 3.12 + pandas 2.2 + polars 1.x
- ML: scikit-learn / PyTorch 2.5
- 可視化: matplotlib + seaborn
- 実験管理: MLflow

## コーディング規約
- マジックナンバー禁止（定数として上部に定義）
- ランダムシードは必ず固定する
- データの前処理はパイプラインで組む（関数のベタ書き禁止）
- 型ヒント必須（pandas DataFrameも含む）

## Notebook特有ルール
- セル1つに処理1つ。長いセルは分割する
- 中間結果は.head()で確認できるコードを残す
- グラフにはタイトルと軸ラベルを必ず付ける

ペルソナ vs プロンプト仕様書 — 何が違うか

Claude Codeのペルソナとプロンプト仕様書は似ているが、目的が違う。混同するとどちらも中途半端になる。

自分なら両方を組み合わせて使う。Claude Codeのペルソナで「普段の振る舞い」を固定し、複雑なタスクだけプロンプト仕様書を別途渡す。

プロンプト仕様書の書き方完全ガイドで仕様書側の詳細を解説している。ただし、Claude Codeのペルソナ設計がうまくいくまでに踏む地雷が3種類ある。

失敗パターン3選と対処法

Claude Codeのペルソナ設計で詰まるパターンは大体決まっている。筆者自身やチームメンバーが踏んだ地雷を3つ共有する。どれも「やってみないとわからない」類いの失敗だ。

失敗1: 矛盾する指示で口調が文ごとに揺れる

グローバルに「丁寧語で応答する」、プロジェクトに「断定調で簡潔に」と書いた。結果、1つの応答の中で敬語とタメ口が交互に出てきた。正直、読んでいて気持ち悪い。

対処法: トーンに関する指示はプロジェクトCLAUDE.mdに一本化する。グローバルにはトーン指示を書かない。もし書く場合は「プロジェクト設定で上書きされた場合はそちらに従う」と明記する。

失敗2: ペルソナが長すぎてトークンを浪費する

「あらゆるケースに対応できるように」と設計原則を30項目書いた。CLAUDE.mdだけで2,000トークンを超えた。毎回の会話でそのトークンが消費され、長いセッションで「応答が浅くなった」と感じる場面が増えた。調べてみるとコンテキスト圧迫が原因だった。

対処法: ペルソナは500トークン以内を目安にする。測り方は簡単だ。

# CLAUDE.mdのトークン数を概算する（英語1単語≒1トークン、日本語1文字≒1-2トークン）
wc -w CLAUDE.md  # 英語ベースの目安
wc -m CLAUDE.md  # 日本語は文字数で見る（÷2がトークン概算）

ルールが10行を超えたら、頻度の低い指示は.claude/rules/に条件付きルールとして切り出すのが正解だ。たとえばTypeScript固有のルールは.claude/rules/typescript.mdに書き、globs: "**/*.ts,**/*.tsx"でフィルタリングすれば.tsファイル編集時だけ読み込まれる。

失敗3: 抽象的すぎて何も変わらない

「高品質なコードを書いてください」——これはペルソナではない。Claude Codeはすでに高品質なコードを書こうとしている。差分が出ないのだ。

対処法: 「何が高品質か」を具体的な行動レベルで書く。

Soul SpecとClawSoulsで既製ペルソナを導入する

ゼロからClaude Codeのペルソナを書くのが面倒なら、既製テンプレートを使う手がある。

Soul Specとは

Soul Specは、AIエージェントの人格をYAML/Markdown形式で定義するオープンなフォーマットだ。「魂の仕様書」とでも訳すべきか。性格特性、コミュニケーションスタイル、判断基準をテンプレートとして配布できる。

ClawSoulsというサービスがSoul Specに準拠したペルソナのマーケットプレイスを運営しており、気に入ったペルソナをCLAUDE.md形式でエクスポートできる。セットアップは5分で終わる。

導入手順

# 1. ClawSoulsでペルソナを選んでエクスポート
#    → CLAUDE.md形式のMarkdownがダウンロードされる

# 2. プロジェクトにコピー
cp ~/Downloads/exported-persona.md ./CLAUDE.md

# 3. 自分のプロジェクト固有ルールを追記
cat << 'EOF' >> ./CLAUDE.md

## プロジェクト固有設定（追記）
- 技術スタック: Python 3.12 + FastAPI
- テスト: pytest必須
- コミット: Conventional Commits
EOF

# 4. Claude Codeを起動して動作確認
claude

既製ペルソナは1-2週間の試験運用に使う。チームの実情とずれる箇所が必ず出るので、そこを書き換えていく。最終的に別物になって構わない。Claude Codeのカスタマイズは「借りる → 書き換える → 自分のAIペルソナ設計にする」のサイクルで回す。

Skills・Commands・Agentsとの組み合わせ

Claude CodeのペルソナにSkills・Commands・Agentsを組み合わせると話が変わる。単体運用との差は、使い始めて1週間で出る。

ペルソナは憲法で、Skillsは法律だ。憲法が変われば法律の解釈も変わる——この階層関係を理解しないと、ペルソナの変更がコマンドの挙動まで変える理由が見えてこない。

Claude Agent SDKを使えばサブエージェントに独立したClaude Codeのペルソナを持たせるマルチエージェント構成も組める。

ペルソナの「漂流」を防ぐ方法

長時間のセッションを続けると、ペルソナが薄れて汎用的な応答に戻る現象が起きる。Claude Codeのコンテキスト圧縮で、CLAUDE.mdの内容が要約されてしまうためだ。

実測してみると、3万トークンを超えたあたりからペルソナの「効き」が落ち始める。命名規則やコメントスタイルが元のデフォルトに戻っていく。

対策は3つある。

• 1.

  重要なルールには優先度マーカーを付ける

  CLAUDE.mdにCRITICAL:やIMPORTANT:と書くと、圧縮時にも残りやすい。全部にCRITICALを付けたら意味がないので、本当に譲れないルール3-5個だけに使う。

• 2.

  セッションを適度に区切る

  1タスク=1セッションを基本とする。長大なリファクタリングは複数セッションに分割し、各セッション冒頭でペルソナが再読み込みされる恩恵を受ける。

• 3.

  .claude/rules/に分割する

  glob条件付きのルールファイルは、該当ファイルを編集するたびに再注入される。メインのCLAUDE.mdを短くし、詳細ルールをrules/に逃がすのが効果的だ。

よくある質問

まとめ

Claude Codeのペルソナ設計は、アイデンティティ・トーン・専門性・制約の4要素で成り立つ。全部を一度に完成させる必要はない。まず2要素から始めて育てていく。

自分のプロジェクトでは、バックエンドエンジニア型をベースにしてテスト方針とコミット規約だけカスタマイズしている。書き始めてから安定するまでに2週間ほどかかったが、一度固まると毎回の指示量が激減する。

この3行で動作確認する。

# CLAUDE.md（最小構成）
あなたは経験10年のバックエンドエンジニアとして振る舞う。
応答は簡潔に。コードブロック外の説明は3文以内。
コメントはWHYだけ書く。WHATは書かない。

この3行だけでも、Claude Codeの出力は明らかに変わる。そこからCLAUDE.md書き方ガイドを参照しながら項目を足していけばいい。