code-quality

コード品質スキル

レビューしやすく、理解しやすく、変更しやすいコードを書きます。マシンの性能を最適化する前に、次の開発者の認知負荷を軽減します。読みやすいコードは変更、デバッグ、信頼が容易であり、性能向上の大半はマイクロ最適化ではなく、アルゴリズムの選択とプロファイリングによって得られるためです。

このスキルが対象とする品質の3つの軸は、優先度順に次のとおりです。

1. 可読性 — 読者がコードを最初から最後まで一度読めば理解できます。
2. 保守性 — 概念の次のバリエーションを追加する際の変更が、1つのファイルへの1回の編集で済みます。既存のユーティリティを再利用し、作り直しません。1つの概念には、正規の定義場所が1つだけあります。
3. 実用的なパフォーマンス — 既定ではアルゴリズムの改善を優先し、マイクロ最適化はプロファイラーが問題箇所を示した場合にのみ行います。

このスキルには、次の4つのモードがあります。

1. 計画モード — コードを書く前に Skill("code-quality", "plan") で起動します。plan.md（または提案されたアプローチ）と既存のコードベースを読み込み、計画の構成が既存のパターンに沿っていること、設計時に予測可能なリスク（時期尚早な並列マップ、ブランド付きプリミティブの欠落、型付けされていないエラーパス、パラメーターの増加、隣接箇所との不整合）を避けていることを検証します。検出結果のみを返し、コードは編集しません。autonomous-workflow のフェーズ1で使用します。詳しくは rules/plan-mode.md を参照してください。
2. 作成モード — 新しいコードを書くとき（TDD の GREEN フェーズや新機能など）に使用します。原則をその場で適用し、初版から基準を満たすようにします。引数が指定されていない場合の既定モードです。
3. レビューモード — コードを書いた後に Skill("code-quality", "code") または Skill("code-quality", "review") で起動します。リファクタリング、PR のレビュー、「これを整理して」と依頼された場合に使用します。ルールに照らして問題を診断し、対象を絞った変更を提案します。検出結果のみを返し、コードは編集しません。
4. 簡素化モード — 機能の実装とテストの成功後に Skill("code-quality", "simplify") で起動します。レビューを実施した後、rules/refactor-recipes.md のクラスMのレシピ（機械的な変更）を、Skill("confidence", "code") ≥ 90 % の確信度と対象を絞った高速チェックを条件に、1つずつ適用します。失敗した場合は元に戻します。判断を要するクラスJのレシピは提案にとどめます。詳しくは rules/simplify-mode.md を参照してください。バリエーション：simplify aggressive は影響度が中程度の機械的なレシピも自動適用します。simplify dry-run は変更を加えずに結果を報告します。simplify <path> は差分ではなく指定したパスを対象にします。

$ARGUMENTS の最初のトークンからモードを判定します。plan → 計画モード、code または review → レビューモード、simplify → 簡素化モード、それ以外（引数なしも含む）→ 作成モードです。なお、ユーザーが「レビュー」または「監査」と依頼した場合は、その場での呼び出しでも従来どおりレビューモードになります。

---

中心となる考え方

認知的複雑性、つまりコードの理解しにくさは、長期的な保守性を示す最も優れた指標です。SonarSource の研究によると、サイクロマティック複雑度（経路の数え上げ）では、人間に実際の負担をもたらす要素、つまりネスト、分断された直線的な流れ、積み重なる条件判断を捉えられません。そのため、以下のルールでは理論上の複雑度スコアではなく、認知負荷を対象とします。出典の全文（SonarSource、Clean Code、Knuth、Alexis King、Gary Bernhardt）と各ルールの研究的根拠は、references/citations.md に記載されています。

迷ったときは、次のヒューリスティックを使います。読者は、後戻りせずに関数を最初から最後まで一度読めば理解できますか？ できるなら、そのままリリースしましょう。スクロールしたり、別の場所に移動したり、条件をいくつも頭に留めたりする必要があるなら、改善してください。

保守性については、次の点を考えます。この概念に次の明白なバリエーションを追加する場合、何個のファイルを編集する必要があり、1つ漏らしたときに型システムで検出できますか？ 1つのファイルで型を完全に網羅できるなら優れています。一方、4つのファイルにある4つのマップを手作業で同期するのはショットガン手術です。バリエーションを追加する前に、構造を修正してください。詳しくは rules/maintainability.md を参照してください。

