付録 H — コード品質とユーザビリティのヒューリスティクス

状態：承認済み・本番稼働中。 未決の判断は残っていない。形態（D-043 と D-044）、スイッチ（D-045 と D-046）、ダッシュボード（D-047）、アクセシビリティの重みを含む初期重大度（D-048、第 10 節）は決定済みである。本書は本メソッドの八言語すべてで公開され、その二つのプロンプトはプロンプト API の一部になっている。そこから build/prompts.mjs が八言語すべてで英語本文のバイト一致を要求し、一致しなければビルドは失敗する。日付：2026-10-22。

本付録の決定の記録：docs/DECISIONES.md、D-043 から D-048。コンプライアンス・ダッシュボード（第 12 節）は D-047 で二つの数値をもって確定した。実装作業は PND-002 に住む。

1. 今日なにが欠けているのか、そしてなぜか

ステップ 9 はすでにコードを測っており、それを通過させないゲートで行っている。単一のフォーマッタ、サイズの上限（ファイル当たり三百行、関数当たり四十行）、関数ごとの複雑度、重複コード、デッドコード、宣言され使用されている依存関係、ラチェット付きのカバレッジ、そして実際のユーザーがいるところでのミューテーションテストである。その数値は docs/CODE_QUALITY.md に書かれる。これは解決済みである。

解決していないのは製品のもう半分である。ステップ群のコーパスを検証した。ユーザビリティへの、人物やプロファイルへの、機能的グルーピングへの言及は一つもない。今日のインターフェースは二つのものに支えられている。所有者が十秒だけ見るスクリーンショットと、手動のテストケースである。どちらも良いものであり、どちらも人間的で、高価で、忘れっぽい。システムは品質ゲートを立派に通過しながら、使えないままでいられる。すべてが緑で、それでもその人はどこで請求するのかを見つけられない。

さらに、技術的ではあるがインターフェースに現れる第二層の問題がある。同じ製品を複数のプロファイル（管理、運用、照会、顧客）が使うとき、機能は三つの異なる場所——データベース、メニュー、ルートのガード——で有効化され、それらは別々の時点で書かれ、ひとりでに同期を失う。症状はいつも同じである。誰かが自分に属さないボタンを見る。あるいはもっと悪いことに、権限を持っている人がその画面を見つけられない。

続く二つのヒューリスティクスは、同じ形態でその二つの問題に取り組む。検証可能な言明の短いカタログ、それらを自動で測る少数の計器、そしてプロジェクトが外に出る必要があるときのための、宣言された例外の道である。

2. モデル：三つの層、規則の単一の形態

誘惑は、規則の一覧を作り、それを最初のプロジェクトのスタックに縛り付けることである。それは悪く老化する。React の規則は Angular には適用されず、Angular の規則はテンプレート付きサーバには適用されず、二年後には一覧の半分が死んでいる。提案は三つの層を分ける。

第 1 層 — 非依存の中核（交渉不能）。 道具についての言明ではなく、結果についての言明である。「フォーマッタは一つしかなく、誰もそれと議論しない」は、TypeScript でも PHP でも Go でも同じように適用される。中核は安定した識別子で列挙され、プロジェクトごとに変わらない。

第 2 層 — スタックごとのアダプタ（設定可能）。 中核の各規則について、フロントエンドの各ファミリが*何で*測り*どのしきい値で*測るかを宣言する。Vite を使う React のプロジェクト、Next のプロジェクト、Angular のプロジェクト、テンプレート付きサーバのプロジェクト、モバイルのプロジェクト、コマンドラインのプロジェクトは、同じ中核の六つの異なるアダプタである。ここに、ユーザーが「フロントエンドごとに設定可能」として求めたもののすべてが住む。

第 3 層 — プロジェクトの決定（宣言されたもの）。 具体的なしきい値と免除である。発明されるのではなく、所有者に求められて書かれる。アーキテクチャのステップのサイジングと同じである。しきい値が宣言されていなければアダプタのものが走り、そのように記録される。

各規則は常に、六つの欄からなる同じカードで書かれる。

例外は宣言される。決して省略されない。 規則は四つの欄からなる登録で消す。識別子、一行の理由、誰が認可するか（所有者であり、エージェントではない）、再検討日である。登録なしで消された規則は、決定ではなくゲートの故障である。これは、「通すために」引き上げられた上限を受け入れないために本方法がすでに使っているのと同じ基準である。

