Claude Codeでoutput styleを自作する実践パターン集

自作のoutput styleは、frontmatterと本文だけのMarkdownファイル1つです。組み込みのDefaultやExplanatoryで足りない役割(ドキュメント執筆・データ分析・レビュー専任など)を、既存のスタイルに近い型から作れます。切り替え手順や組み込みスタイルの詳細はoutput styleの基本ガイドに譲り、本稿は自作そのもの、用途別のテンプレート、チームやプラグインで配布するときの注意点に絞ります。

自作が必要になるタイミング

組み込みのDefault・Proactive・Concise・Explanatory・Learningでカバーできない役割が欲しくなったら自作の出番です。毎回同じ前置きを打ち込んでいる、Claudeに特定の職能(レビュアー・アナリスト・教育係)を演じさせたい、といった状況が該当します。

もう少し具体的に言うと、次のような場面で自作の必要性が出てきます。ドキュメントだけを書かせたいのに毎回コードを提案してくる、分析結果を文章で長々と返してきて表にまとめてほしい、実装前に設計方針を確認してほしいのに黙って書き始める。こうした不満はプロンプトを毎回書き直しても解消しますが、セッションが変わるたびに同じ指示を繰り返すことになります。自作のoutput styleにしておけば、その職能を選ぶだけで再現できます。

前提として、/configから組み込みスタイルを切り替えたことがあり、.claude/settings.local.jsonにどう保存されるかを知っている状態を想定します。切り替え自体が初めてなら、先に基本ガイドを読んでから戻ってきてください。

自作スタイルの実体はMarkdownファイル1つです。frontmatterにはname・description・keep-coding-instructions・force-for-pluginの4キーを持てます。このうち設計判断が要るのはkeep-coding-instructionsだけです。他の3キーは名前・説明・プラグイン挙動の指定なので、迷う余地はほとんどありません。

用途を1つに絞って設計する

自作スタイルの設計は、keep-coding-instructionsをtrueにするかfalseにするかの二択にほぼ集約されます。ここを最初に決めると、本文に何を書くべきかが自然に決まります。

keep-coding-instructionsの既定値はfalseです。falseのままだと、Claude Codeが元から持つソフトウェアエンジニアリング指示(変更範囲の絞り方・コメントの書き方・検証手順)が丸ごと外れます。代わりに自作の本文がシステムプロンプト末尾に載ります。Claudeがコードを書かない役割(ドキュメント執筆・データ分析・レビュー専任)ならこれで十分です。逆にコーディング自体は続けさせつつ話し方や出力形式だけ変えたいなら、trueにして既存指示を残します。

判断に迷ったら、「このスタイルを選んだ状態でコードを書かせるか」を自問します。書かせないならfalse、書かせるならtrueが出発点です。

本文の書き方にも設計原則があります。CLAUDE.mdの効果的な書き方として公式が挙げる「具体的で、簡潔で、構造化されている」という原則は、output styleの本文にもそのまま使えます。曖昧な役割説明(「丁寧に対応する」)より、検証できる指示(「結論を1文で先頭に置く」「表以外の形式を使わない」)のほうが再現性が上がります。「わかりやすく書く」ではなく「専門用語には初出で補足を付ける」、「簡潔に」ではなく「1回答は3段落まで」のように、後から守れたかどうかを判定できる粒度まで具体化するのがコツです。本文はそのままシステムプロンプトに追加されるので、長く書くほど毎回のトークン消費が増える点も忘れないでください。

目的別テンプレート5パターン

ここからは実際に使える5パターンです。いずれも保存先ファイル名がそのままスタイル名になるので、nameは省略しても構いません(区別のため明記しています)。

最初の1つはkeep-coding-instructions: falseの代表例、ドキュメント執筆アシスタントです。

---
name: Docs Writer
description: 実装せず、ドキュメント執筆のみを行うスタイル
keep-coding-instructions: false
---
 
あなたはテクニカルライターです。コードの変更は提案のみに留め、ファイルの編集は行いません。
既存のREADMEやガイドの文体に合わせ、見出し構成を先に提示してから本文を書いてください。
専門用語には初出で簡潔な補足を添えます。

---
name: Data Analyst
description: 分析結果を表形式で返すスタイル
keep-coding-instructions: false
---
 
あなたはデータアナリストです。実装は行わず、渡されたデータや出力の傾向を分析して返してください。
結論を先頭に1文で示し、根拠となる数値はMarkdownの表にまとめます。
不確かな推測には「〜と考えられます」と明記し、断定しないでください。

---
name: Socratic Mentor
description: 実装前に設計判断を質問で確認するスタイル
keep-coding-instructions: true
---
 
実装に取りかかる前に、設計上の分岐点(データ構造・エラー処理方針・命名)を1つずつ質問してください。
回答を得てから実装に進みます。質問は一度に1つまでとし、矢継ぎ早に聞かないでください。

---
name: Commit Writer
description: 実装後に詳細なコミットメッセージ案を添えるスタイル
keep-coding-instructions: true
---
 
実装が終わったら、変更内容を要約したコミットメッセージ案を提示してください。
1行目は50字以内の要約、2行目以降に変更理由と影響範囲を箇条書きで示します。

---
name: JSON Only
description: 説明文を含めずJSONのみを返すスタイル
keep-coding-instructions: false
---
 