---

クイックリファレンス（これらのパターンを作業メモリに読み込んでください）

コードスメル	リファクタリング先	理由
ネストした if（3階層以上）	ガード節＋早期リターン	インデントが増えるたびに認知負荷が増します。フラットなほうが読みやすくなります
長い関数（50行以上、複数の責務）	意図ごとに切り出し、方法ではなく内容を表す名前を付ける	1つの関数＝変更する理由は1つです
意味の分かりにくい名前（d、tmp、data）	ドメインを表す名詞（priceDifference、pendingOrders）	名前はドキュメントそのものです
ブール値の引数	名前を付けた2つの関数、または列挙型	send(true, false, true) は読みにくくなります
WHAT を説明するコメント	名前を変更するか、関数を切り出す	コメントは古くなりますが、名前はコードとともにリファクタリングされます
WHY（自明でない制約）を説明するコメント	残す	唯一、残す価値のあるコメントです
起こり得ない状態への防御的チェック	削除する	呼び出し元を信頼し、境界で検証します
フラグ／オプションのまとまり（引数4個以上）	オブジェクト引数またはビルダー	作業記憶で保持できるのは約4つのまとまりです
return／throw の後の else	else を削除する	分岐よりも直線的なフローのほうが分かりやすくなります
マジックナンバー／文字列	名前付き定数	将来の自分は 7 の意味を覚えていません
同じユニオンを対象とする並行マップ（Status をキーにする LABELS、COLORS、ICONS）	1つの Record<Status, { label, color, icon }>	バリアントの追加が、N箇所の編集ではなく1箇所の編集になります
すでに存在するヘルパーの再実装	まず検索し、既存のものを使う	実装が2つあると差異が生じ、バグは片方だけで修正されます
値に応じて振り分ける if/else if の連鎖	ルックアップテーブルまたは単一の信頼できるレコード	制御フローよりデータ構造のほうが拡張しやすくなります
同じ定数（MAX_RETRIES、ステータス文字列）のファイル間での重複	1つの共有モジュールに集約する	1つの概念には、1つの置き場所を用意します
新しいバリアントの追加に4つ以上のファイルの編集が必要	バリアントを追加する前に集約する	ショットガン手術は、バリアントを追加するたびに悪化します
同じ形状に対する別々の type User = {...} と userSchema = z.object({...})	スキーマを1つにし、type User = z.infer<typeof UserSchema> とする	宣言が2つあると差異が生じます。1つなら生じません
スタックの深い場所で、すでに解析済みの値を再検証する	境界で一度だけ解析し、内部では型を信頼する	検証は境界で行うものであり、呼び出しごとに行うものではありません
「整理のため」にネストしたオブジェクトをすべて独自のサブスキーマに分割する	サブ形状を再利用する場合、または独自の境界がある場合を除き、フラットに保つ	分解が早すぎると、過剰設計になります
オーケストレーションの説明と低レベルの処理が混在する関数	抽象化レベルごとに切り出す（R16）	読み手は、自分が必要とするレベルで読み進められます
「この2つのフィールドは同時に設定できない」ことを強制するランタイムチェック	判別可能なユニオン（R15）	コンパイラーが不変条件を強制するため、ランタイムチェックは不要になります
Email、UserId、OrderId に生の string を使う	スキーマを介して型にブランドを付ける（R11）	ID の混同がコンパイルエラーになります
型チェッカーを黙らせる any や根拠のないキャスト	スキーマ解析、絞り込んだ unknown、または // because: コメント（R17）	根拠のない any は、型のバグで最もよく見られる形です
関数が Date.now()／Math.random() を直接呼び出す	クロック／乱数生成器を注入する（R9）	純粋関数はテスト可能で、不純な関数は不安定です
「見つからない」場合に関数が例外を投げる、またはセンチネル値（-1、""）を返す	全域化し、null または Result<T, E> を返す（R10）	全域関数なら網羅的にテストできます
すべてのエラーで、解析済みメッセージを持つ同じ Error を投げる	判別可能な AppError ユニオン	文字列の解析より構造化されたフィールドのほうが適しています
モジュールのインポートで副作用が発生する	ファクトリー：createX(...)（R20）	テストが意図せず統合テストになることを防げます
リトライされる可能性のある操作を2回実行しても安全ではない	冪等性キー、アップサート、または適切な HTTP メソッド	そうしないと、リトライで状態が破損します
金額を number として保存する	整数の最小通貨単位、または小数ライブラリ	浮動小数点数では10進通貨を正確に表現できません
浮動小数点数を === で比較する	イプシロンを使って比較する、または整数の刻み幅を使う	0.1 + 0.2 !== 0.3
Promise.all を使うべき箇所で for ループ内に await がある	逐次実行か並列実行かを意識して選ぶ	意図しない逐次化はパフォーマンス上のバグです
対応する close のないすべての open	try/finally または using	リソースリークは気付かないうちに積み重なります
新しいファイルが隣接するファイルのパターンに合っていない	隣接するファイルを2～3個読み、同じパターンに合わせる	例外的なコードがあると、読み手は毎回コンテキストを切り替える必要があります
リファクタリングの PR と機能追加の PR が混在している	2つの PR に分ける	混在した PR は、誤った基準で形式的に承認されたり、却下されたりします
ファイルの先頭にヘルパーがあり、公開関数が200行下にある	公開 API を先に置き、ヘルパーを呼び出し順に下へ置く	ファイルは上から下へ読み進められます
a に作用するために a.b.c.d.method() までたどる	問い合わせるのではなく指示する：操作を a に置く	呼び出し元が非公開の構造をたどる必要はありません

