Claude Code output styleの違いとカスタムMarkdownの作り方

output-styleって、結局CLAUDE.mdと何が違うのか。最初に触ったときに一番引っかかったのがここでした。同じMarkdown、同じ「振る舞いを変える仕組み」に見えるんですが、公式ドキュメントを読み込むと別物として設計されていることがわかります。Claude Code v2系で安定して使える機能なので、Skill運用やCLAUDE.md設計と並行して整理しておくと、AIの応答スタイルをチームで揃える設計の幅がぐっと広がります。

記事の前半でbuilt-inの3スタイル（Default/Explanatory/Learning）の違いを公式ドキュメントの記述ベースで整理し、後半で/output-style:newを使ったカスタムスタイルの作成手順、そしてkeep-coding-instructionsフラグで挙動が大きく変わる点を解説します。最後にCLAUDE.md・Skills・サブエージェントとの使い分けを表で並べます。

output-styleはCLAUDE.mdとどう違うのか

公式ドキュメントのComparisons to related featuresセクションに、3つの近接機能との違いがはっきり書かれています。output-styleは「Claude Codeのデフォルトシステムプロンプトのうち、ソフトウェアエンジニアリング向けの部分を完全にOFFにする」仕組み。これがCLAUDE.mdや--append-system-promptとまるっきり違うところです。

システムプロンプトの組み立て位置が違う

3つを並べると次のようになります。

機能	挿入位置	デフォルトSP上書き	セッション中の変更
output-style	システムプロンプトを置換	あり（コーディング指示をOFF）	不可（次セッションから）
CLAUDE.md	システムプロンプト直後にユーザーメッセージとして注入	なし	可
–append-system-prompt	システムプロンプトの末尾に追記	なし	起動時のみ

地味に重要なのが「CLAUDE.mdはシステムプロンプトではなくユーザーメッセージとして注入される」という事実です。これは関連記事のClaude Code memoryとCLAUDE.mdの違いと運用設計の実例でも触れていますが、実装上は<system-reminder>形式でユーザーメッセージ先頭に挿入される作りになっています。一方、output-styleは正真正銘システムプロンプトの中身を入れ替えるので、「Claudeをソフトウェアエンジニア以外の役割に振り切らせたいとき」に効くわけです。

役割を変えるのか、ルールを足すのか

使い分けの軸はシンプルです。

• Claudeを「家計簿アドバイザー」「英語翻訳者」「セキュリティレビュアー」など別の役にしたい → output-style
• 「このプロジェクトのDBはPostgreSQL」「テストはpytestで書く」のような前提を伝えたい → CLAUDE.md
• セッション起動時だけシステム指示を追加したい → --append-system-prompt

output-styleはあくまで役割（role）・口調（tone）・出力形式（format）を変える機能で、コードベース固有の知識は別レイヤーで渡す、という分業が公式ドキュメントの推奨です。

Default / Explanatory / Learning の中身を比較する

built-inで提供されている3つのスタイルは性格がきれいに分かれています。Claude Codeの/configからOutput styleメニューを開くとこの3つが並ぶ仕組みです。

3スタイルの設計意図

スタイル	用途	応答の長さ	追加機能
Default	通常の開発作業	標準	なし（既存のシステムプロンプト）
Explanatory	新しいコードベースの理解	長め	「Insights」セクションを応答に挿入
Learning	学びながら手を動かす	長め	「Insights」+ コード中にTODO(human)マーカー

Explanatoryの「Insights」は単なる説明追加ではなく、実装選択の理由やコードベースのパターンに対する解説をブロックで挟んでくる挙動です。新しいリポジトリに入ってまず構造を掴みたいときに、自分でコードリーディングするのと並走させると効きます。

Learningスタイルの「TODO(human)」が地味に新鮮

Learningで触ってみないと気づきにくいのが、TODO(human)マーカーの存在です。Claudeが「ここはあなたが書いてみてください」と判断した箇所に、コード中にこのマーカーを差し込んできます。実行例はこんな感じです。

def calculate_discount(price: int, member_rank: str) -> int:
    if member_rank == "gold":
        return price * 0.8
    elif member_rank == "silver":
        # TODO(human): silver会員の割引率を実装してください
        # ヒント: gold（20%off）とregular（割引なし）の中間に位置づけます
        pass
    else:
        return price

提案: silverには10%offくらいが妥当そうですが、ビジネス要件次第です。
実装したら、gold/silver/regularの3パターンでテストを書くことをお勧めします。

ペアプロ的にClaudeに教えてもらいたいときに使う想定です。ジュニアの育成や、自分が触ったことのない言語に挑戦するときに刺さるスタイルですね。

トークン消費はどう変わるか

公式ドキュメントのHow output styles workセクションに、トークン消費についての記述があります。要点は3つ。

