フロントエンドの規則リポジトリで規則を書き、公開前に検査を通す

## 規則を変える前に、編集すべきソースと生成物を見分ける フロントエンド規則リポジトリを、ソースコンテンツ、スキーマ、API、レビューツール、表示ページ、生成インデックスからなる製品として扱う。変更前に、どの層が動作を所有するかを特定し、その層と直接の利用側を調べる。 - コンテンツパッケージ、共有型とスキーマ、アプリケーションの接点、ツールサーバー、生成物の関係を整理する。 - 利用できる場合は、記憶から指針を作り出さず、リポジトリのレビュー・規則検索ツールを使う。 - 修正を推奨する前に調査対象のコードを確認し、アクセシビリティ、性能、SEO、セキュリティ、プライバシー、国際化、テストに関する主張をする前に規則群を検索する。 - 広範な監査は、タスクが広範な監査を求める場合だけ行う。 - 編集可能なソースと、生成成果物および表示用の投影結果を区別する。 互換性の指針は、宣言されたブラウザ方針とパッケージが裏付けるデータから導く。記憶している対応表に頼ったり、生成された表示を暗黙に正本として扱ったりしない。 ## どの規則にも必要なメタデータを決める 各規則には、解析、検索、採点、レビュー、表示に対応する安定したメタデータ契約が必要である。必須項目は、一貫して強制できる小さな集合に保つ。 必須メタデータには次を含める。 - 引用符で囲んだ人間向けタイトルと、一文の説明。 - 許可されたカテゴリ、優先度、難易度。 - 単位を明示した整数の工数見積もり。 - 規則を確認、修正、説明するための実行可能な指示。 有用な任意メタデータには、サブカテゴリ、簡潔な要点、ユーザーまたは事業への影響、根拠資料、補足資料、関連規則、ツール、タグ、コードレビュー用指示、自動レビューのコンテキストがある。 カテゴリと列挙値は正本の許可一覧に照らして検証する。構文上意味を持つ句読点を含む値は引用符で囲む。役立ちそうに聞こえるだけの項目は追加せず、解析器、UI、検索層、ジェネレーターが利用する場合だけ追加する。 指示には、調べる対象と期待する是正内容を明記しなければならない。実行可能なレビュー戦略を示さない「この規則を確認する」のような仮置き文は拒否する。 ## 根拠、追加の資料、関連規則へのリンクを分けて置く 権威ある根拠は構造化されたソースメタデータに置く。任意の読み物とツールは資料メタデータに、規則間の移動情報は関連規則メタデータに置く。ある役割を別の役割で代用しない。 - 各規則に、少なくとも2種類の異なる役割を持つ関連資料を2件以上付け、そのうち少なくとも1件を一次的な権威ある資料にする。 - パイプラインが対応する場合、根拠には安定した識別子を使う。 - 一般的な「関連項目」や「参考資料」の行を本文に入れない。 - 名前のあるツールが実質的に役立ち、資料またはツールのメタデータにも存在する場合は、最初の意味ある言及箇所からリンクする。 本文中のリンクは、具体的な主張または実装判断を支えるものにする。目安は規則ごとに2〜5件、導入部は0〜1件、主要指針全体は1〜3件とする。内部規則へのリンクは通常0〜1件に保ち、特に関連の深い題材だけ2件にする。 「詳しく読む」のようなラベルではなく、内容を表すリンク文言を使う。安全に導出できる項目はビルドツールに推論させてよいが、弱い根拠や無関係な根拠を推論で正当化してはならない。 ## 規則の本文は、コード例を理由より前に、検証を最後に置く 人、エージェント、検証器が同じ情報を見つけられるよう、各規則を安定した順序で書く。 1. 平易で短い導入。 2. 現実的なコード例または例の集合。 3. 規則が重要な理由の説明。 4. 必要な実装指針。 5. 最後の検証セクション。 例を理由説明より前に置き、検証を最後の最上位セクションにする。ベストプラクティス、よくある誤り、フレームワーク例、ツール、しきい値、例外、ブラウザ対応、標準、実装注記などの任意セクションはその間に置く。 有効な但し書きや誤検出が存在する場合だけ例外を追加する。自動検査と手動検査の両方に意味がある場合だけ検証を分ける。互換性または適合性によって実装判断が変わる場合は、目に見える標準または対応注記を加える。 一般論より合否を判定できる指示を優先する。技術者が規則を検証する方法、根拠として認めるもの、検査を不合格にする条件を述べる。 ## フロントエンド規則に、合否を測れるしきい値を付ける 規則をテストできる場合は、測定可能なしきい値を使う。 - `LCP <= 2.5s`、`CLS <= 0.1`、アセット容量上限などの性能予算。 - コントラスト比、操作対象の大きさ、キーボード操作、拡大、再配置などのアクセシビリティ基準。 - インデックス登録可否、状態コード、正規URLの動作などのSEO状態。 - 通信方式と応答ヘッダーの条件などのセキュリティ要件。 影響に応じて優先度を割り当てる。最高位はサイト停止、セキュリティ、法的問題に限定し、体験低下、ベストプラクティス、任意の仕上げには低い段階を使う。 例は失敗の形が分かる程度に現実的でなければならない。重要な例外と対応上の制約を含めるが、すべての規則へ任意セクションをすべて追加しない。 検証を後続の編集作業ではなく規則の一部として扱う。再現可能な検査のない推奨は不完全である。 ## 共有のUI部品は、各ページではなくデザインシステムに置く タイポグラフィ、アイコン、意味に基づく色、再利用可能なコンポーネントなど、アプリケーション横断の関心事は共有デザインシステムに置く。アプリケーションは共有契約を利用しながら、フレームワーク固有の連携を配線する。 - ページ固有の派生版を作る前に、既存コンポーネントを再利用する。 - 共有機能は、最初に要望が出たページだけでなく、関係するすべての接点に適用する。 - カード全体をリンクにするパターンでも、副次的な操作部品を操作可能に保つ。 - ブランドアイコンとフレームワーク用アイコンのエクスポートを集約し、利用側がデザインシステムの境界を迂回しないようにする。 - 任意の不透明度修飾子より、意図した完全なコントラストを持つ意味的なテーマ変数を優先する。 - CSSリセットがリッチテキストのリスト記号を消す場合は、明示的に復元する。 不一致を隠すためにサーバーとクライアントのハイドレーション警告を抑止してはならない。クライアント専用状態をマウント後まで遅らせるなど、状態の境界を修正する。 ブラウザ由来の保護は、ブラウザでの変更操作とフォームに適用する。ブラウザの課題に応答できないプログラム用APIエンドポイントへ、クライアント側のボット検査を適用しない。 ## 新しいツールを、定義からテストまで全部つなぐ 新しいツールまたはパッケージ横断機能は、その定義、エクスポート、登録、振り分け、実装、テスト、文書が一致したときだけ完成する。 呼び出し可能なツールでは次を行う。 1. 具体的な名前、説明、入力スキーマを定義する。 2. パッケージ境界でエクスポートする。 3. サーバーのツールカタログへ登録する。 4. 振り分け経路へ接続する。 5. 検出、検証、ルーティング、動作をテストする。 集約エクスポートはパッケージ境界だけで使う。内部の集約エクスポートは移動手順を増やし、所有関係を隠す。複数パッケージが使う共有依存関係のバージョンは一元管理し、スクリプトを目的別に整理して、保守された索引を付ける。 バージョン固有のライブラリ契約を守る。たとえば、導入済み検証器の現在のエラー形式を使い、状態を持つクエリクライアントはリポジトリ承認済みファクトリーで作り、非同期設定ラッパーは返されたすべてのプロパティを保つ順序に維持する。 起動時に読み込まれる設定を変更した後は、サービスを再起動する。実行中のプロセスが変更を読み込むまでは、編集成功を根拠として扱わない。 ## 公開前に全部の検査を通し、1つも飛ばさない 規則またはその基盤を変更した後は、リポジトリ正本の品質検査手順を実行する。 - 必須メタデータ、カテゴリ値、資料の品質、規則構造を検証する。 - 実行可能な指示、根拠、例、本文の深さ、検証、しきい値、適用対象となる条件付きセクションを採点する。 - 整形、静的検査、型検査、パッケージ検査、集中テスト、変更した接点が必要とする全体ビルドを実行する。 - インデックスまたはスキルを再生成し、生成物が同期されていることを確認する。 コミット前検査を迂回してはならない。検証を省略する経路を使わず、文書、危険な型変換、複雑度、インポート境界、未使用コード、カバレッジの失敗を修正する。 自動採点を意味上の正しさの証明ではなく、品質ゲートとして扱う。ソースファイルだけでなく、表示結果とツール向け結果も確認する。 公開前に、必須の指示が実行可能で、根拠が権威あるもので、例が推奨内容と一致し、検証が最後にあり、生成差分が残っていないことを確認する。全手順が合格した後だけ公開する。