code-discipline

コードの規律

タスクにロジックの追加や変更、ヘルパーの増殖、不要なラッパー、重複したユーティリティや定数、抽象化の肥大化、巨大なファイル、スキーマの境界、クラスとコンポジションの選択、アロー関数と関数宣言の選択、オブジェクト引数と位置引数の選択、またはセキュリティや保守性の強化が関わる場合は、いつでもこのスキルを使用してください。

これは安易な対応を防ぐスキルです。既存のプリミティブで問題を解決できるのに、新しいファイルやヘルパー、間接層を作ってタスクを「解決」することをエージェントに防ぎます。機能によってより適切な境界が明らかになった場合は、その変更が現在のタスク範囲内に収まり、以下の導入ゲートで妥当と判断されるなら、今すぐリファクタリングしてください。

基本方針：

• ユーザーは、抽象化の表面積を最小限に抑えた保守しやすいコードを望んでいます。機能によって明らかに優れた境界が示された場合は、差分を小さくするためだけに劣った構造を維持せず、長期的な複雑さを軽減するために短期的な表面積の増加が必要で、導入ゲートにより妥当と判断される場合も含め、今すぐその境界を採用してください。
• ユーザーは、既存の動作を別名で重複させることを望んでいません。同じ規律を ORM のスキーマ境界、クラス継承、関数シグネチャ、セキュリティ上重要な判断にも適用してください。
• 新しいヘルパー、ラッパー、定数モジュール、スタイルだけを目的とする間接層は、明確なアーキテクチャ上の価値によって正当化されない限り禁止です。
• これらのルールは、抽象化、ヘルパー、ユーティリティ、間接層に適用されます。新しい第一級ドメインファイル（例：ルートハンドラー、エンティティ、ページコンポーネント、テストファイル）は、導入ゲートではなく repo-standards-enforcement に従います。主な目的が共有インフラストラクチャではなくドメインロジックであるファイルには、導入ゲートを適用しないでください。

使用する場面

次の場合にこのスキルを使用してください。

• 新しいロジックを導入する機能実装
• ユーティリティ層やサービス層を追加するリファクタリング
• コンポーネント内のヘルパーが増えがちな UI の変更
• 定数、トークン、スタイル付きファイルを不必要に分割する可能性があるフロントエンド作業
• 手軽なラッパーでの修正に走りがちなバグ修正
• 保守性と再利用の規律に焦点を当てたコードレビュー

本番実装作業では、agent-execution-mode および repo-standards-enforcement と併用してください。

このスキルに記載された参照ファイルが利用できない場合は、このドキュメントに明記されたルールを正式な代替として適用してください。不足している参照ファイルを待って作業を止めず、出力契約のレポートに利用できなかった参照ファイルを記載してください。 参照ファイルがすべて利用できない場合でも、このドキュメント内のルールで完全に対応できます。参照ファイルは例と補足を示すものであり、参照ファイルだけに依存して実行可能となるルールはありません。確信度を下げることなく、本文中のルールに従って作業を進めてください。

中核となる適用方針

このスキルは適用モードで動作します。ハードルールに違反するコードは、交渉の余地なく却下してください。ソフトルールについては、出力契約に書面で理由を記載して作業を進めてください。対話形式のレビューを行っている場合を除き、理由をユーザーに求めないでください。

候補となる抽象化ごとに、判断フローを統一します。（1）再利用を優先して評価するため、必須評価手順のステップ 1〜6 を実行します。（2）ステップ 6 を利用できない場合に限り、ステップ 7 に進み、新規抽象化の導入ゲートで許可または却下を判断します。（3）実装後、完了条件の基準を満たしていることを確認します。

厳格なルール — 例外は認められません

• ロジックが単純で一度しか使われない場合、ヘルパーを作成しないでください。
• 呼び出しを転送するだけのラッパーを作成しないでください。
• 既存のユーティリティと名前を変えただけの重複を作成しないでください。
• Admission Gate の条件を少なくとも1つ満たし、その理由を明示できない限り、間接性を増やすサービス、フック、アダプターのレイヤーを追加しないでください。
• プラットフォームや標準ライブラリの動作を再実装しないでください。
• パッケージ間でユーティリティのロジックを重複させないでください。
• 行数を減らすだけの目的で、一度しか使わない定数をモジュールに切り出さないでください。
• 所有関係と再利用の実態がない限り、constants、helpers、utils、または shared ファイルを作成しないでください。
• スタイルがローカルなものであり、ファイルを分割しても所有関係が改善されない場合は、スタイルを別ファイルに分割しないでください。

厳格なルールに異議を唱えることはできません。

ルールが競合する場合の優先順位：（1）厳格なルール、（2）モノレポおよびワークスペースのルール、（3）Admission Gate の判断、（4）機能優先の境界ルール、（5）その他のソフトルールとドメイン固有ルール（具体性の高い順）。