3. 四つの計器

どのヒューリスティクスも、その検証が意見であれば役に立たない。計器は四つであり、各規則はどれに属するかを宣言する。

1. 自動ゲート。 毎回のプッシュとブロックの閉鎖で走る。緑か赤を返す。安価で、反復可能で、議論しない。数えられるもののすべてを測る。
2. マトリクスへの問い合わせ。 プロファイルごとの機能マトリクス（B2 を参照）は宣言的な成果物であり、メニュー、ルーティング、権限はそこから導出される。マトリクスを点検することはインターフェースを点検することである。ユーザビリティの一部を機械で検証できるものに変える部品がこれである。
3. プロファイルごとのエンドツーエンド・テスト。 宣言された各プロファイルについて、そのプロファイルとして入り、到達可能な機能の集合をマトリクスの行と比較するスクリプト。*少なすぎても多すぎてもならない*。典型的な二つの同期ずれ（余分なボタンと欠けた画面）を捕まえるテストである。
4. 手動のケース。 どの機械も判断しないもの。グルーピングが理解できるか、作業が助けなしに完了するか、テキストがユーザーの言語にあるか。人とともに実行し、ステップ 10 がすでに命じているとおりに記録する。

4. パート A — コード品質

中核はステップ 9 を拡張する。それを置き換えも矛盾もしない。すでに測られているもののそれぞれに名前、重大度、アダプタを与え、今日欠けているもの、すなわちコードとして見たインターフェースを加える。

CQ-12 から CQ-18 の規則こそが、「コード品質」をフロントエンドにおいて意味のあるものにする。それらがなければ、プロジェクトはミューテーション九十パーセントを持ちながら、コンポーネントの中で自前の算術で合計を計算する画面を持つことができる。両方の世界の最悪である。複製された計算はバックエンドのテストをすべて通過してしまうからである。

初期重大度（D-048）。 初日からブロックするのは、検証器を持ち、議論を要するしきい値に依存しない十四の規則である。CQ-01 から CQ-06、CQ-08、そして CQ-11 から CQ-17。CQ-09 は実際のユーザーがいるところでブロックし、そこが測られる場所である。警告するのは三つ、しかも三つだけである。CQ-07（型）、CQ-10（依存関係）、CQ-18（アクセシビリティ）。これらはプロジェクトがまず較正する必要があるものだからである。フォーマッタ、リンタ、サイズ、複雑度は緩めない。ステップ 9 がすでに今日それらをブロックしており、これはそれを拡張するのであって置き換えるのではない。継承された負債は、宣言された例外かラチェットのベースラインで解決するのであり、重大度を下げて解決するのではない。そして CQ-12 と CQ-14 は、この表で唯一、機械ではなく人間の赤でブロックする二つの規則である。ペンディングの閉鎖時に、手動のケースを前にして検証され、UX-22 と UX-27 と同じ基準に従う。毎回のコミットではない。プロジェクトがその閉鎖を支えられないなら、その規則は忘れられたのではなく記録された決定によって AVISA に下がる。

フロントエンドのファミリごとのアダプタ。 第 2 層がどのようにインスタンス化されるかの一例である（名前は例示であり、プロジェクトが選んで書く）。

列の間で変わるのは道具としきい値である。変わらないのは言明である。それこそが、ヒューリスティクスを装飾にせずに非依存にするものである。

5. パート B — ユーザビリティ

五つのファミリ。第一と第二は所有者が明示的に求めたものであり、他の三つは、それらがなければグルーピングとプロファイルが同じように、ただより遅く劣化するから存在する。

B1 — 機能的収束によるグルーピング

母なる規則：機能は、その人がしに来たことによってグループ化され、それが生まれたモジュールによってではない。 コードはエンティティ（「請求書」「顧客」「支払」）で組織される。人はそうではない。誰も「エンティティを管理する」ためにシステムに入らない。入るのは請求するため、出荷するため、月末を締めるためである。メニューがエンティティを見せるなら、その人が翻訳者の役をする。メニュー*が*仕事である。

B2 — プロファイルと、プロファイルごとに有効化される機能

