Claude Code output styles 設計ガイド - 返答形式を毎回プロンプトで直さない

Claude Code を使っていると、毎回「結論を先に」「コード差分だけ短く」「レビュー観点を表にして」「学習用に理由も説明して」といった指示を足しがちです。最初はそれで回りますが、チームで使い始めると、依頼する人ごとに返答形式が揺れ、レビューに必要な情報が抜けます。

この問題は CLAUDE.md に長い出力ルールを書くより、Claude Code の output styles で切り出した方が扱いやすい場面があります。この記事では、output styles を「口調設定」ではなく、返答形式を毎ターン固定する薄い system prompt 層として設計します。

Claude Code 全体の導入順は Claude Code の使い方 実践ガイド、プロジェクト文脈の固定は CLAUDE.md の書き方と育て方、繰り返し手順の再利用は Claude Code スラッシュコマンド実践ガイド に分けています。今回はそのどれでもなく、「Claude の返し方そのものを変える」層だけを扱います。

output styles で解決する課題

output styles が向くのは、作業内容ではなく 返答の型 が毎回同じときです。

• レビュー結果は必ず 重大度 / 根拠 / 修正方針 で返してほしい
• 実装中の説明は短く、最後だけ検証結果を明示してほしい
• 学習目的のセッションでは、差分だけでなく設計判断も説明してほしい
• 非エンジニア向けの要約では、コード詳細より影響範囲を先に出してほしい
• 図解を最初に置く説明モードを、毎回プロンプトで指定したくない

逆に、リポジトリ固有のディレクトリ構成、禁止コマンド、レビュー基準、検証コマンドは output styles に寄せません。そこは CLAUDE.md、Hooks、managed settings の責務です。

まず押さえるべき仕様

公式ドキュメント上、output styles は Claude Code の system prompt を変更して、role、tone、output format を調整する機能です。重要なのは、知識を足す機能ではないことです。プロジェクト事情を覚えさせる場所ではなく、返答の姿勢や形式を変える場所として見るべきです。

組み込み style は、Default に加えて Proactive、Explanatory、Learning があります。

style	向く場面	注意点
Default	通常の実装、修正、調査	返答形式を強く固定したい場合は都度指示が必要
Proactive	細かい確認で止めずに前へ進めたい作業	permission mode を変える機能ではないため、tool 実行の承認境界は別に残る
Explanatory	実装理由や設計判断も学びたい作業	出力が長くなりやすい
Learning	人間が一部コードを書きながら学ぶ作業	TODO(human) を含む進め方になるため、納品用作業には混ぜにくい

私なら、通常の業務実装では Default を維持します。output styles を常用するのは、レビュー、説明、教育、非エンジニア報告のように、出力形式の一貫性が成果物の品質に直結する場面です。

設定方法

現在の Claude Code docs では、output style の選択は /config から行うのが基本です。設定ファイルで直接指定する場合は、outputStyle を置きます。

{
  "outputStyle": "Explanatory"
}

注意点は、outputStyle が system prompt の一部として session start 時に読まれることです。変更しても、その場の会話に即時反映されるとは考えず、/clear または新しい session で確認する運用にします。

チームで共有するなら .claude/settings.json、個人だけなら ~/.claude/settings.json や .claude/settings.local.json に置きます。ただし、output style は返答形式に影響するため、プロジェクト全体で共有する場合は「なぜこの style を標準にするのか」を短く残しておいた方がよいです。

custom output style の最小例

custom output style は Markdown ファイルです。frontmatter に名前や説明を書き、その下に system prompt へ足したい指示を書きます。

たとえば、レビュー結果を短く固定したいなら、次のようにします。

---
name: Review Brief
description: Return code review findings in a short, evidence-first format
keep-coding-instructions: true
---

When reviewing code, lead with findings ordered by severity.

For each finding, include:

- severity
- file and line
- concrete failure mode
- minimal fix direction

If there are no findings, say so directly and list only residual test risk.
Avoid broad refactors unless they are required to fix the issue.

保存先は用途で分けます。

保存先	使いどころ
~/.claude/output-styles/	個人の説明・レビュー形式をどの repo でも使いたい
.claude/output-styles/	その repo のチームで同じ返答形式を共有したい
managed settings 配下	組織として配布したい

ここで大事なのは keep-coding-instructions: true です。コードを書く作業で output style を使うなら、基本は true にします。これを外すと、Claude Code の組み込みソフトウェアエンジニアリング指示を残さない設計になります。文章作成やデータ分析の persona に寄せたい場合は選択肢になりますが、実装作業に使うなら事故りやすいです。

CLAUDE.md、skills、status line と何が違うか

output styles は便利ですが、何でも入れる場所ではありません。既存機能との役割分担を先に決めます。

機能	主な責務	output styles に寄せないもの
output styles	返答の role、tone、format を固定する	repo 固有ルール、検証コマンド、禁止操作
CLAUDE.md	プロジェクト文脈、開発規約、読む順番を伝える	毎回の口調指定、長い persona
skills	特定タスクの手順、参照資料、スクリプトを必要時だけ読む	全ターン共通の返答形式
Hooks	tool 実行前後の強制チェック、自動整形、ブロック	説明の雰囲気や文章構成
status line	model、cwd、branch、context、cost などの状態表示	返答内容そのもの
managed settings	組織で上書きさせない設定・権限境界	個人の学習用スタイル

たとえば「PRレビューでは重大度順に短く返す」は output style に向きます。一方で「この repo では pnpm run build を必ず実行する」は CLAUDE.md や automation の手順に置くべきです。返答形式と作業義務を混ぜると、後からどこを直せば挙動が変わるのか分からなくなります。

実務での設計パターン

1. Review Brief

