Claude Codeに実装を任せたあと、返ってきた説明が読みにくいと感じたことはないでしょうか。聞き慣れない用語や略語が並び、一文が長く、結論がどこに書かれているのかを探すことになります。私も毎回「わかりやすく書いて」と指示していましたが、セッションを新しくするたびに元に戻っていました。
この記事では、output styleというファイルを1つ書いてこの問題を解決した方法と、同じことをhooksで実現する場合との違いを説明します。実際に使っているファイルの中身もそのまま載せます。
アストラルコードではループエンジニアリングという、AIエージェントに開発工程を任せる進め方を実践しているため、AIの出力を読む時間そのものが作業時間を圧迫する場面を何度も経験してきました。
Claude Codeの出力がわかりにくくなる理由
- 出力が長くなる
- なじみのない単語や省略語を使う
ことが原因だと考えています。
AIのモデルがどんどん賢くなるにつれ、一度に扱えるコンテキスト量が莫大に増えると同時に、ユーザーに出力される文章も長くなる傾向にあります。
実際にAnthropicもclaude opus5が出てきてから出力が長くなると公式に言っています。
また特に私が困っていたのは、たとえば次のような説明です。
「本質的には、リレーションシップの所有権という観点において、双方のモデルが相互に参照関係を確立しようとしている構造になっています。」
この文が言いたいのは「原因は、両方のモデルで外部キーを定義していることです」ということだけです。内容は同じでも、読み取りに時間がかかります。
output styleを書いて出力の書き方を固定する
上記の問題を解決するために、output styleを独自で定義して解決することにしました。
output styleは、Claude Codeのシステムプロンプトに自分の指示を追加する仕組みです。会話ではなくシステムプロンプト側に入るため、毎回の応答に効き続けます。
システムプロンプトとは、モデルが応答する前にあらかじめ読み込む指示文のことです。Claude Codeにはソフトウェア開発向けの指示が最初から入っており、応答の組み立て方はここで決まります。会話の中で「短く書いて」と伝えても、それは会話の一部として扱われるだけです。やり取りが長くなると、後から入ってくるコードやツールの実行結果に押されて効きが弱くなります。セッションを新しくすれば指示そのものが消えます。
作り方は、マークダウンファイルを次のどちらかの場所に置くだけです。
- 自分の環境だけで使う場合：~/.claude/output-styles/
- チームで共有する場合：プロジェクト直下の .claude/output-styles/（リポジトリに入れて共有できます）
ファイルの先頭にはフロントマターを書きます。keep-coding-instructionsをtrueにすると、Claude Codeに元から入っているソフトウェア開発向けの指示を残したまま、自分の指示を追加できます。指定しない場合はfalseになり、開発向けの指示が外れます。説明の書き方だけを変えたい場合はtrueにしてください。
私が実際に使っているファイルは次のとおりです。
---
name: Plain Japanese
description: Clear and concrete Japanese explanations for software engineering
keep-coding-instructions: true
---
# Communication style
Write explanations in clear, ordinary Japanese.
The reader is a software engineer.
Do not simplify the technical content.
Simplify only the language used to explain it.
## Core rules
- State the conclusion first.
- Use short sentences.
- Prefer concrete wording over abstract wording.
- Do not invent metaphors, jargon, shorthand, or clever terminology.
- Do not use vague phrases when you can name the actual code, field, function, or behavior.
- Do not narrate what you are about to do.
- Do not repeat the same conclusion in different words.
- Do not add background information unless it helps solve the current problem.
When explaining an error, use this order:
1. 原因
2. どこがおかしいか
3. どう直すか
4. 修正後のコード
Prefer:
「原因は、両方のモデルで外部キーを定義していることです。」
Avoid:
「本質的には、リレーションシップの所有権という観点において、
双方のモデルが相互に参照関係を確立しようとしている構造になっています。」
When technical terminology is necessary, use it.
Immediately explain what it means in ordinary Japanese.
If you must choose between concise and clear, choose clear.
日本語では自然な口語寄りの「です・ます調」で説明する。
翻訳調、論文調、過度に抽象的な表現を避ける。書くときに意識した点は3つです。
- 結論を先に書かせ、一文を短くさせています。
- 比喩や独自の略語を作ることを禁止しています。曖昧な言い回しではなく、実際の関数名やフィールド名を書かせます。
- 避けたい書き方と使ってほしい書き方を、実例のペアで示しています。抽象的な指示だけを並べるよりも効きます。
適用するには、/config を実行して Output style から選ぶか、設定ファイルの outputStyle にスタイル名を書きます。output styleはセッション開始時に一度だけ読み込まれるため、変更は /clear の後か新しいセッションから反映されます。
導入後は、結論が先頭に来るようになり、専門用語が出るときはその場で日本語の説明が付くようになりました。出力を読み直す回数が明確に減っています。
以下「claude codeとは？」という質問をoutput style適用前と適用後で比較したものです。
afterのほうがわかりやすくなっています。
簡単な指示なのでそこまで差はないですが、難しい指示になるほど効果が出ます。
before
after
hooksに書く場合との違いと使い分け
同じことはhooksでもできそうに見えますが、仕組みが違います。hooksは、セッション開始時やプロンプト送信時などの決まったタイミングでコマンドを実行し、その出力を会話に差し込む仕組みです。
違いは3点あります。
- 差し込む場所：output styleはシステムプロンプトを書き換えます。hooksは会話の中に文章を追加します。会話に入れた指示は、後から入るコードやツールの実行結果に押されて効きが弱くなることがあります。
- 適用の範囲：output styleは選択している間、すべての応答に効きます。hooksは設定したイベントが発生したときだけ動きます。
- 必要な作業：output styleはファイル1つで済みます。hooksは実行するコマンドとJSONの設定が必要で、保守する対象が増えます。
そのため、使い分けは次のようにしています。
- 文章の書き方や口調を常に同じにしたい場合はoutput styleに書きます。
- 状況によって内容が変わる情報を渡したい場合や、機械的な処理をしたい場合はhooksに書きます。たとえば現在のブランチ名を毎回伝える、コードの変更後にフォーマッタを自動実行する、といった用途です。
1つ注意点があります。output styleが効くのは本体の会話だけです。サブエージェントは自分のシステムプロンプトで動くため、スタイルは適用されません。
まとめ
- Claude Codeの出力の書き方はシステムプロンプトで決まるため、毎回の会話の前の指示では安定しません。
- output styleはシステムプロンプトに指示を追加する仕組みで、ファイル1つで書き方を固定できます。
- keep-coding-instructionsをtrueにすると、開発向けの指示を残したまま説明の書き方だけを変えられます。
- 常に効かせたい書き方はoutput style、状況に応じた情報の注入や機械的な処理はhooksに書きます。
まずは、避けたい書き方と使ってほしい書き方を1組ずつ書いただけのファイルを作り、1日使ってみてください。それだけでも出力の読みやすさは変わります。合わなければファイルを消せば元に戻るので、試す手間はほとんどかかりません。
