coding-standards

コーディング規約

記述、編集、レビューするすべての行は、これらのルールに従う必要があります。ルールは2つのセットに分かれており、各タスクでは 共通ルール + いずれか1つのフレームワークルール を適用します。

• 共通ルール（references/common/） — 言語を問わず、すべての関数、クラス、モジュールの 内部 に適用されるクリーンコードの原則です。
• フレームワーク別ルール（references/<framework>/） — ファイルの配置場所やフォルダーの意味など、外部 を規定するフォルダーレイアウトとフレームワークのパターンです。

このドキュメント内のパスはすべて、この SKILL.md ファイルからの相対パスです。そのため、スキルがどこにインストールされていても解決されます。

手順の流れは、ブートストラップ（最初に1回）→ 除外対象をスキップ → モードを選択 → フレームワークを検出 → 構造を解決 → 実行形式を選択 → タスクリストを開く → 分岐を実行 です。ステップ0～6がこの流れで、ステップ7が分岐（7a パイプライン、7b インライン）です。

---

ステップ0 — 強制適用フックをブートストラップする（セッションごとに1回、必要な場合のみ）

まず、読み取り専用の簡易チェックを実行します（絶対パスを使った単一のコマンドで、cd や && は使いません。事前承認済みの権限ルールに合致するため、プロンプトは表示されません）。

python3 <skill-dir>/bootstrap.py --verify

終了コードが0の場合 → フックは設定済みです。ステップ1に進みます。0以外の場合 → 完全インストールを実行し、その出力に応じて対応します。

python3 <skill-dir>/bootstrap.py --auto-install

• Wired / Updated / Install OK → フックを有効にするため、セッションを再起動するようユーザーに伝えてください。 再起動するまでは、このセッションで PreToolUse フックは有効になりません（Claude Code はセッション開始時に settings.json を読み込むため）。そのため、ここで Write を実行してもブロックされません。これが、強制適用されない初回セッションのギャップです。このギャップを埋めるため、このセッションで記述またはレビューするコードには、完了を報告する前に、補完チェックとして変更対象ファイルに対して自分でリンターを実行してください。 python3 <skill-dir>/hooks/review-files.py <file> … は再起動せずにすぐ実行でき、検出された問題は修正してください。書き込み時のブロックは次のセッションから有効になり、このセッションでは手動のリンター実行で対応することをユーザーに伝えてください。
• Blocking issues: → その内容をそのまま提示し、ユーザーが解決するまで停止してください。
• cannot determine install scope → スキルが .claude/skills/ ツリーの外にあります。README.md を案内し、書き込み時のブロックは行わずに続行してください。ルールは引き続き適用され、review-files.py も手動リンターとして実行できます。

インストール処理は、プロジェクト単位かグローバルかを自動検出し、スキルに必要なパッケージを自動インストールします。フラグ、venv／PEP-668 のフォールバック、準備状況の内訳については references/bootstrap.md を参照してください。ブートストラップに問題が発生した場合にのみ読みます。

---

ステップ1 — 除外対象ファイルをスキップする（常に）

一部のファイルはユーザーではなくサードパーティ製ツールが管理しています。それらを編集すると、アップグレードできなくなったり、生成コードに不要な変更が発生したりします。以下のいずれかに該当するファイルは除外対象です。