スタック別の重要パターン

特に効果の高い、スタック固有のルールをいくつか紹介します。rules/stacks/ の各ルールファイルには、「よくある間違い」セクションがあります。そのスタックで作業するときに、該当するファイルを読み込んでください。

問題の兆候	リファクタリング先	場所
6 個以上の props（特に boolean）で見た目のバリエーションを制御する React コンポーネント	深いドット記法（Combobox.Content.List.Item）を使う複合コンポーネントと、名前空間付きの制御フック（Combobox.useCombobox）。Context 経由で状態を共有	stacks/react/components.md
サーバーデータの取得に使われる useEffect(() => { fetch(...).then(setData) }, [id])	useQuery({ queryKey, queryFn })（TanStack Query / SWR）	stacks/react/data-fetching.md
ミューテーションで、UI の更新前にサーバーの応答を待つ	onMutate で楽観的更新し、onError でロールバック、onSettled で無効化	stacks/react/data-fetching.md
キー入力のたびにフォームを保存する	約 1000 ms のデバウンス＋最大待機時間約 5 秒でのフラッシュ＋フォーカスが外れたとき＋表示状態が非表示になったときに保存する。入力をブロックしない	stacks/react/autosave.md
2 つのタブが同じレコードを自動保存し、一方がもう一方の変更を何も通知せず上書きする	ETag＋If-Match。412 の場合は「別の場所で編集されました — 再読み込み／自分の変更を維持」を表示	stacks/react/autosave.md
再読み込みでミューテーションが失われ、場当たり的な再試行処理がコンポーネント間に散在する	IndexedDB に永続的なミューテーションキューを作り、各エントリに冪等性キーを付与する。navigator.locks で複数タブ間の単一ライターを実現	stacks/react/offline-sync.md
ルートハンドラーが検証せずに req.json() の本文を信頼する	共有 Zod スキーマ（FE と BE が同じモジュールをインポート）で safeParse を使い、判別可能な AppError ユニオンから共通のエラー形式にマッピング	stacks/nextjs/endpoints.md

---

手順

このスキルには 4 つのモードがあります。plan（計画の検証）、authoring（新しいコードの作成）、review（リファクタリング／監査。指摘事項のみ）、simplify（レビュー後、機械的なレシピを自動適用）です。上の表に従って $ARGUMENTS からモードを判定してください。デフォルトは authoring です。

authoring（13 ステップのチェックリスト）と review（8 ステップのチェック）では、rules/procedure.md を読み込んでください。simplify の手順（分割 → 確信度による判定 → レシピを 1 つずつ適用 → 対象を絞った簡易チェック → 失敗時に元に戻す → 最後に全体のテストスイートを検証）では、rules/simplify-mode.md を読み込んでください。

---