必須の評価順序

ヘルパー、フック、サービス、ラッパー、アダプター、フォーマッター、パーサー、トランスフォーマー、定数モジュール、トークン、またはユーティリティを追加する前に、必ず次の順序で評価してください。

1. 言語またはランタイムのプリミティブ
2. 標準ライブラリの API
3. フレームワーク標準の機能
4. 既存のリポジトリ内ユーティリティ
5. 既存のインストール済み依存関係
6. 既存のユーティリティでニーズの一部を満たせる場合は、新しい共有抽象化を作るより、呼び出し側で適用する方法（たとえば、合成または呼び出し側だけの薄いアダプター）を優先してください。複数の既存ユーティリティがそれぞれニーズの一部を満たす場合は、呼び出し側に最も近いドメインの所有関係を持つものを優先し、所有関係が同等であれば、どちらかを適応させるより呼び出し側で合成する方法を優先してください。ユーティリティを適応させることで公開シグネチャが変わる場合、既存の呼び出し側の動作が変わる場合、または現在のタスク範囲外の呼び出し側に更新が必要となる場合は、ステップ7に進み、その部分的な適合を再利用できない理由を明示したうえで、合成または適応の根拠を Output Contract に記録してください。
7. 根拠を示した新しい抽象化

この順序を省略することは、要件違反です。

抽象化の候補ごとに、次のチェックリストを順番に実行してください：（1）必須の評価順序のステップ1〜7を完了する、（2）ステップ7に進んだ場合は、新しい抽象化の Admission Gate を適用する、（3）実装後に Definition of Done の基準を確認する。

新しい抽象化の Admission Gate

新しい抽象化、ヘルパー、定数モジュール、または共有スタイル境界を認めるのは、次のいずれかを満たす場合に限ります。

• ドメインの不変条件またはポリシーを適用する
• 次の条件をすべて満たすロジックをカプセル化する。（a）複雑さが単一の式を超える。（b）3か所以上の異なる呼び出し箇所に、同一またはほぼ同一の形で現れる。（c）そのロジックを将来変更する際、呼び出し箇所を個別に修正する必要がある
• インフラストラクチャの境界を分離する
• 正確性、検証、またはセキュリティを保証する
• 真に複雑な動作のテスト容易性を向上させる
• 複数の利用側で同期を保つ必要がある値について、共有の唯一の情報源を作る

次の目的だけであれば、新しい抽象化は認められません。

• 既存の動作に別の名前を付ける
• 呼び出しを1対1で転送する
• 単一のプリミティブまたは単一のライブラリ呼び出しをラップする
• スタイル上の好みだけを理由に作成する
• インラインのほうが明確な、一度しか使わないリテラルを隠す

機能優先の境界ルール

ファイル構成、API の形状、スキーマ構成、またはクラスとコンポジションの選択に変更が及ぶ場合は、references/feature-refactor-first.md を読んでください。機能を通じてより適切な境界が明らかになり、かつ作業が現在の実装範囲内に収まる場合に適用してください。references/feature-refactor-first.md が利用できない場合は、変更がタスクの範囲内に収まり、機能の境界を越えて広がらず、Admission Gate によって正当化される場合に限り、より適切な境界になるよう今の段階で再構成してください。

ソフトルール - 上書きするには文書化された正当な理由が必要です

以下を自動的な精査のトリガーとして扱います。

• normalize、format、parse、transform、sanitize、safe、to で始まる名前
• 単一の操作をラップするだけの場合、build、make、create、get、set、use、manage で始まる名前
• 公開インターフェース全体がリポジトリまたは SDK のメソッドシグネチャに一対一で対応し、引数の転送以外にエラー処理、ポリシー、検証、変換を追加しないサービス
• 別のフックを呼び出して同じ形で返すだけのフック
• 単一ファイル内で一度だけ使われるヘルパー
• 1 行のラッパーだけを含むユーティリティモジュール
• 単一の利用箇所しかない定数モジュール
• 宣言の所有者や再利用方法を変えず、宣言の移動だけを行うスタイルファイル

コードスメルが常に誤りとは限りませんが、明示的な根拠が必要です。ソフトルールに該当する場合、エージェントは続行する前に、出力仕様に明示的な理由を記載する必要があります。ユーザーとのやり取りなしに自律的に動作する場合は、その理由をインラインで記載して続行してください。外部からの承認を待って実行を止めてはいけません。ハードルールに異議を唱えることはできません。

コンポーネントロジックのルール

• 単純な表示処理や一度限りの変換はインラインに保ちます。
• 複雑さや再利用性によって正当化される場合にのみ切り出します。
• コンポーネントファイルをローカルなユーティリティライブラリに肥大化させないでください。
• 再利用可能なロジックは、最も近いファイルではなく、適切な共有レイヤーに移します。
• 一度限りの定数は、共有コントラクトの一部であるか、複数のファイルで繰り返し使われていない限り、インラインに保ちます。
• コンポーネント内でのみ使うスタイル宣言は、スタイルの繰り返しによって共有プリミティブの必要性が明らかにならない限り、コンポーネント内に保ちます。