1. パスが組み込みのデフォルト（インストール済み依存関係、生成コード、ビルド出力、ロックファイル、ORM マイグレーション、shadcn components/ui/**、スキル独自の .coding-standards/** レポート）に一致する場合。全リストは hooks/_exclusions.py → DEFAULT_EXCLUSIONS にあります。
2. ファイルの先頭10行に生成を示すマーカー（@generated、DO NOT EDIT、Code generated by など）がある場合。
3. プロジェクトのルートにある .coding-standards-ignore（gitignore 形式。ブートストラップ時に作成）内のパターンに一致する場合。

確認は、パスをデフォルトリストと照合し、読み取り対象のファイルにあるマーカーを確認し、存在する場合は ignore ファイルを調べて行います。手作業で除外せず、レビューと修正の対象を絞り込んでください。hooks/review-files.py は除外対象を自動でスキップし、書き込み時のフックもそれらのファイルでは何もせず終了します。

除外対象ファイルの変更は拒否してください。ユーザーが明示的に編集を求めた場合は、そのファイルはツール管理であり、再生成時に変更が失われることを警告してから、同意を得た場合にのみ作業を進めてください。

---

Step 2 — モードを選ぶ（コンテキストなしで起動した場合のみ）

ユーザーのメッセージですでにタスクが示されている場合は、この手順をスキップしてください。「X を書いて」「Y をリファクタリングして」「この PR をレビューして」「これはきれいですか？」「FN-005 の意味は？」などのフレーズ自体がモードを示しています。Step 3 に進んでください。

スキルが明確なタスクなしで起動した場合にのみ、この手順を実行してください。単独の /coding-standards、「このスキルでは何ができますか？」、またはモードを推測するには曖昧すぎるメッセージなどが該当します。AskUserQuestion を使い、references/activation.md にあるモード選択のペイロードをそのまま使用してください。ラベルは以下のルーティング条件に一致するものです。

回答に応じてルーティングします。

• これらのルールに従ってコードを書く → Write モード、全フロー。
• 既存のコードがこれらのルールに準拠しているか確認する → 何を確認するか（ファイル、フォルダー、差分、PR）を尋ねます。ユーザーが回答した時点で対象範囲が確定するため、レビューを開始する前に、ワークフロー全体のタスクリストを作成してください（Step 6）。項目 1 は 解決 + 構成を記録 とし、ユーザーが追加で指定した対象も項目として加えてください。
• ルールを見せて → フレームワークと構成を内部で解決し、参照資料を読み込んで、1 画面に収まるルール一覧を提示します。構成についての質問も、実行モードについての質問もありません。何も書き込みません。

Fix に対応する選択肢はありません。「指摘事項を修正して」「レビューを反映して」などの言い回し、または未完了のマイルストーン計画を再開する「修正を続けて」「修正を再開して」によって起動し、Fix モードに直接進みます。

1 セッションにつき質問は最大 1 回です。モードが設定されたら、その後は変更されません。ユーザーがすでにタスクを示している場合は、決して質問しないでください。

---

Step 3 — フレームワークを検出する

対象ファイルを確認し、以下のシグナルに照らし合わせてください。**編集するファイルの拡張子が「対象ファイル形式」に含まれる最初の一致で止めてください。**対象ファイル形式に現在のファイルが含まれない行は、リポジトリレベルのシグナルが存在していてもスキップします。そのため、Laravel + Inertia/Vue のリポジトリで .php ファイルを編集する場合は vue-nuxt ではなく laravel に解決され、同じリポジトリの Component.vue は vue-nuxt に解決されます。これがルールです。以下の「より具体的」という注記は、同じ言語内での優先順位が同じ場合にのみ適用されます。

フレームワークキー	対象ファイル形式	検出シグナル（いずれか）
nextjs	.ts .tsx .js .jsx	リポジトリのルートに next.config.{js,ts,mjs} がある または package.json の依存関係に next がある または ファイルがその設定ファイルと同じ階層の app/ または pages/ 以下にある
react-native	.ts .tsx .js .jsx	package.json に expo、react-native、または @expo/* がある または "expo" キーを含む app.json がある または metro.config.js がある
nativescript	.ts .js .xml	nativescript.config.{js,ts} または package.json に nativescript がある または .ts のページファイルと対になった .xml ファイルがある
cocos-creator	.ts .js	リポジトリのルートに assets/ と settings/ があり、さらに .gitignore に library/ または temp/ がある または cc / cocos-creator のインポートがある または .scene / .prefab ファイルがある
vue-nuxt	.vue .ts .js	package.json に vue または nuxt がある または nuxt.config.{ts,js} がある または .vue ファイルがある
nestjs	.ts	package.json に @nestjs/* がある または NestJS デコレーターのインポートを含む *.module.ts / *.controller.ts / *.service.ts がある
node-express	.ts .js	package.json に express または fastify があり、かつ NestJS ではない
laravel	.php	laravel/framework を含む composer.json がある または ルートに artisan ファイルがある または app/ 以下に .php ファイルがある
csharp	.cs	*.csproj、*.sln、*.cs ファイルがある
spring-boot	.java .kt	spring-boot-starter-* を含む pom.xml がある または Spring Boot プラグインを含む Gradle 設定がある または @SpringBootApplication がある
django	.py	manage.py と設定モジュールがある または pyproject.toml / requirements.txt に django がある
fastapi	.py	依存関係に fastapi がある または from fastapi import FastAPI があり、かつ Django ではない
flask	.py	依存関係に flask がある または from flask import Flask があり、かつ Django / FastAPI ではない
go-http	.go	go.mod とルーター（gin、echo、fiber、chi、mux）がある、または net/http ハンドラーによるルーティングがある
unsupported	（任意）	スキルが認識するものの、構成リファレンスがないフレームワーク／エコシステムです。Web：Angular（@angular/core / angular.json）、Svelte / SvelteKit（.svelte、package.json の svelte、svelte.config.*）、Astro（astro 依存関係 / astro.config.* / .astro）、Remix（@remix-run/*）、Ember、SolidStart、Qwik。ゲームエンジン：Unity（Assets/ + ProjectSettings/）、Godot（project.godot）。v5 ではまだ対象外のその他のエコシステム：Ruby/Rails、Rust、Swift/iOS、Flutter/Dart、Android ネイティブ。…
vanilla-js	.ts .js	上記のいずれにも該当せず、認識済みの対象外フレームワークでもない通常の .ts / .js（ライブラリ、CLI、スクリプト、ブラウザを必要としないプロジェクト）

• 同じ言語に該当する行が2つある場合（例：.tsがNext.jsとvue-nuxtの両方に該当する場合）は、より具体的な方を選びます（Next.jsリポジトリ内の.tsxはreact-nativeではなくnextjsです）。上記のファイル種別ゲートで異なる言語はすでに分けられているため、これは同じ言語内での優先順位を決めるルールです。
• モノレポでは、リポジトリ単位ではなくファイルごとにフレームワークを選びます。ファイルの位置から上の階層へたどり、そのファイルの種別を含むシグナルが見つかった時点で決定します。apps/web/... → nextjs、apps/api/... → nestjs。
• **エンジン／エコシステムによる上書き（最初に確認）：**プロジェクトにゲームエンジンのマーカー（UnityのAssets/とProjectSettings/、またはGodotのproject.godot）がある場合は、.csが通常csharpに該当するとしても、unsupportedに振り分けます。csharpの行にある垂直スライス型のWeb構成はUnityプロジェクトには不適切なため、エンジンのシグナルを優先します。common/の行単位のルールは引き続き適用されます。構成のレビューは行いません。
• フレームワークのシグナルがない通常のライブラリは、デフォルトでvanilla-js（JS/TS）またはcommon/のみ（Python）を適用します。
• 認識されているが未対応（unsupportedの行）の場合は、未対応であることを伝え、vanilla-jsにフォールバックしないでください。AngularやSvelteKitアプリにvanilla-jsのビジネス用フォルダーとバレルの構成を押し付けると、フレームワーク独自の規約に反するため、レビューを見送るよりも好ましくありません。代わりに、common/のすべてを適用します（共通ルールのため、行単位のルールと書き込み時のフックは引き続き言語に対して適用されます）。配置にはプロジェクトの既存の構成を維持し、このフレームワークの構成リファレンスはまだないため、構成や配置のレビューはフレームワーク固有の形式ではなく、common/structure.md（ST-*）に限られることをユーザーに伝えます。提示できるカタログがないため、ステップ4の構成に関する質問は省略します。
• 判断できない場合は、一度だけ質問してください。フレームワークを推測してはいけません。

---

ステップ 4 — プロジェクト構造を解決する（外側の枠組み）

ここでは外側のフォルダー構成、つまり最上位フォルダーの配置と名前を解決します。決定するのは 配置だけです。各フォルダーの内部は、どの枠組みを選んでも引き続き common/structure.md（業務 → 機能 → サブ機能 → 単位）に従います。プロジェクトがすでに採用している構成（フレームワークの スキャフォールド、または既存のレイアウト）に従います。選択内容は .coding-standards-structure ファイルに 記録されるため、ユーザーへの質問は最大 1 回です。

構造を一度把握したら、記録を信頼してください。 .coding-standards-structure が存在しない 場合は、構造を把握し（マップを作成して確認し、references/structure-map.md を参照）、解決した レイアウトを記録します。存在する場合はその内容に従い、構造を再導出したり再編成を提案したり しないでください。通常の書き込み／レビュー実行では、コードを記録済みの構造に照らして 確認するだけで、構造を再検討することはありません。構造を全面的に再度把握する（その後、記録を更新する）のは、 ユーザーが明示的に構造の再編成やレビューを求めた場合に限ります。「これを再編成して」「構造をレビューして」「構造ツリーを 見せて」といった依頼が該当します。通常のタスク（「X を追加して」「この PR をレビューして」「これは整理されている？」）は該当しません。

判断の概要：

1. フレームワークプロジェクトのルートにファイルが存在する → それを読み、従います（follows: <standard> の参照先、 または記述されたカスタムレイアウト）。質問はしません。ファイルが非標準の形式（コメント、hooks: ブロック、またはルールの切り替え設定を含む）の場合は、その場で正規化し（follows: 行／layout: 本文のみを残して）、 書き戻してユーザーに報告します。
2. ファイルがなく、フォルダーが標準に一致する → その標準のリファレンスを使用し、記録します。後続の実行で再度把握せず、 記録に従うよう、follows: <standard> と完全な layout: ツリーを書き込みます。質問はしません。
3. ファイルがなく、カスタムレイアウトである → AskUserQuestion を使ってユーザーに一度だけ尋ねます（推奨構造を最初に、 「現在の構成を維持」を最後に提示）。その後、ユーザーの選択を記録したファイルを書き込みます。

このファイルに記録するのは配置のみです。follows: 行や完全な layout: ツリー（実際に解決された構造。プロジェクトに 両方記録されている場合もあります）を記録します。ルールの切り替え設定は記録しません。すべてのルールは常に適用され、 ディープインポートはバレルの有無から判断され、ST-008 のサイズ／フォルダーチェックは固定のしきい値で実行されます。 これらは block-structure-file-violations.py によって適用されます。

ケース 3、モノレポ、または非標準形式のファイルに対応する前に、references/structure-resolution.md を読んでください。 ここには、モノレポでのファイル配置（リポジトリのルートではなくサブプロジェクトのルート）、質問の形式、「現在の構成を維持」で 免除されることとされないこと、自己修復のための正規化、複雑なプロジェクトでのフォールバックなど、詳細な手順が記載されています。

解決した構造は、ステップ 7b の読み込みリストで references/<framework>/structure.md に代わるものであり、 パイプラインから STRUCTURE として Worker 1 に渡されます。「ルールを見せて」などの純粋な質疑応答では、構造を黙って解決し、 質問もファイルへの書き込みもしません。

ステップ 5 — 実行形式を選択します（オーケストレーターパイプラインとインライン）

Write と Review には 2 つの形式があります。まずステップ 4 を解決してください。構造が常に最初の質問で、実行モードは 2 番目の質問です。

トリガー	形式
単一ファイルの編集（≤30 行）、単一関数のリファクタリング、またはルールに関する Q&A	インライン — 自分で実行します。ステップ 6 → 7b。
2 つ以上のファイル、新機能、差分／PR レビュー、--thorough、または /coding-standards コマンド	オーケストレーターパイプライン — ワーカーをディスパッチします。ステップ 6 → 7a。
このホスト（Cursor、Codex、OpenCode）で Agent ツールを利用できない	スコープに関係なくインライン — ルーティング行にその旨を記載します。
レビュー指摘への対応（「指摘を修正」「修正を続ける」／「修正を再開」）	オーケストレーターパイプライン、常に MODE: fix。 実行モードに関する質問はありません。

選択方法は次の 2 つです。

A) /coding-standards またはステップ 2 の選択メニューから起動され、Agent を利用できる → references/activation.md に記載された正確な内容で実行モードに関する質問をします。「複数のエージェント」ならパイプライン（7a）、 「単一エージェント」ならインライン（7b）です。1 セッションにつき質問は最大 1 回とし、その後は回答を再利用します。

B) 通常のメッセージ（コマンドなし） → 表に基づいて判断します。

ルーティングを通知する — 本作業の前に 1 行

モード、フレームワーク、構造、形式が決まったら、ユーザーにルートが分かるよう 1 行を出力します。

coding-standards: framework=nextjs · structure=route-colocated (matched) · shape=pipeline (2+ files)

形式のトリガー（表の該当行、または「ユーザーの選択」）を示し、構造の解決方法を (matched)、 (file)、または (asked) と記載します。純粋なルールに関する Q&A では、ルーティングするものがないため、この行は省略します。

---

ステップ 6 — タスクリストで作業を追跡する

実作業（作成、編集、リファクタリング、レビュー）では、スコープが分かった時点ですぐ、最初にタスクリストを開きます。ステップ 2 の選択メニュー経由の場合は「レビュー／作成する対象は何か」という回答の直後、通常のメッセージ（「この PR をレビューして」）の場合はファイルを特定した直後です。タスクリストはステップ 3〜4 より前に開き、フレームワークの検出と構造の解決＋記録が、リストがない状態で事前に実行されるのではなく、リスト上の最初の追跡項目になるようにします。基準の適用状況を可視化するのがリストの役割です。ユーザーは、基準が適用されたと信頼するだけでなく、各段階で適用される様子を確認できます。ホストのタスクリストツール（TodoWrite、TaskCreate／TaskUpdate、…）を使います。ホストにタスクリストがない場合に限り省略し、純粋なルールに関する Q&A でも省略します。追跡する複数段階の作業がないためです。

ワークフロー全体を一度に作成し、その後、ユーザーが指定した対象があれば追加します。ユーザーが重視する作業を追跡し（実際のファイル名／機能名を取り込みます）、in_progress の項目は常に 1 つだけにして、次の項目を開始する前に完了させます。一般的なレビューのリストは、構造の解決＋記録 → フレームワークの検出 → ルールの読み込み → レビュー → フックの実行 → レポートの作成です。一般的な作成のリストは、構造の解決＋記録 → フレームワークの検出 → 既存コードの読み取り → ルールの読み込み → 草案の作成 → 草案の書き直し → ルールの全件確認 → ファイルの作成です。最初の項目である構造の解決＋記録を completed にできるのは、解決済みのプロジェクトルートに .coding-standards-structure が存在する場合だけです。解決方法は 3 つあります。標準に一致した場合、確認して記録した場合、またはスキップ理由を記録した場合（認識済みの未対応フレームワーク、またはスコープのしきい値未満）。構造理解エージェントを実行しただけでは完了になりません。ディスク上のファイルが必要です。パイプライン形式と Fix 形式では、ワーカー／台帳の段階が追加されます。orchestrator-pipeline.md を参照してください。マイルストーン主導の修正では、計画の承認時にマイルストーンごとに項目を 1 つ追加します。これは表示用のミラーにすぎず、ディスク上の計画ファイルが引き続き信頼できる情報源です。

---

Step 7a — パイプライン分岐：ワーカーを統括する

あなた（メインエージェント）はオーケストレーターとなり、3 人のワーカーを順番に調整して、最後に自分で Write します。これにより、フックは完成したコードに対してちょうど 1 回だけ実行されます。references/orchestrator-pipeline.md を読み、その手順に従ってください。これが完全なプロトコルです（ワーカー構成、Write／Review／Fix のパイプライン形式、ディスパッチループ、検証、再試行／フォールバック、要約）。

リファレンスを開く前でも、次の不変条件は適用されます。

• 確認する前に把握します。 スコープのしきい値を超えており、かつ構造が .coding-standards-structure にまだ記録されていない場合（またはユーザーが構造の再編成／レビューを明示的に依頼した場合 — Step 4 を参照）、Worker 1 をディスパッチする前に構造マップ（references/structure-map.md）を作成して確定し、STRUCTURE_MAP として渡します。すでに記録があり、そのような依頼もない場合は、マップの作成を省略して、記録済みの構造を STRUCTURE として渡します。レイアウトを読み直してはいけません。機能をまたぐ構造（重複、誤った入れ子、機能の分割、テーマ別クラスターの昇格）は、実際のツリーとマップを比較して見つけます。ファイル単位のワーカーでは把握できません。
• ワーカーは Write／Edit を呼び出しません。 コード／指摘事項を JSON として出力し、ディスクへの書き込みはあなただけが行います。
• 並列ではなく、順番に実行します。 Worker 1（Structure）→ Worker 2（Quality）→ Worker 3（Failure）と進み、各ワーカーの出力を次のワーカーの入力にします。
• 再試行は 2 回までです。 検証に 2 回失敗する、または JSON を解析できない場合は、インライン方式にフォールバックします。

---

Step 7b — インライン分岐：リファレンスを読み込んで適用する

コードの作成やレビューを始める前に、以下をすべて読みます。タスクごとではなく、セッションごとに 1 回だけ読みます。

1. common/ の 8 ファイルすべて（常時）：functions.md、naming.md、objects-and-data.md、 formatting.md、comments.md、error-handling.md、code-principles.md、structure.md。
2. 解決済みの構造（Step 4 から）：structures/<name>.md のバリアント、または references/<framework>/structure.md。

判断の根拠はルール名ではなく、実例にあります。そのため、ファイル全体を読みます。「関数を小さくする」という記憶だけで適用すると FN-001 を誤解してしまいます。実例を読めば、実際の境界がわかります。

各ルールは適用範囲に従って適用します。common はコードの内側を規定し、解決済みの構造は外側を規定します（ファイルの配置、フォルダー名、パブリック API）。両者が矛盾しているように見える場合は、この適用範囲の分担に従ってください。フレームワークのエントリーファイルは薄く（フレームワークのルール）、そこからエクスポートされる関数も短くします（common のルール）。

---

モード：Write、Review、Fix

作成

コードの作成でも、レビューと同じようにルールを一つずつ確認します。ほとんどの common/ ルールには作成時のフックがないため、明示しなかったルールは適用されません。次の手順を Step 6 のタスクリストに追加します。Step 1 はファイルごとではなく、領域ごとに一度だけ実行します。

1. 既存のコードを読む。 新しいコードを配置する場所に最も近いファイルを 2～3 個開きます。配置先フォルダー内のファイルがなければ、同じ言語で最も近い類似機能のファイルを開きます。繰り返し行う各処理にプロジェクトで使われている動詞、エントリーファイルがエクスポートするもの、機能がどのように単位へ分割されているか、どのドメインエラー型が存在するか、インポートがどのような順序になっているかを確認します。ルールはプロジェクトの慣例に優先し、プロジェクトの慣例は、そうでなければ選ぶデフォルトに優先します。 ルールに違反する既存ファイルはそのままにします。作成タスクで既存コードを整理し直すことはありません。まったく新しい領域では、語彙を決めるのはあなたです。作成するすべてのファイルで一貫させてください。
2. 参照資料を読み込む（Step 7b）：common/ の 8 ファイルすべてと、解決済みの構造。
3. 下書きを作成する。 まず動作を正しくします。最初の下書きが雑でもかまいません（FN-012）。
4. 下書きを書き直す。 各ファイルを初めて読む人のつもりで読み直します。25 行で済ませた関数を分割し、これでよいと思った名前を置き換え、誰も必要としていないパラメーターを削除します。
5. ルールを一つずつ確認する。 common/ のルールを、書いたコードに照らして確認し、それぞれを「適用済み」「すでに満たしている」「理由付きで該当なし」のいずれかに分類します。この手順より前に検討していなかったルールについては、参照資料を読み直します。分類結果は返信で報告し、ファイルには書きません。
6. 見つかった問題を今すぐ修正する。 違反は修正してから提出するか、提出しないかのどちらかです。違反と TODO を併記してはいけません。

デフォルトではコメントを書かないでください（comments.md）。意図は名前とコードの構造で伝えます。コードだけでは伝えられない制約、理由、外部参照、注意すべき点を含む場合に限り、文をファイルに残す価値があります。コードを説明してはいけません。編集内容を説明してはいけません。会話の内容をファイルに残してはいけません。as requested、I think、we could also、管理されていない TODO、絵文字、Note: の前置きは使わないでください。ユーザーへの返信に書くべき内容は返信に書き、ファイルはクリーンな状態に保ちます。

別のモデルが、ターンを終える前にそのターンで書かれたコメントを判定します（hooks/judge-comments.py）。そのため、残す価値のないコメントは無視してよい注意書きではなく、適用すべき修正として返されます。最初から適切に書けば判定モデルは何も出力しません。コードに触れたターンごとに短いモデル呼び出しが 1 回必要ですが、ファイルにコメントが追加されなかったターンでは呼び出しは発生しません。

コードの作成と変更には、必ず Write／Edit／MultiEdit ツールを使ってください。シェルのリダイレクト（> file、>>、tee、sed -i、cat <<EOF > file）は使用しないでください。 強制フックが実行されるのは Write／Edit／MultiEdit を使った場合だけです。シェルで書き込んだファイルは、すべてのフックをすり抜けてしまいます。これは強制措置の範囲に実際に存在する抜け穴であり、シェルでの書き込みに対してそれを塞ぐのはこの指示だけです。必ず従ってください。Write の経路以外でソースファイルを生成せざるを得ないツールを使う場合は、生成物に対して python3 <skill-dir>/hooks/review-files.py <file> を実行し、報告された問題を修正してください。

レビュー

ルールを体系的に確認し、その場の判断で進めないでください。対象範囲がわかったら、レビューを始める前に、まず Step 6 のリストを作成します。番号付き手順はリストの項目に対応し、step 0 はリストの最初の項目です。 0. 構造を解決して記録する — 最初のタスク項目であり、.coding-standards-structure が存在して初めて完了です。 スコープのしきい値を超えており、まだ記録されていない場合に限ります。.coding-standards-structure にすでに構造が記録されていて、ユーザーが構造の再編またはレビューを依頼していない場合は、この項目をスキップしてください — 記録済みの構造に従ってコードをレビューし、レイアウトを再検討しないでください。それ以外の場合は、ツリー全体を対象に構造マップ（references/structure-map.md）を作成し、ユーザーに一度確認してから、.coding-standards/structure-map.md に保存し、解決したレイアウトを .coding-standards-structure に記録してください。このマップを構造ワーカーに STRUCTURE_MAP として渡してください。機能を横断する所見（重複、誤った階層にある同列の要素、分割された機能、テーマ別クラスターの昇格）は、このマップとの差分であり、ファイルごとのチェックでは見つけられません。しきい値未満の場合はスキップし、機能横断の構造チェックを実施していないことを伝えてください。

1. スコープを定め、構造を解決する。 差分に含まれる各ファイルを列挙し、そのフレームワークを検出して（Step 3）、構造を解決します（Step 4）。
2. 参照資料を読み込む。 すべての common/ ファイルに加え、差分に含まれる各フレームワークの解決済み構造を読み込みます。
3. 判断によるチェック — ルールの正規表現／AST では検出できない項目（FN-001 の長さに関するニュアンス、FN-009 の CQS、OD-003 のデメテルの法則、EH-002 の境界、CM-* のコメント文に関するルール、structure.md のルール）を確認します。各ルールについて、PASS、所見（file.tsx:42 — <rule> — <what's wrong>）、または SKIPPED — <why it doesn't apply> を報告してください。
4. フックをリンターとして実行する（決定論的チェック、最後に実施 — スキップしないでください）。block-*.py フックは Write/Edit 時にのみ実行されるため、レビューでは明示的に呼び出す必要があります。

   python3 <skill-dir>/hooks/review-files.py <file> [<file> ...]
   # diff:   git diff --name-only | python3 <skill-dir>/hooks/review-files.py --stdin
   # pipeline: add --json and parse per file
   

   これは書き込み時と同じ契約（any、ハンガリアン記法、4 個以上／5 個以上の引数、握りつぶされたエラー、雑多な処理を集めたパス、深いインポート、TS/Python の AST チェック）を適用し、除外対象ファイルはスキップします。review-files.py は、TS/JS 文法を読み込めるインタープリターを自動で選択します（起動時の python3 に文法がない場合は、同梱の venv を使用します）。使用可能なものがない場合は、その不足を明確に通知します。TS ファイルを問題なしと黙って報告することはありません。返された所見はすべて、修正すべき違反です。 所見が存在することは決定論的であり、再議論の対象にはなりません（any は any です）。ST-008 の宣言数ブロックでは、修正方法はレビュアーの判断に委ねられます。まとまりのある分割にするか、またはファイルの処理内容が一貫していて代理指標によるカウントが誤っている場合は、記録済みの免除（理由を添えて .coding-standards-ignore に記録し、accepted としてログに残す）にします。散在を生み出す分割や、同階層のファイルの仕組みをコピーする分割は、それ自体が ST-008 と DP-007 の違反であり、修正ではありません。
5. 統合し、レポートを作成して、要約する。 判断によるチェックとリンターの所見を、ファイル名、次にルールコードの順で並べた単一のリストに統合します。重大度の段階分けはありません — すべての所見が修正すべき違反です。 所見を修正しない唯一の選択肢は Fix 時点での accepted（レビュアーがこのケースでは違反ではないと判断したもの — 理由が必要）または deferred（実際の違反を未解決のまま残すもの）です。レビュー時の判断は二択です。ルールに違反していれば所見として記録し、違反していなければパスとします。「検討してください」のような曖昧な扱いにはしません。統合した結果を references/review-report.md に従ってレポートファイル（.coding-standards/reviews/<timestamp>.md、gitignore 対象）に保存し、そのパスをユーザーに伝えてください。インラインでのレビューも含め、レビューごとに必ずレポートを作成します。レポートの Structure baseline: フィールドは必須であり、記録済みの .coding-standards-structure を明記するか、理由を添えて NOT RECORDED と宣言します。詳細は references/review-report.md を参照してください。スコープのしきい値を超える場合（orchestrator-pipeline.md → Fix mode で一度定義されています）、チャットへの出力を review-report.md に記載された形式に絞ってください。レポートファイルには常にすべての内容を記載します。
6. 構造のベースラインを検証し、その後はルールを黙ってスキップしないでください。 レポートを作成した後、python3 <skill-dir>/hooks/check-review-report.py <report.md> を実行してください（モノレポでは --root <sub-project> を渡します）。終了コード 2 は、レポートが .coding-standards-structure のない構造をベースラインとしていることを意味します。つまり、構造のステップ（Step 4／step 0）がスキップされています。構造を解決して記録し、完了を報告する前にレポートを書き直してください。終了コード 1 は、明示的に宣言されたスキップです。その理由を伝えてください。これはタスクリストの項目に対する最終チェックであり、書き込まれていないベースラインを宣言したままレポートを完了扱いにすることはできません。また、ルールをチェックしていない場合は、その旨を伝えてください。抜けを隠したレビューは、スコープを明示するレビューよりも望ましくありません。

修正

「findings を修正して」「レビューを適用して」「レビュー」の直後に修正を依頼された場合、または未完了のマイルストーン計画を再開するために「修正を続けて」「修正を再開して」と依頼された場合に実行します。修正モードは常にオーケストレーターパイプラインとして実行されます（MODE: fix）。本質的に複数ファイルにまたがる処理であり、ファイルごとに修正エージェントを1つ割り当て、漏れなく修正できるよう完了状況の台帳で追跡します。「単一エージェント」の選択肢は提示しないでください。Agent が利用できない場合は、ドキュメントに記載された逐次バッチ方式の代替手順を実行し、その旨を伝えてください。

各指摘は、fixed（違反を解消）、accepted（違反ではないと判断。理由が必要）、または deferred（実際の違反だが未修正。未解決の違反）で終了します。未解決の違反が残る実行結果は done ではなく done-with-open-breaches と報告してください。ユーザーが解決するまで、この状態は変わりません。references/fix-plan.md を参照してください。

入力は、最新の .coding-standards/reviews/<ts>.md です。存在しない場合は、先に Review を実行してください。それ以外の内容、つまり台帳、ファイルごとの振り分け、スコープのしきい値、大規模な修正のマイルストーン主導型計画ファイル（references/fix-plan.md）は、references/orchestrator-pipeline.md の「Fix mode」に記載されています。

---

必要に応じてルールを見つける

ルールは言語別ではなく、質問の種類（関数、命名、オブジェクト／データ、書式、コメント、エラー処理、原則、構造）ごとに整理されています。質問からファイルを引く完全な索引は references/rule-index.md にあります。「FN-005 はどういう意味か」といった検索や、どのリファレンスが該当するか分からない場合に使用してください。実際の作業ではステップ 7 ですでにすべて読み込まれるため、この索引は対象を絞った検索にのみ使用します。

---

競合した場合 — よりシンプルで正しい設計を選ぶ

2つの設計がどちらも正しく、ほかの原則との兼ね合いで方向性が分かれる場合は、**DP-006（KISS）**をタイブレーカーとして使用します。DRY やほかのルールに多少反する場合でも、よりシンプルな設計を選びます。KISS はタイブレーカーであって、切り札ではありません。正しさ、実際の要件、SOLID を覆すことはありません。渡されたバリアントごとにクラスを用意するのを省略する（OD-002）、エラーを握りつぶす、または何も通知しないフォールバックを出荷するために、KISS を持ち出すことはできません。ルールを満たすためだけにパターン（Strategy、Visitor、5段目の間接化レイヤー）を追加しようとしていますか？いったん立ち止まってください。通常はシンプルなバージョンが正解です。構造を避けるために、巨大なファイルや重複した switch を「シンプル」だと擁護しようとしていますか？それもやめてください。よりシンプルなのではなく、単に小さいだけです。

---

このスキルが対象としない内容

• パフォーマンスのチューニング — プロファイラーを使用してください。クリーンなコードは通常、十分に高速です。
• セキュリティレビュー — 専用のセキュリティスキル（例：security-review）を使用してください。クリーンコードレビューで検出できるバグの種類もありますが、セキュリティ監査ではありません。
• テスト設計 — テストにも同じクリーンコードのルールが適用されますが、TDD／BDD／ミューテーション戦略は対象外です。
• UI/UX のビジュアルレビュー — これは別の領域です（web-design-guidelines、design-taste-frontend）。これらのフレームワークが扱うのは、視覚デザインではなくコードの構成です。

ユーザーからこれらのいずれかを依頼された場合は、このスキルの対象外であることを伝え、適切なツールを案内してください。