ルールファイル

目の前のコードに関連するものだけを読み込んでください。毎回すべてのルールファイルを読むのは、コンテキストの無駄です。このスキルの中核部分は言語に依存しません。下の表では、フレームワークに依存しないルールと、スタック固有の拡張を分けています。コードが該当するスタックで書かれている場合にのみ、スタックのファイルを読み込んでください。

言語に依存しないルール

コードに次の要素が含まれる場合	読み込むファイル
条件分岐、分岐処理、ネスト	rules/control-flow.md
長い関数、または複数の目的を持つ関数	rules/functions.md
変数名、関数名、クラス名	rules/naming.md
コメント、docstring、ドキュメント	rules/comments.md
パフォーマンス上の懸念、またはホットパス	rules/performance.md
エラー処理、バリデーション、防御的なコード、スキーマ優先のバリデーション、Zod / Pydantic、スキーマからの型推論	rules/error-handling.md
既存コードのレビュー	rules/review-checklist.md
認知的複雑度のスコアリング	rules/cognitive-complexity.md
関連データを持つユニオン型、並列マップ、重複した定数、「どこに配置するか」、再利用の判断	rules/maintainability.md
抽象化レベル、型駆動設計、表現可能な不正状態をなくすこと、ブランド付きプリミティブ、ジェネリクス、any / キャストの規律	rules/abstraction.md
モジュール境界、公開範囲、依存関係の方向、関数型コア／命令型シェル、DTO ↔ ドメイン ↔ 永続化、イミュータビリティのデフォルト、インポートによる副作用	rules/architecture.md
関数シグネチャ、パラメーターの順序、全域関数、不在のモデリング、エラー型システムの設計、tell-don't-ask、ファイルの読み取り順序	rules/api-design.md
冪等性、金額／小数／浮動小数点数、日付と時刻、識別子、エンコーディング、決定性、アサーション、非同期処理／並行処理、リソース管理	rules/correctness.md
テストしにくいコード、時計／乱数生成器／ID の依存性注入、tdd スキルを呼び出すタイミング、data-testid なしでロール／ラベルから特定できる UI コンポーネント	rules/testability.md
PR のスコープ、隣接するパターン間の対称性、移行と進化、レガシーコードの扱い、差分の整理	rules/collaboration.md
レビュー結果でのリファクタリングの命名（R1 並列マップの統合、R6 型宣言を推論型に置き換える、など）	rules/refactor-recipes.md
機能実装の最後に機械的なリファクタリングを自動適用すること（レビュー後に適用、信頼度に応じた適用、失敗時の取り消し）	rules/simplify-mode.md

スタック固有のルール

インデックスと、新しいスタックを追加する際の規約については、rules/stacks/README.md を参照してください。

スタック	コードに次の内容が含まれる場合…	読み込むもの
React / Next.js	UI ファイル（*.tsx、*.jsx、React Native の画面）全般 — セマンティック HTML、ARIA、WCAG 2.2 準拠、フォーカス順序、コントラスト、プラットフォームのガイドライン（Apple HIG、Material Design 3）	Skill('ux')（別のスキル）
React	コンポーネントの分割、複合／名前空間コンポーネント（Component.List.Item、Component.useComponent）、スロット、RSC の境界	rules/stacks/react/components.md
React	クライアント側のデータ取得、サーバー状態、クエリーキャッシュ、楽観的更新、キャッシュの操作（作成／更新／削除）、クエリーキー、リクエストのウォーターフォール、TanStack Query / React Query / SWR、Next.js App Router のプリフェッチ、HydrationBoundary、dehydrate、initialData、リクエストごとの QueryClient	rules/stacks/react/data-fetching.md
React	自動保存フォーム、デバウンス＋最大待機時間でのフラッシュ、フォーカス喪失／可視性／pagehide 時のトリガー、ローカル優先の下書きバッファ（localStorage / IndexedDB）、ARIA ライブリージョンを使ったステータスインジケーター、ETag / If-Match による競合検出、冪等な PATCH によるオフライン時の再試行（フォームの基本については /ux に委ねます）	rules/stacks/react/autosave.md
React	アプリ全体のオフライン対応＋同期、IndexedDB の永続的なミューテーションキュー／アウトボックス、フォアグラウンドキューと Background Sync、TanStack Query の networkMode ＋永続化＋resumePausedMutations、冪等性キー、再接続フロー、競合解決、複数タブ間の調整（navigator.locks ＋ BroadcastChannel）	rules/stacks/react/offline-sync.md
Next.js	サーバーエンドポイント、Route Handlers / Server Actions、Zod による境界検証、共有スキーマ／コントラクト（FE ＋ BE）、API エラーエンベロープ、HTTP ステータスのマッピング、認証とレート制限の順序、リクエスト ID、semconv 属性を付与したハンドラー全体のトレース（詳しくは /otel-instrumentation ＋ /otel-semantic-conventions に委ねます）	rules/stacks/nextjs/endpoints.md