ここに最も実り多い部品がある。その理由は設計ではなく工学である。有効化は一度、マトリクスの中で宣言され、それ以外のすべてはそこから導出される。 今日の典型的な誤りは、権限を三度（メニューで、ルートのガードで、データのフィルタで）書き、その三つが離れることである。マトリクスを唯一の生産者とすれば、メニュー、ルーティング、サーバの権限、テストのスクリプトは消費者であり、本方法がすでに要求する生産者／消費者の対称性がひとりでに検証可能になる。

マトリクスは四つの列と機能ごとに一行を持つ。*機能*、*家*（B1 のグループ）、*それを持つプロファイル*、*入口のルート*。それだけである。

B3 — 状態、そして何かがないときに人が見るもの

「動かない」という苦情のほとんどは、「何もない」「読み込み中」「失敗した」と言えなかった画面である。四つの状態を、常に、すべての一覧とすべての詳細画面で。

B4 — 操作とエラー

B5 — 言語とアクセシビリティ

6. どこに掛かるか、そしてどんな成果物を生むか

本付録は新しいステップを発明しない。存在するものに掛かる。それによってゲートの複製を避け、ユーザビリティの一覧の通常の行き先、すなわち一度読まれて終わることを避ける。

どこに置くか（D-043）。 四つの区間に横断的であり、主な重みは建設ループ（ステップ 5 から 12）にあり、そこが決定され建設される場所である。独自のステップではない。番号付きのステップはラダーの再番号付けを強制し、ステップの数え方を変え、付録を八言語への契約の義務的翻訳に従わせることになり、建設が緑で通る前にそれを要求することになる。しかもループがすでに持たないゲートを一つも加えない。

どう掛かるか（D-044）。 一つの正典の出所、五つのアンカー、二つの事前入口。規則のテキストはここにだけ住み、プロンプトはそれを引用する。決してコピーしない。四十五の規則をループの八つのプロンプトの中で繰り返すと、それらを薄める（各ステップ自身の仕事と競合し、エージェントは毎回違う仕方で従う）。それらを派生させる（同じテキストの二つのコピーはひとりでに同期を失う。ステップ 11 が追うアンチパターンである）。そしてそれらをより横断的にするわけではない。規則を横断的にするのは、各ブロックが同じゲートを通ることなのであり、規則がどこにでも書かれていることではない。

状態（D-049）。 五つのアンカーは接続済みである。ステップ 5、8、9、10、12 の冒頭プロンプトが本書を八言語で引用し、英語の一文はすべてで同一、その隣に各国語の翻訳が置かれている。本書は残りのメソッドとともに八言語でサイトに公開され、その二つのプロンプトは契約 anexo-h として docs/html/api/prompts.json に入った。そこから build/prompts.mjs が八言語でバイト比較し、一致しなければビルドは失敗する。

ステップ 6、7、11 はせいぜい一行を受け取る。6 はすでにしきい値と例外を決定として記録しており（宣言された例外の自然な場所である）、11 は四つの場所に書かれたマトリクスのケースが打撃とともに現れる場所である。薄めないために、独自のテキストは加えない。

三つの成果物、すべて docs/ の中にある。CODE_QUALITY.md（拡張）、USABILITY.md（新規、規則ごとの結果と宣言された例外を含む）、PROFILE_MATRIX.md（マトリクス。文書であると同時にメニューの源である）。

7. 設定

プロジェクトごとに一つのファイルが第 2 層と第 3 層を宣言する。提案された形態での例であり、最終的な値ではない。

{
  "version": 1,
  "frontend": "react-vite",
  "medido_por": {
    "formato": "prettier",
    "lint": "eslint",
    "tipos": "tsc",
    "complejidad": "eslint-complexity",
    "duplicacion": "jscpd",
    "muertos": "knip",
    "cobertura": "vitest-coverage",
    "mutacion": "stryker",
    "accesibilidad": "axe-core"
  },
  "umbrales": {
    "lineas_por_archivo": 300,
    "lineas_por_funcion": 40,
    "caminos_por_funcion": 10,
    "cobertura_minima": 0,
    "mutacion_objetivo": 0
  },
  "excepciones": [
    {
      "regla": "CQ-17",
      "motivo": "トークンを持たない継承された印刷用レポート",
      "autoriza": "所有者",
      "revisar": "2027-01-31"
    }
  ]
}

二つのゼロは意図的であり、それこそが重要な部分である。最低カバレッジはラチェットが実測値で決め、ミューテーションの目標はプロジェクトにユーザーがいるときに所有者が決める。それらがゼロで誰も宣言していないなら、ゲートはそれを発明する代わりに未宣言のしきい値として報告する。