• システムプロンプトに指示が追加される分、入力トークンは増える
• ただしプロンプトキャッシュが効くので、セッション2リクエスト目以降のコストは抑えられる
• Explanatory/Learningは応答が長めなので出力トークンが増える（こちらはキャッシュが効かない）

「とりあえず常時Explanatoryにしておこう」とすると、出力トークンの増加でコストが地味にかさむ点には注意が必要です。新規コードベースを掴む期間だけ切り替えるのが現実的な運用かなと思います。

/output-style:newでカスタムスタイルを作る

built-inでは表現できない役割を担わせたいときは、自分でMarkdownファイルを書きます。スクラッチで書いてもいいんですが、Claude本体に雛形を作ってもらえる/output-style:newコマンドが用意されています。

コマンド一発で雛形を生成する

Claude Codeのセッション内で次のように打ちます。

/output-style:new セキュリティレビュアーとして、コードの脆弱性を OWASP Top 10 を念頭に指摘するスタイル

Created custom output style at:
  ~/.claude/output-styles/security-reviewer.md

To activate, run /config and select "security-reviewer" under Output style.

生成されるファイルは次のような骨格です。

---
name: security-reviewer
description: OWASP Top 10を念頭にコード脆弱性を指摘する
---

# Security Reviewer Mode

あなたはセキュリティレビュー専門のCLIアシスタントです。
コードを読み、以下の観点で脆弱性を指摘してください。

## レビューの観点

- インジェクション系（SQL/コマンド/XSS）
- 認証・セッション管理の不備
- 機密情報の取り扱い
- 入力検証の欠如

## 出力フォーマット

各指摘は「重大度（High/Med/Low）」「該当箇所（file:line）」「修正案」
の3点セットで出してください。

保存場所はuser/projectで使い分ける

カスタムスタイルの置き場所は2か所あります。

• ~/.claude/output-styles/ — ユーザー全体で使うスタイル（個人用の口調指定など）
• .claude/output-styles/ — プロジェクト固有のスタイル（リポジトリにcommitして共有可）

プラグインとしても配布できる仕組みになっていて、プラグイン内のoutput-styles/ディレクトリに置けばmarketplace.json経由で配れます。プラグイン経由の配布はClaude Codeプラグインの作り方—marketplace.json設計と配布の流れでまとめた手順と同じ流れになります。

フロントマターのkeep-coding-instructionsで挙動が変わる

カスタムスタイルを書くときに、ここを理解していないとハマります。フロントマターは3項目あります。

フィールド	役割	デフォルト
name	スタイル名（未指定ならファイル名）	ファイル名から継承
description	/configのピッカーに表示される説明	なし
keep-coding-instructions	コーディング系のシステム指示を残すか	false

デフォルトでコーディング指示が消える

keep-coding-instructionsのデフォルトがfalseなのが要注意ポイントです。これがfalseだと、Claude Codeのデフォルトシステムプロンプトのうち「テストで動作確認しろ」「型を意識しろ」「既存パターンに合わせろ」といったコーディングの行儀作法部分がまるごとOFFになります。

セキュリティレビュアーや英語翻訳者のように、ソフトウェアエンジニアとしての振る舞いそのものを変えたい場合はfalseのままでOK。一方、たとえば「丁寧語で口調だけ統一したいエンジニアモード」を作りたい場合は、ここをtrueにする必要があります。

---
name: polite-engineer
description: 通常のソフトウェアエンジニア業務を丁寧語で実行する
keep-coding-instructions: true
---

# 丁寧語エンジニアモード

通常のソフトウェアエンジニアリングタスクを引き続き実行してください。
ただし、すべての応答は「ですます調」で行い、専門用語には簡単な
補足を1行添えてください。

出力例:
  ファイルを読み込みました（src/main.py、142行）。
  関数 `parse_config` の中でPydantic（型バリデーション用ライブラリ）
  を使われていますね。テストも合わせて確認いたします。

このフラグをfalseのまま「コードも書いてくれよ」と期待すると、テスト確認やコード規約遵守の指示が消えているので応答品質が下がる、という事故が起こります。「役割を完全に変える」のか「口調だけ変える」のかでフラグを切り替えるのが基本です。

設定の優先順位とセッション中の変更

output-styleは設定ファイルとセッションライフサイクルの両方に絡むので、ここを掴んでおくと運用が安定します。

選択結果は settings.local.json に書かれる

/configからOutput styleを選ぶと、選択結果は.claude/settings.local.jsonに保存されます。手で書く場合の中身はこうです。

{
  "outputStyle": "Explanatory"
}

このファイルはローカル設定なので、Gitignoreしておくのが原則。チーム全体で同じスタイルを共有したい場合は、.claude/settings.json（コミット対象）に書く運用も可能です。

セッション開始時にしか反映されない