---

重要なルール（常に適用）

これらはスタイル上の好みではなく、人間の認知能力の限界を反映しているため、妥協できません。

1. 分岐よりも直線的な流れを優先する

上から下へと流れる関数 — ガード、ロジック、return の順 — は、深く分岐する関数より常に理解しやすくなります。if/else if/else が30行にわたる場合は、構成を見直してください。

2. 名前に意味を込める

コードは書くときよりも10倍多く読まれます。意図を説明する30文字の名前は、入力にかかる時間以上の時間を節約できます。反対に、意味が文脈から明らかな狭いスコープ（ループのインデックスや数式など）では、1文字の名前でも問題ありません。

3. 関数は1つのことを表す

関数名は、その関数が何をするのかを完全に説明する必要があります。正直に名前を付けると validateAndPersistAndNotifyUser になるなら、それは3つの関数に分けるべきです。

4. まだ訪れていない未来に備えて作り込みすぎない

仮定上のニーズに備えた設定パラメーター、抽象化レイヤー、機能フラグは、実現するまでは何の利点もないまま、今すぐ認知負荷を増やします。そして、その仮定のほとんどは実現しません。目の前のケースに対応し、2つ目のケースが現れたらリファクタリングしてください。

5. コメントでは「何を」ではなく「なぜ」を説明する

コードを言い換えただけのコメントはノイズです。一見分かりにくい制約や、微妙な不変条件、あるいは「Xを試したが、Yのためうまくいかなかった」という説明は価値があります。コメントを書きたくなったら、まず名前を変えたり、処理を切り出したりして、コード自体が説明するようにしてください。

6. 測定してから最適化する

Knuth の言葉にあるように、「早すぎる最適化は諸悪の根源」です。プロファイラーがホットパスを示すまでは、読みやすい実装を優先してください。パフォーマンスを左右するのはコードの約3%だけです。残りの97%は、人間が読みやすいように最適化してください。

7. 境界で検証し、内部では信頼する

ユーザー入力、外部 API のレスポンス、信頼できないデータは境界で検証してください。 内部コードのあちこちに防御的な null チェックを追加しないでください。あり得ない状態を黙って処理してしまい、実際のバグを見えにくくするためです。このコードの時点で値が null になり得ないなら、なり得るかのように扱わないでください。

8. 新しく作る前に再利用する

ヘルパー、型、定数、フォーマッターを書く前に、既存のものがないかコードベースを検索してください。同じ概念を二重に実装するのは、最初の実装よりも悪い結果を招きます。動作に差が生じ、バグ修正が片方にしか適用されず、次に読む人はどちらが正式な実装なのかわからなくなります。既存コードの再利用が早すぎることはありません。

9. 共用型のメタデータは信頼できる情報源を一つにする

共用型や列挙型に関連データ（ラベル、色、アイコン、フラグ、デフォルト値）がある場合は、N 個の並列マップではなく、構造化された値を持つ、共用型をキーとした一つのレコードにまとめてください。新しいバリアントの追加は一度の編集で済み、フィールドを見落とした場合は型システムが検出できるようにしてください。OrderStatus に対して手作業で同期する 4 つのマップは、いずれ本番環境に紛れ込むバグの温床です。

10. 変更の影響範囲を最小限にする

保守しやすい変更は、型チェックがすべて通る少数のファイルに収まります。概念に新しいバリアントを追加する前に、次のように考えてください。「次のバリアントを追加するとき、編集が必要な箇所はいくつあるか。見落としがあればコンパイラーが教えてくれるか」。答えが「たくさん」または「いいえ」なら、まず構造を見直してください。通常は、並列マップを統合する、重複した定数を共通の場所に移す、またはデータをその操作と同じ場所にまとめることで解決できます。rules/maintainability.md §3 を参照してください。