コードレビュー用の style です。発見事項、根拠、修正方向だけを先に出します。実装説明を長くしないため、レビュー queue で読む人の負荷を下げられます。

向く場面:

• PR差分レビュー
• automation が作った差分の受け入れ判断
• セキュリティ観点の preliminary review

避ける場面:

• 学習目的でレビュー観点を丁寧に理解したいとき
• 仕様整理がまだ曖昧で、会話しながら設計を詰めたいとき

2. Implementation Log

作業中の中間報告は短く、最後に変更ファイル、検証、未解決リスクだけを返す style です。自動化や長い修正作業では、これがあると「どこまで終わったか」を見失いにくくなります。

---
name: Implementation Log
description: Keep progress terse and final reports evidence-first
keep-coding-instructions: true
---

During implementation, keep updates to one or two sentences.
At the end, report only:

- changed files
- verification commands and results
- unresolved risks
- next required action

この style は Claude Code status line と役割が違います。status line は現在の session 状態を見る UI で、Implementation Log は会話本文の返し方です。両方を使うと、状態と報告形式を分けて管理できます。

3. Explain First

新人 onboarding やコードベース理解に使う style です。実装だけでなく、なぜその修正にしたか、どの既存パターンに合わせたかを説明します。

これは Explanatory に近いですが、チーム固有のレビュー観点を少し足したい場合に custom style として持つ価値があります。ただし、説明が長くなるため、通常の修正依頼に常用すると token と読む時間が増えます。

4. Non Engineer Summary

非エンジニアに結果を返す style です。コード詳細ではなく、影響範囲、リスク、確認方法、意思決定が必要な点を先に出します。

AIエージェント運用では、作業者と意思決定者が別になることがあります。この場合、成果物をレビュー可能な形で返す必要があります。output styles は、その返答面だけを軽く固定する補助線になります。

チーム導入時の判断基準

output styles は system prompt に触るため、便利さだけで増やすと管理しづらくなります。導入時は次の基準で絞ります。

1. 返答形式の問題か
   • repo ルールなら CLAUDE.md
   • 実行手順なら skill / slash command
   • 強制チェックなら Hooks
   • 返答の型なら output style
2. 全ターンに効いてよいか
   • 1回だけなら prompt で足す
   • 特定タスクだけなら skill にする
   • session 全体で効かせるなら output style にする
3. coding instructions を残すか
   • 実装・レビューなら keep-coding-instructions: true
   • 非コーディング persona なら外す余地あり
4. token と冗長性を許容できるか
   • 長い style は input token を増やす
   • Explanatory / Learning 系は output token も増えやすい
5. 管理者が固定すべきか
   • 個人の好みなら user scope
   • repo のレビュー形式なら project scope
   • 組織標準なら managed policy

特に Proactive を使うときは、権限設定と混同しない方がよいです。Proactive は「返答と進め方を前のめりにする」style であって、危険な tool 実行を自動許可する権限設定ではありません。権限境界を設計するなら Claude Code managed settings 設計ガイド や Hooks 側で固めます。

失敗しやすいアンチパターン

style にプロジェクト知識を詰める

「この repo では Astro を使う」「build は pnpm run build」「記事は src/content/blog に置く」といった情報は output style ではありません。CLAUDE.md に置くか、記事作成 skill に切り出します。

style を増やしすぎる

Review Brief、Explain First、Non Engineer Summary くらいなら管理できますが、細かい persona を10個以上作ると選ぶ負担が増えます。まずは、チームの業務で本当に繰り返される返答形式だけに絞ります。

Learning を納品作業で使う

Learning は学習には向きますが、人間が途中でコードを書く前提になりやすいです。納期がある修正作業、automation、PR作成では Default か専用の Implementation Log を使う方が安定します。

output style で安全運用を代替する

「危険なら止めて」と style に書いても、権限境界にはなりません。MCP write、外部送信、secret 読み取り、deploy などは、managed settings、permission rules、Hooks、review gate で止めるべきです。

私ならこう運用する

個人利用では、まず Default のまま使います。何度も同じ返答形式を頼んでいると気づいたら、user scope に custom output style を1つだけ作ります。

チーム利用では、いきなり標準 style を配りません。まず .claude/output-styles/Review Brief.md を repo に置き、PRレビューや automation 結果確認だけで試します。2週間ほど使って、レビュー時間が短くなり、必要な根拠が抜けないなら project scope の標準候補にします。

組織利用では、style そのものよりも「どの style をどの作業 lane で使うか」を決めます。

作業 lane	推奨 style	理由
通常実装	Default	過剰な説明を避ける
PRレビュー	Review Brief	findings を先に出す
onboarding	Explanatory / Explain First	設計判断を残す
非エンジニア報告	Non Engineer Summary	影響と判断点を先に出す
automation	Implementation Log	検証と未解決リスクを固定する

この分け方にすると、output styles は「気分で変える表示設定」ではなく、AIエージェント運用の応答契約になります。

まとめ

Claude Code output styles は、Claude の知識や作業手順を増やす機能ではありません。返答の role、tone、format を system prompt 層で固定する機能です。

実務では、CLAUDE.md にプロジェクト文脈、skills に再利用手順、Hooks と managed settings に強制境界、status line に session 状態、output styles に返答形式を置く。この分担にすると、Claude Code のカスタマイズが肥大化しにくくなります。

最初に作るなら、Review Brief か Implementation Log のどちらかで十分です。毎回同じ形式をプロンプトで頼んでいる箇所を1つだけ style に切り出す。そこから始める方が、チーム運用では失敗しにくいです。

参考

• Output styles - Claude Code Docs
• Claude Code settings - Claude Code Docs
• Extend Claude with skills - Claude Code Docs