8. 二つの部品、本方法が使う形態で

コード品質。

ユーザビリティ。

9. この提案がしないこと

• ステップを加えない。 四十五の横断的な規則（18 の品質と 27 のユーザビリティ）であり、新しい段階ではない。存在するステップに掛かる。
• スコアを発明しない。 「ユーザビリティ 78」という数値は何を直すべきかを言わず、間違った方向に最適化される。規則ごとに報告する。第 12 節は二つの派生した数値を提案するが、それらは規則とその座席の数え直しであり——品質やユーザビリティの評点ではなく——何も閉じる権限を与えない。
• 所有者を置き換えない。 最初のクリックのテスト、スクリーンショット、タスクテストは人間のものであり続ける。「動く」と「役に立つ」を区別する唯一の計器だからである。
• 工場出荷のしきい値を持たない。 アダプタのものは宣言された出発点である。自分のものを宣言しないプロジェクトはそれを継承し、そのように記録される。
• ゲートが悪いグルーピングを検出するとは約束しない。 機械は重複も孤児もないことを検証できる。グループが「管理」と名付けられていれば、それを見るのは人間でなければならない。

10. 決定：何が解決し、何が残っているか

解決済み

D-048 で閉じたもの、そしてそれが引きずる二つの訂正

プロンプトの執筆を妨げていた二つの問いはすでに回答済みである。一つ目は五行目に、二つ目は六行目に残った。しかし承認された勧告には二つの事実の誤りがあり、それらが戻らないようにここに書いておく。

1. 数え方の欠陥。 本付録が「二十七の規則」と言っていたところ、正しい数は四十五である。品質が 18（CQ-01 から CQ-18）、ユーザビリティが 27（UX-01 から UX-27）。古い数字は、半分だけを数えていた草稿から来ていた。第 6 節と第 9 節で訂正し、D-048 に注記した。D-044 のテキストは書かれたまま保持される。決定は記録であり、書き直されないからである。
2. フォーマッタ、リンタ、サイズ、複雑度は緩めない。 この勧告の以前の版は、継承された負債を抱えるプロジェクトを妨げないために、それらを「警告する」に送っていた。そうはできない。ステップ 9 がすでに今日それらをブロックしており、この拡張はそれを拡張するのであって置き換えるのではない。継承された負債は、宣言された例外——理由と再検討日を伴う——かラチェットのベースラインで解決するのであり、規則の重大度を下げて解決するのではない。

そして宣言された限界が一つある。その類で唯一だからである。CQ-12 と CQ-14 は人間の赤でブロックする。 画面が業務規則を決定していないことを証明する道具はない。それらはペンディングの閉鎖時に、手動のケースを前にし、UX-22 と UX-27 と同じ基準で検証される。プロジェクトがその閉鎖を支えられないなら、記録された決定によって AVISA に下がる。ブロックするのに誰も検証しない規則は、警告する規則より悪い。

決定ではなく暦のペンディング

翻訳。 完了した。付属文書は八言語で存在し、その二つのプロンプトはプロンプト API の一部であり、八版すべてで英語本文がバイト一致している（D-043 が要求し、build/prompts.mjs がビルドのたびに検証する）。カスティーリャ語が正典であり続ける。翻訳とカスティーリャ語が食い違えばカスティーリャ語が勝ち、同じ変更の中で翻訳を直す。

11. ゲートが見張っていることをどう確かめるか

入れて切って何も変わらないヒューリスティクスは、ゲートではなく装飾である。実装（PND-002）の受け入れテストは、各ファミリの違反を意図的に仕込んだフィクスチャ・プロジェクトである。

見られるのは色だけではない。二行の停止が報告に存在することが見られる。その行のない緑の結果は、このテストが色だけで単独では検出できない唯一の故障であり、だからこそ出力を読んで検証する。

12. コンプライアンス・ダッシュボード（決定済み：二つの数値、D-047）

状態。 2026-10-22 に D-047 で決定された。ダッシュボードは二つの数値で行き、レギュレーションの指紋を伴い、ラチェットを伴い、人間のものを割合の外に置き、座席を必須とする。ブロックを閉じる権限は与えない。以下は実装（PND-002）が満たさなければならない仕様である。