11. 不正な状態を表現できないようにする

バグを検出するのに最もコストが低いのは、そのバグが存在できない場所です。制約を型システムに取り込みましょう。状態マシンには判別共用体を、網羅性の確認には assertNever を使った網羅的な switch を、プリミティブ型にはブランド型を、制約付きの型には精緻化型（NonEmptyArray<T>）を使ってください。型システムで強制できるランタイムガードは、やがて実態とずれていくノイズです。rules/abstraction.md §2 を参照してください。

12. 純粋なコア、不純なシェル

意思決定ロジックは純粋にします。I/O、時刻、乱数、グローバル状態を使わないでください。副作用は境界にある薄いシェルに置きます。純粋なコードはテストや推論のコストが最も低く、不純なコードは避けられませんが、結合テストで検証できるほど小さく保つ必要があります。時計、RNG、フェッチャー、ID 生成器は、直接呼び出すのではなく注入してください。rules/architecture.md §3 と rules/correctness.md §7 を参照してください。

13. 見つからない場合に例外を投げるより、全域関数を使う

すべての入力に対して定義済みの出力がある関数を、全域関数といいます。仕様上存在しない場合は null を、想定される失敗には Result<T, E> を返してください。throw はプログラマーのミスや予期しない I/O の失敗に限って使います。番兵値（-1、""、0）は嘘をつきます。すべての番兵値は、次の呼び出し元が遭遇する実際の値と衝突します。rules/api-design.md §4 を参照してください。

14. 新しいコードはテストファーストで

新しい関数、モジュール、振る舞いを実装するときは、tdd スキル（Skill('tdd')）を呼び出し、厳密な RED → GREEN → REFACTOR サイクルに沿って実装してください。GREEN ではこのスキルのルールを明示せずに適用し、REFACTOR では明示的に適用してください。引き継ぎを省略できるのは、些細な編集、既存コードのリファクタリング、またはユーザーが希望しない場合に限ります。rules/testability.md を参照してください。

15. UI ファイルでは ux と連携する

UI を描画するファイル（*.tsx、*.jsx、*.vue、*.svelte、React Native の画面）を作成またはレビューするときは、WCAG 2.2、セマンティック HTML、プラットフォームのガイドラインに沿った確認のために、ux スキル（Skill('ux')）を呼び出してください。アクセシビリティは ux の担当であり、このスキルの範囲外です。ここでは ux に委ねます。アクセシブルな名前を E2E テストの安定性にも役立てるため、rules/testability.md（UI Testability セクション）のロケーター安定性に関する項目を適用してください。UI 以外のファイル、またはマークアップに触れない純粋なリファクタリングの場合に限り、省略できます。autonomous-workflow の Phase 3 で呼び出された場合は、そこで ux が直接実行されます。二重に呼び出さず、フェーズレベルの呼び出しに任せてください。

---

意見が対立する場合

原則同士が衝突する場合は、判断に迷ったときの基準について rules/tradeoffs.md を読み込んでください（可読性とパフォーマンス、DRY と明快さ、再利用と時期尚早な抽象化、短い命名と明確な命名、ガード節と単一の戻り値、同じ場所への配置とレイヤー別のフォルダー）。

---

出力規約

レビュー モードでは、指摘事項を ## Code Quality Review: [target] ブロックにまとめ、影響度が高・中・低のセクションを設けてください。さらに、レビュー対象のコードでユニオン型、列挙型、共有定数、ユーティリティを導入または拡張する場合は、保守性に関する指摘事項を必ず含めてください。再試行可能な操作、金額、日付、非同期 I/O、リソースハンドル、または自明ではない純粋ロジックに関わる場合は、正確性／テスト容易性に関する指摘事項も必ず含めてください。完全なテンプレートについては rules/output-contract.md を読み込んでください。

作成モードでは、コードだけを書いてください（新しいコードの場合は、まず tdd に引き継いでもかまいません）。原則は表に出さずに適用してください。ガード節の一つひとつについて説明する必要はありません。ユーザーには差分のすっきりしたコードが見えます。