これも触ってみないと気づかない仕様の一つで、output-styleの変更はセッション開始時にのみ反映される。理由はプロンプトキャッシュです。セッションの途中でシステムプロンプトが変わると、キャッシュが効かなくなって遅延・コストともに悪化するため、Anthropicは「セッション中は固定」という設計にしています。

運用上のコツは次のとおり。

• スタイルを切り替えたいときは、いったん/exitして再起動する
• 用途別に新しいセッションを立てる前提で運用する
• 「コーディング → レビュー → ドキュメント生成」のような長丁場のフローでは、フェーズごとにセッションを切る

SkillsやAgentsとの使い分け

Claude Codeには似たようなカスタマイズ手段が複数あって、最初は混乱します。output-styleがハマる場面を見極めるために、近接機能と並べておきます。

3機能の責務マップ

機能	変えるもの	発動タイミング	主な用途
output-style	システムプロンプト（役割・口調・形式）	セッション中ずっと有効	Claudeを別の役割にする
Skills	呼び出し時に追加プロンプト	/skill-nameまたは自動ロード	再利用可能なワークフロー
Agents（サブエージェント）	独立したエージェント（モデル・ツール選択可）	明示的に呼び出された時	並列処理・専門タスク委譲

判断のコツ

使い分けの目安はこんな感じです。

• 「全レスポンスでこの形式で答えてほしい」 → output-style
• 「特定のフローを呼び出したら、その時だけ専用プロンプトで動いてほしい」 → Skills
• 「並列で複数タスクを進めたい・コンテキストを汚したくない」 → Agents

Skillsの設計思想はClaude Code Skillの作り方—SKILL.md設計とtrigger発動の勘所でまとめていて、SKILL.mdのtriggerに何を書くかでロード判断が変わるという話を扱っています。あわせて読むと「常時 vs 都度」の境界線が掴みやすいはずです。

カスタムスタイル運用のアンチパターン

実際に何種類かカスタムスタイルを試してみて、ハマりやすいパターンが見えてきました。先にNG例を挙げてからOK例を示します。

NG: コードベース固有の知識を書く

---
name: project-style
---

# プロジェクト固有スタイル

このプロジェクトのDBはPostgreSQL 16です。
テストはpytest 8.x、ORMはSQLAlchemy 2.0を使っています。
ファイル構成は src/ 以下に...

これはoutput-styleでやるべきではない内容です。プロジェクト固有の前提はCLAUDE.mdに書くのが正解。output-styleにこれを書くと、別プロジェクトでこのスタイルを使ったときに前提が食い違って事故ります。

OK: 役割と出力形式に絞る

---
name: code-reviewer
description: コードレビュアーとして指摘事項を構造化された形式で出す
---

# Code Reviewer Mode

あなたはコードレビュアーです。指摘事項を以下のフォーマットで出してください。

## 出力フォーマット

```
## 指摘 N: <タイトル>
- 重大度: High / Med / Low
- 該当箇所: :
- 内容: <なぜ問題か>
- 修正案: <提案する修正>
```

指摘がない場合は「指摘なし: <理由>」と1行で返してください。

## 指摘 1: SQLインジェクションの可能性
- 重大度: High
- 該当箇所: src/users.py:42
- 内容: f-stringでクエリを組み立てているため、ユーザー入力の
  サニタイズが不十分。
- 修正案: parameterized queryに変更する。
  `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`

役割（reviewer）と出力フォーマットに絞ることで、どのプロジェクトでも使い回せるスタイルになります。これが本来のoutput-styleの守備範囲ですね。

まとめ

長くなったので要点を箇条書きで振り返ります。

• output-styleはClaude Codeのデフォルトシステムプロンプトを置換する仕組み。CLAUDE.md（ユーザーメッセージとして注入）とは挿入レイヤーが違う
• built-inはDefault/Explanatory/Learningの3種。Explanatoryは「Insights」、LearningはTODO(human)マーカーが特徴
• カスタムスタイルは/output-style:newで雛形生成。~/.claude/output-styles/または.claude/output-styles/に置く
• フロントマターのkeep-coding-instructionsはデフォルトfalse。コーディング指示を残したい場合は明示的にtrueにする
• 選択結果は.claude/settings.local.jsonのoutputStyleに保存される。セッション中の変更は反映されないので/exitして再起動が必要
• 役割・口調・形式の変更はoutput-style、コードベース固有の前提はCLAUDE.md、再利用フローはSkillsで分担するのが基本
• カスタムスタイルにプロジェクト固有の知識を書くのはアンチパターン。役割と出力形式に絞ると使い回せる

個人的には、Explanatoryをまず1セッション動かしてみて「Insightsって何が出るんだ？」を体感してから、自分用のreviewer/translatorスタイルを作っていくのが入りやすかったです。CLAUDE.mdとSkillsとoutput-styleの3点セットで、Claude Codeの応答スタイル設計はかなり自在になります。