何であるか。 ゲートがすでに出した規則ごとの結果からの決定論的な派生物である。新しいものを測らず、新しいものを判断しない。数える。もしダッシュボードが規則の評決を変えられたなら、同じものに対して二つの真実の源があることになり、それはまさに本付録が UX-10（ナビゲーションはマトリクスから導出される）と CQ-14（共有状態の単一の場所）で戦っているものである。

何でないか。 受け入れ基準ではない。どの数値もブロックを閉じる権限を与えない。緑か赤かは、ブロックする各規則が一つずつ決める。ダッシュボードは傾向を記述し、何を見るべきかを指す。閉鎖のしきい値として使われ始めたら、役に立つのをやめる。数値を上げる最短の道は規則を消すことだからである。

二つの数値、決して一つではない。

二つである理由：規則を消すとコンプライアンスは上がり、カバレッジは下がる。単一の数値では消すことは無料であり、ダッシュボードは盲目を報いる。反対の方向に動く二つの数値では、近道は消える。より良いダッシュボードを見せるには、規則を消すのではなくコードを直さなければならない。そしてカバレッジは測ることなしには上げられない。

レギュレーションの指紋。 各記録は、どの物差しで計算されたかを保存する。カタログの版、有効な規則と消えた規則、フロントエンドのアダプタ、道具の版である。それがなければ、昨日の 82 と今日の 91 は同じように書かれても同じ測定ではない。二つの異なるレギュレーションであり、系列は偽である。指紋のない二つの数値は進歩の幻想を生み、それはダッシュボードを持たないより悪い。指紋が変われば、記録は比較不能と印され、そうでなければ履歴は現行の物差しで再計算される。決してそれを言わずに並べてグラフ化しない。

ラチェット。 コンプライアンスは、それを説明する記録された決定なしにブロックから次へ下がらない。CQ-08 でテストのカバレッジがすでに持っているのと同じ仕組みである。今日の数値が明日の床である。下げることは禁じられていない。記録なしで下げることは禁じられている。

勘定に入らないもの。 人だけが判断できるもの——最初のクリックのテスト（UX-07）、タスクテスト（UX-06）、スクリーンショット（UX-27）、そしてすべての手動のケース——は、ブロックごとに名前と日付とともに合格または不合格として記録され、人間による検証のカバレッジとして別に報告される。コンプライアンスの割合には入らない。混ぜれば、結果は六十パーセントが測定で四十パーセントが意見の数値になり、どれがどちらか誰にも言えない。だから第 9 節はなお有効である。ダッシュボードはユーザビリティの評点を発明せず、規則を数える。

どう反証するか。 第 11 節の受け入れテストを拡張する。

どこに現れるか。 ステップ 12 の正直な報告（アンカー 5）に、この順で。まずゲートの二値の評決、次に二つの数値、次に何がいつまで消えているか、次に前のブロックに対する動きと、その名指された原因である。常に座席を伴う。*四ポイント下がった：CQ-15、請求画面のカタログ外の三つの文字列*。座席のない数値はノイズである。座席こそが、コードを読まない所有者にとってそれを実行可能なものにする。

宣言されたリスク。 ダッシュボードを読むのはコードを読まない所有者であり、だからこそ彼はそれが上がることを望む。数値が目的になり、目的が狙いを押しのける。防御は上にあり、五つある。消すときに互いに矛盾する二つの数値、異なる物差しの比較を妨げる指紋、記録なしの下降を許さないラチェット、割合の外にある人間のもの、そして平均によって交渉されないゲートを伴う必須の座席である。五つのうちどれかが崩れれば、ダッシュボードは消える。誤って使われたダッシュボードは、持たないより多くの損害を与える。

13. 記録

本付録のすべての決定は、日付、認可者、逐語の引用、影響を受けるファイルとともに docs/DECISIONES.md に残る。D-043（形態）、D-044（仕組み）、D-045（スイッチ）、D-046（スイッチの規律）、D-047（二つの数値を持つダッシュボード）。実装とその受け入れ基準は PND-002 に住む。

未決の判断は残っていない。形態（D-043 と D-044）、スイッチ（D-045 と D-046）、ダッシュボード（D-047）、アクセシビリティの重みを含む初期重大度（D-048）は決定済みである。本文は八言語で流通し、プロンプト API の一部になっている。これで日程に残っていた唯一の項目が閉じた。