定数の配置ルール

• 可読性が向上する場合は、一度限りのリテラルを使用箇所の近くに置きます。
• 共有の意味を持つ、再利用される、または公開コントラクトやファイル間コントラクトの一部である場合にのみ、定数として昇格させます。
• 単一の定数を置くためだけにモジュールを作成しないでください。
• 新しい名前によって意味が増えない場合は、リテラルを const X = ... に移さないでください。
• 共有デザイントークンは、ページ固有のファイルではなく、テーマまたはデザインシステムのレイヤーに置きます。
• 共有 UI 定数は、利便性だけを目的とする領域ではなく、それらを所有するドメインまたは共有レイヤーに置きます。

ファイルとスタイルの整理ルール

• ヘルパー、定数、スタイルは、それらを適切に所有する最小の範囲に保ちます。
• コンポーネント内だけで使うものには、コンポーネントと同じ場所に置くスタイルを優先します。
• 複数のコンポーネントで実際に共有される場合にのみ、共有スタイルプリミティブを優先します。
• 構造を隠すためだけに存在する、汎用的な受け皿フォルダーは避けます。
• 境界や再利用の価値を加えない再エクスポート用バレルは避けます。
• スタイルファイル名は汎用的な名前ではなく、所有対象がわかる名前にします（Button.styles.ts は styles.ts より明確です）。
• 分割によって所有権、再利用、保守性が明確になる場合にのみ、スタイルファイルを分割します。
• 一度しか使われない短いスタイル断片のために、別ファイルを作成しないでください。

モノレポとワークスペースのルール

• パッケージ間でヘルパーを重複させないでください
• 再利用される共有ロジックは、適切な共有パッケージに昇格させます
• パッケージ B がワークスペースの依存関係グラフでパッケージ A の依存先として記載されていない場合、パッケージ A のユーティリティをパッケージ B にインポートしないでください。境界が不明確な場合は、インポートする前に確認してください
• 便宜的なインポートを通じて境界を迂回しないでください
• コードジェネレーターの出力であるファイル（ORM のマイグレーション、スキーマクライアント、ビルド成果物など）には、重複排除や削除のルールを適用しないでください。ヘッダーコメント、ツールの慣例、generated/ および __generated__/ ディレクトリを使って、生成ファイルを特定してください

レビューとリファクタリングの適用

レビュー／リファクタリングモードで動作する場合、エージェントは以下を行う必要があります。

• 不要なヘルパーやラッパーを指摘する
• 安全な場合は、些細な抽象化を削除する
• 重複するユーティリティを統合する
• 適切な場合は、手書きのロジックをプラットフォームやライブラリのプリミティブに置き換える
• 削除や統合のそれぞれについて、保守性の観点から理由を説明する

完了の定義

以下のすべてを満たした場合に限り、このスキルは完了です。

• 新たに追加された些細なヘルパー／ラッパー層が残っていない
• 変更対象の範囲に重複したユーティリティロジックが残っていない
• 共通の意味に基づく理由がないまま、単独で使う定数を切り出していない
• 新しい抽象化（存在する場合）が、採用基準によって正当化されている
• 独自に再実装するより、プラットフォーム／フレームワーク／内部ユーティリティを優先している
• 変更対象の範囲が長期的な保守の負担を軽減している。短期的な変更箇所の増加が許容されるのは、対象範囲内のより適切な境界へのリファクタリングに必要であり、かつ採用基準によって正当化される場合に限る

出力要件

このスキルを使用した後に回答する際は、内容がある項目のみを報告してください。実装モードでは、このタスクで行った変更を報告してください。レビュー モードでは、レビュー対象として提出されたコードについて報告してください。抽象化候補を検討していない場合は、その項目を省略してください。定数をインラインのまま維持していない場合は、その項目を省略してください。必ず少なくとも1項目を報告してください。

抽象化候補を評価せず、統合も行っていない場合は、次のように報告してください。「抽象化候補は特定されませんでした。新しいヘルパーは追加せず、既存のプリミティブを直接使用しました。」

• 検討した抽象化／ヘルパー候補
• 再利用した既存のプリミティブ／ユーティリティ
• 却下した抽象化とその理由
• 実施した統合／削除
• 追加した新しい抽象化と、それを認めた採用基準の条件
• 抽出せずに定数やスタイルをインラインのまま維持した箇所
• 参照ファイルが利用できなかった場合は、そのファイル

参考資料

例や詳しい説明については、以下のリファレンスガイドを参照してください。

• references/helper-functions.md
• references/abstraction-patterns.md
• references/library-preference.md
• references/feature-refactor-first.md
• references/component-logic.md
• references/constants-and-organization.md