Claude Code の出力スタイル（output-style）を同じタスクで比べてみた

はじめに

こんにちは、けーまです。今回ジョイン記事以降初めての執筆になります。

何を書こうかとネタを探していて、Xを見ていたら「出力スタイル」という機能をちらっと見つけました。2025年8月15日に追加されたものですが、DevelopersIO にはまだ記事がなかったので、試してみることにしました。

ドキュメントを読んだだけだと違いがピンとこなかったので、同じプロンプトを4つのスタイルに投げて実際に比べてみました。

出力スタイル(output-style)とは

Claude Code のシステムプロンプトを差し替える仕組みです。/config から選ぶか、.claude/settings.local.json の outputStyle フィールドで設定します。

変更はセッション開始時に反映されるため、切り替え後は新しいセッションを起動する必要があります。

組み込みは3種類あり、カスタムで自前のスタイルを追加することもできます。

やること

以下の共通プロンプトを4つのスタイルそれぞれで実行して、生成されたコードの差を確認します。

ユーザー情報を管理するLambda関数を作ってください。
DynamoDBにget/put/deleteできるようにしてください。
TypeScriptで実装し、AWS SDK v3を使用してください。

環境

スタイルの設定方法

各フォルダに .claude/settings.local.json を置いてスタイルを指定します。

{
  "outputStyle": "Explanatory"
}

/config から GUI で設定する方法もあります。

カスタムスタイルは ~/.claude/output-styles/ にMarkdownファイルを置くと選択肢に表示されます。

やってみた

Default

コードだけが出てきます。余計な説明はありません。

ファイル構成は src/handler.ts / dynamodb.ts / types.ts の3分割。レスポンスヘルパーは types.ts にまとめて、handler から呼ぶ設計になっていました。

// default/src/handler.ts（抜粋）
  let body: Partial<PutUserInput>;
  try {
    body = JSON.parse(event.body);
  } catch {
    return errorResponse("Invalid JSON body", 400);
  }
  // ...
  return successResponse(user, userId ? 200 : 201);

指示していないのに PUT が新規作成なら 201、更新なら 200 を使い分けていました。JSON パースエラーを try-catch で個別に捕まえて 400 を返す処理も入っています。

Explanatory

コードの量はほぼ同じですが、コメントの密度が違います。

// explanatory/user-lambda/src/dynamodb.ts（抜粋）
// ハンドラ外で初期化することでコールドスタート後の接続を再利用
const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client, {
  marshallOptions: {
    // undefined値を自動的に除外する
    removeUndefinedValues: true,
  },
});

Lambda の最適化ポイントが、コメントとして実装に埋め込まれています。コードを読むと「なぜこう書いたか」が分かる状態です。ルーティングも Default の if-else から switch-case に変わり、POST/PUT を同一ケースにまとめた理由もコメントで補足されていました。

Learning

handleGet / handlePut / handleDelete と関数ごとに分割された骨格が生成されました。handleError だけが TODO(human) で残されています。

// learning/src/handler.ts（抜粋）
// TODO(human): エラーハンドリング戦略を実装してください
// 考慮すべきケース:
// - DynamoDBの接続エラー（503を返すべきか？）
// - JSONパースエラー（400 Bad Request）
// - 予期しないエラー（500 Internal Server Error）
// - ログ出力の粒度（エラー内容をレスポンスに含めるか否か）
function handleError(error: unknown): APIGatewayProxyResult {
  throw error; // placeholder: ここを実装してください
}

「動く骨格を渡すから、ここだけ自分で考えて」という構成です。TODO に設計上の考慮点まで書いてあるので、実装しながらエラーハンドリングの判断軸が自然に身につく作りになっています。

Custom（AWS Infra Advisor）

今回のカスタムスタイルは以下の定義です。~/.claude/output-styles/aws-infra.md に置いています。

---
name: AWS Infra Advisor
description: AWS インフラ構成の提案・解説に特化したスタイル。コード実装と合わせてインフラ構成の推奨事項、コスト・セキュリティの注意点を提示します。
keep-coding-instructions: true
---

## AWS Infra Advisor スタイル

あなたはAWSインフラの専門家として振る舞います。コードの実装に加えて、以下を必ず提示してください：

### 応答フォーマット

1. **実装コード** — 要求された機能を実装する
2. **インフラ構成メモ** — 必要なIAMポリシー、環境変数、関連AWSリソースを箇条書きで列挙
3. **コスト・パフォーマンス Tips** — DynamoDBのキャパシティモード選択など、コストに影響する選択肢を1〜3点
4. **セキュリティチェックリスト** — 最低限確認すべきセキュリティ設定を箇条書き

応答は日本語で行うこと。

生成されたコードは他のスタイルと同様に DynamoDBDocumentClient（Document API）を使用しており、types.ts / dynamodb.ts / index.ts の3ファイル構成になりました。keep-coding-instructions: true によってデフォルトのコーディング指示が維持されているため、コード品質や構造は他スタイルと揃っています。

keep-coding-instructions: true を指定することで、デフォルトのコーディング指示を残しつつ独自の指示を上乗せできます。

コードに加えて、インフラ構成メモが自動で出力されました。コードだけでなくデプロイに必要な周辺情報が一緒に出てくるのが特徴です。

気づいたこと

同じ指示でも API の設計が微妙に変わる

Default は PUT を新規/更新で 201/200 を使い分け、Explanatory は POST と PUT を同じルートで受け付けるなど、スタイルが変わるとコード設計の判断も変わります。どれが正しいということはなく、都度レビューは必要です。

Learning の TODO は実行ごとに変わる

今回は handleError のみが TODO でしたが、同じプロンプトでも実行するたびに「どこをTODOにするか」が変わります。

Explanatory の解説はコメントの形で残る

実行中に「Insights」セクションが追加で出るわけではなく、コメントとして実装の中に埋め込まれます。コードを読めば設計の意図が分かるので、チームで共有するコードに向いています。

カスタムスタイルはプロンプト設計が重要

keep-coding-instructions: true を使ったことで、ファイル構成や DynamoDB API の使い方はデフォルトのコーディング指示に従った状態になりました。カスタムスタイルで独自の指示だけを上乗せしたい場合はこのオプションが有効ですが、コードの方針を完全に自前で制御したい場合は keep-coding-instructions を省略して「ファイルは〇〇のように分割する」「DynamoDBDocumentClientを使う」といった指示をすべて定義に書く必要があります。

まとめ

Claude Code の出力スタイルを同じタスクで比べてみました。生成されるコードは基本的に同じ要件を満たしますが、コメントの量・ファイル構成・TODO の使い方・コード外の情報量がスタイルごとに変わります。

普段使いは Default、チームや新人向けには Explanatory、学習には Learning、カスタマイズしたい時は Custom と使い分けるのが合いそうだと思いました。理解の浅いプログラミング言語については Learning にして学習しようと思いました。

Tips

出力スタイル vs. CLAUDE.md vs. —append-system-prompt

• 出力スタイル
  デフォルトで組み込まれているソフトウェアエンジニアリング固有のシステムプロンプトを完全に無効化する。
• CLAUDE.md
  プロジェクト固有の要件、コーディング規約、コンテキストなどの前提条件を付与する。システムプロンプトの構築が完了した後、ユーザーからの入力の直前に、コンテキストとして挿入される。
• --append-system-prompt
  システムプロンプトの末尾に追加される。AIの基盤となる動作規定や制約事項を、システムレベルで拡張および追記する。

参考

• 出力スタイル - Claude Code 公式ドキュメント