explain-code

コードの解説

ワークフロー

1. たとえから始める — コードを日常生活で目にするものにたとえます
2. 適切な C4 レベルを選ぶ — 質問に合った図の詳細度にします。特に指定がなければレベル 2（コンテナー）を使います
3. 図を描く — 外部ツールは使わず、回答内に ASCII のボックス図を直接描きます。手順 2 に従って C4 レベルを選び、プレーン文字（+ - | v ^ <- ->）でボックスと矢印を組み立てます。ターミナルやチャットウィンドウで読みやすいよう、行の長さは約 80 列以内に収めます。各ボックスにはコンポーネント名（可能であれば 1 行の役割説明も）を記し、矢印にはその矢印に沿って流れるアクションやイベントを記します
4. コードの流れを説明する — 入力から出力までを文章でたどります。何が入り、どの関数やモジュールがどの順に処理し、どこで状態が変化し、何が出ていくのかを説明します。手順だけでなく、データ名も挙げます
5. 注意点を挙げる — よくある間違いや誤解について説明します

会話するような自然な口調で説明します。複雑な概念には、複数のたとえを使います。

出力例の形式

単一の関数

たとえ： debounce はスヌーズボタンのようなものです。操作をやめるまで、実行を遅らせます。

処理の流れ： 呼び出すとタイマーが開始します（setTimeout）。タイマーが作動する前に再度呼び出すと、タイマーを解除して再開します（clearTimeout）。タイマーが作動すると、コールバックが 1 回だけ実行されます。

注意点： 返される関数はクロージャーを通じて timer を保持します。呼び出し元ごとに専用の debounce(fn, ms) インスタンスが必要です。そうしないと、同じタイマーを共有してしまいます。

複数クラスのシステム

たとえ： この認証サービスは、クラブの用心棒のようなものです。部屋（エンドポイント）に入れる前に、身分証（トークン）を確認します。

+--------+   token    +----------------+   validate   +-------------+
| Client | ---------> | AuthMiddleware | -----------> | TokenCache  |
+--------+            +----------------+              +-------------+
                               |  claims
                               v
                       +---------------+
                       |  UserService  |
                       +---------------+
                               |  user record / UnauthorizedError
                               v
                       +---------------+
                       |   Endpoint    |
                       +---------------+

処理の流れ： リクエストが HTTP アダプターに到着し、AuthMiddleware が JWT を検証します。デコードされたクレームが UserService.resolve() に渡され、ユーザーレコードが返されるか、UnauthorizedError がスローされます。

注意点： AuthMiddleware はステートレスですが、TokenCache に依存しています。キャッシュが空の場合、リクエストのたびに DB にアクセスします。

マルチサービスアーキテクチャ

たとえ： このチェックアウトパイプラインはリレー競走のようなものです。各サービスは次の区間へバトン（注文イベント）を渡してから、次へ進みます。

+---------------+  order.created   +------------------+  stock.reserved   +-----------------+
| OrderService  | ---------------> | InventoryService | -----------------> | PaymentService  |
+---------------+                  +------------------+                    +-----------------+
       ^                                    |                                      |
       | 補償イベント（失敗時）             |                                      | payment.captured
       +------------------------------------+                                      v
                                                                         +----------------------+
                                                                         | NotificationService  |
                                                                         +----------------------+

手順： OrderService がメッセージバスに order.created を送信 → InventoryService が在庫を確保して stock.reserved を送信 → PaymentService が請求して payment.captured を送信 → NotificationService が確認メールを送信します。どの段階で失敗しても、上流をロールバックするための補償イベントが送信されます。

注意点： 各サービスは個別にデプロイできますが、Saga に中央のコーディネーターはありません。注文の失敗をデバッグするには、4つのサービスのログにわたって相関 ID を追跡する必要があります。

---

ベンチマーク

シナリオ：.benchmarks/scenarios/explain-code-001-worker-walkthrough.md · 実行：2026-08-31 · ログ：.benchmarks/runs/2026-08-31/explain-code-001-worker-walkthrough.json

モデル	なし	あり	差分
claude-opus-4-8	50%	100%	+50%
claude-sonnet-4-6	50%	100%	+50%
claude-haiku-4-5	50%	100%	+50%

合格（実行日：2026-08-31）。一律で +50 — 今サイクルで最大の最低値の引き上げです。.agents/skills/skill-optimizer/rules/release-gates.md に従ってゲートを確認してください。