すべての応答をJSONのみで返してください。説明文・前置き・コードフェンスは付けません。
出力できない場合は {"error": "理由"} の形式で理由を返してください。

保存してテストし、チームやプラグインで配布する

ファイルを保存したら/configでOutput styleメニューから選び、動作を確認します。個人用に留めるか、チームで共有するかで保存先が変わります。

個人の好みなら~/.claude/output-styles/、プロジェクトの全員に配りたいなら.claude/output-styles/に置いてgitでコミットします。この使い分けはCLAUDE.mdとCLAUDE.local.mdの関係と同じで、リポジトリにコミットする=チーム共有、ホームディレクトリ止まり=個人設定という対応です。なお.claude/output-styles/は作業ディレクトリからリポジトリルートまでの各階層で読まれ、同名のスタイルが複数階層にある場合は作業ディレクトリに近い方が優先されます。

プラグインとして配布する場合は、プラグインルートのoutput-styles/ディレクトリに置くか、plugin.jsonのoutputStylesキーで既定のoutput-styles/を置き換える形で別パスを指定します。ゼロから作るならclaude plugin init <name> --with output-styleを実行します。このコマンドは~/.claude/skills/<name>/配下にプラグインの雛形一式を生成し、output-styles/にもひな形ファイルが1つ含まれます。--with output-styleで生成したスタイルは、プラグインが有効化されている間は自動で適用される設定になっています。

claude plugin init my-styles --with output-style

プラグイン配布では反映タイミングの違いを見落としがちです。SKILL.mdの変更はセッション中に即座に反映されます。一方でプラグインのoutput-styles/・hooks/・agents/・.mcp.jsonの変更は、/reload-pluginsかセッション再起動をしないと反映されません。チームメンバーに「更新したのに古いスタイルのまま」と言われたら、まずここを疑います。

配布方法を決めるときの目安は単純です。1人のプロジェクトなら.claude/output-styles/にコミットするだけで足ります。複数のプロジェクトをまたいで同じスタイルを配りたい、あるいは他社のフックやコマンドと一緒に配布したいなら、プラグイン化したほうが管理が一箇所に集まります。逆に配布の手間をかけたくない小さな組織では、プラグインの仕組みを覚えるコストのほうが上回ることもあります。プラグインの作り方・マーケットプレイスへの公開手順はプラグイン完全ガイドにまとめています。

よくあるつまずき

個人スコープに置いてチームに配布されていない

~/.claude/output-styles/はホームディレクトリなのでgit管理下になく、チームメンバーの環境には存在しません。チーム全員が使うスタイルは、.claude/output-styles/に置いてリポジトリにコミットするのが解決策です。

keep-coding-instructionsをtrueにしたのに指示が競合する

自作の本文が「コードを書くな」という趣旨なのにkeep-coding-instructions: trueにすると、組み込みのソフトウェアエンジニアリング指示と自作指示が矛盾します。矛盾する指示が同居すると、Claudeがどちらを優先するかは状況次第になり、挙動が安定しません。役割がコーディングを含まないならfalseに戻すのが確実です。

プラグインの更新が反映されない

前節のとおり、output-styles/はSKILL.mdと違って即時反映されません。更新後は/reload-pluginsを実行するか、次のセッションまで待ちます。

まとめ

自作output styleの設計はkeep-coding-instructionsの二択から始まります。5つのテンプレートはいずれもそのまま保存して試せる最小構成です。個人用かチーム共有かで保存先を~/.claude/output-styles/と.claude/output-styles/のどちらにするか決めます。プラグインとして配布するなら、/reload-pluginsが要ることも覚えておきます。そもそもoutput styleとCLAUDE.md・Skillsのどれを選ぶべきかで迷う場合は、3つの拡張機構の違いを参照してください。

よくある質問

カスタムoutput styleの本文を複数ファイルに分割できますか

公式ドキュメントに、CLAUDE.mdの@path/to/importに相当する分割記法は示されていません。output styleファイルは1つのMarkdownで完結させる前提です。共通部分を使い回したい場合は、テンプレート側で本文をコピーして管理する必要があります。

チーム全員に同じスタイルを強制することはできますか

force-for-pluginはプラグイン経由の強制適用専用で、プラグインを有効化した利用者に自動で適用されます。プラグインを使わない場合は、組織の管理ポリシースコープにoutputStyleを固定する方法が該当します。

自作スタイルの本文に文字数の上限はありますか

公式ドキュメントに文字数上限の明記はありません。ただし本文はそのままシステムプロンプトに追加されるため、長くするほど入力トークンとコンテキストの消費が増えます。役割の説明に必要な分量に絞るのが安全です。

動作確認のたびにセッションを再起動する必要がありますか

再起動までは不要です。output styleはセッション開始時に1回だけ読み込まれる設定なので、/clearを実行すれば新しいスタイルがすぐに反映されます。設定ファイルを直接編集した場合も同様で、次の/clearかセッション開始のタイミングで読み込まれます。

レビュー専任スタイルのような定番の型も自作の一種ですか

はい。レビュー専任・執筆専任のように役割を1つに絞ったスタイルは、いずれも同じ仕組み(frontmatter+本文のMarkdown)で作れます。本稿の5パターンはその中でも実装をさせない役割・実装を続けさせる役割の両方を1つずつ含むよう選んでいるので、まず近い用途のものをコピーして書き換えるのが早道です。