heuristic-to-deterministic

ヒューリスティックから決定論的な仕組みへ

セッションから得た知見や、繰り返し使われるレビューのヒューリスティックを、再現可能なチェック、正規化ツール、ジェネレーター、フィクスチャ、CI ジョブ、フック対応のワークフローに変換します。

判断ツリー

どのような種類のヒューリスティックを変換しますか？

• 必須または禁止される構造に関するルール
  バリデーターを使用するか、拡張します。アーティファクトの選択について詳しく確認する必要がある場合は、references/conversion-patterns.md を参照してください。

• 正規のフォーマット、画像の形状、生成出力、メタデータのクリーンアップに関するルール
  利用可能な正規化ツールを再利用し、その後、事後条件を確認します。

• 繰り返し使われるひな形や、生成ファイルのレイアウト
  マニフェストまたは明示的な計画をもとに、ジェネレーターを使用するか、拡張します。出力コントラクトで必要な形状だけを固定し、付随的なファイル構成は編集可能なままにします。

• 不安定な環境やクロスプラットフォームの障害
  その障害に応じて、ランタイムの検出、バージョンチェック、フィクスチャ、CI カバレッジを選択します。検証の深度について詳しく確認する必要がある場合は、references/verification.md を参照してください。

• 生成メディアやモデル出力に関するプロンプトのガイドライン
  プロンプトハーネスをソースとして保持し、スクリプトで検査できる特性について、生成後の決定論的なチェックを追加します。

• 測定可能な指標のない、好みや判断によるもの
  決定論的であるかのように装わないでください。例を記録し、受け入れ基準を求めるか、レビューガイダンスとして残します。

クイックリファレンス

ニーズ	アーティファクト	最初のアクション
ファイル、README ブロック、フック、設定の欠落を防ぐ	バリデーター	不変条件を記述し、実行可能な出力とともに失敗させます
マシン間で出力を一貫させる	正規化ツール	検証前にメタデータを除去し、キーを並べ替え、サイズを変更し、フォーマットするか、正規化します
ひな形の手作業でのコピーを避ける	ジェネレーター	マニフェストまたは計画ファイルを信頼できる唯一の情報源として使用します
繰り返し発生するリグレッションを防ぐ	フィクスチャまたはゴールデンテスト	修正前に失敗する、肯定例と否定例を追加します
フックや CI でチェックを再利用する	薄いラッパー	中核のコマンドを移植可能に保ち、複数のアダプターから呼び出せるようにします
モデルのアートや文章のルールを変換する	プロンプトハーネスと事後チェック	プロンプトを保存し、寸法、パス、フォーマット、必須メタデータを検証します

運用契約

1. ツールではなく、得られた知見から始めます。アーティファクトを選ぶ前に、観測された障害を一文で記述します。
2. 安定した主張だけを変換します。関連する不安定な API や製品に関する主張は、バージョン管理されたドキュメント、インストール済みツールのヘルプ、機能プローブ、最新の一次資料など、適切で信頼できる根拠で裏付けます。ルールの鮮度が重要な場合は、情報を更新します。
3. 判断と強制を分離します。人間またはエージェントが簡潔な計画でポリシーを決定し、スクリプトが形状、パス、スキーマ、サイズ、互換性を強制します。
4. 想定する用途の範囲内で、チェックを移植可能に保ちます。ツールのプロジェクトルート検出を再利用するか、対象パスを受け取るようにします。マシン固有の絶対パスは避けます。
5. ツールの文書化された終了コードの仕様と、呼び出し元の契約に従います。呼び出し元が期待する場合に限り、フックをブロックする失敗に終了コード 2 を使用し、必要に応じて境界部分でコードを適合させます。
6. 修正方法を出力します。決定論的な失敗では、ずれを修正するコマンドまたはファイルを、次のエージェントに明示します。

ワークフロー

1. ヒューリスティックを棚卸しします。

   • 何が分かりましたか？
   • どのような繰り返し発生するミスや逸脱を防ぎますか？
   • 何を安定したルールとして適用できますか？
   • 何が主観的なままですか？

2. 関連のない選択肢は開いたままにしつつ、安定した不変条件を確実に適用できる最小の仕組みを選びます。

   • はい／いいえで判定できる構造にはバリデーター。
   • 正規の表現形式にはノーマライザー。
   • 繰り返し作成するものにはジェネレーター。
   • 回帰動作の確認にはフィクスチャ。
   • 共通の信頼できる情報源にはマニフェスト。
   • 適用のタイミングには CI またはフックアダプター。

3. 作る前に再利用します。

   • リポジトリにある既存のフォーマッター、チェッカー、スキーマ、またはジェネレーターで不変条件を適用できるか確認します。
   • 十分な場合は設定または拡張し、不足している動作だけをコード化します。
   • 新しいコードは移植可能にし、隠れたグローバル状態を避けます。
   • 出力の契約で許される場合は、ジェネレーターとノーマライザーを冪等にします。

4. 検証手段を追加します。

   • リスクと成果物に応じてチェックを選び、既存のテストを使うか、焦点を絞ったフィクスチャを追加します。
   • 不変条件が満たされることと、関連する違反が検出されることを示します。
   • 書き込み処理は繰り返し実行して確認し、主張する場合は macOS／Ubuntu との互換性も確認します。

5. 適用のタイミングが対象に含まれる場合は、アダプターを接続します。

   • Stop フック、Git フック、GitHub Actions からは、同じコアコマンドを呼び出します。
   • 環境ごとに動作が分岐しないよう、アダプターファイルは薄く保ちます。

決定性の段階

過剰な約束を避けるため、次の段階に従ってください。

1. 構造的：ファイルが存在する、JSON スキーマに一致する、README ブロックが存在する。
2. 正規化：キーのソート、PNG の正規化、コードのフォーマット、メタデータの削除。
3. 動作的：フィクスチャの入力から期待する出力または終了コードが得られる。
4. 環境的：依存関係のバージョンと機能フラグを使用前に検出する。
5. 外部的：仕様に依存するルールを固定する前に、正式な証拠によってサポート対象の契約を確認する。情報の鮮度が重要な場合は、最新の情報源を確認する。
6. 主観的：例とレビュー基準のみを使用し、基準が測定可能になるまではハードエラーにしない。

ヘルパー

手早く決定論的な一次判定を行うには、scripts/classify_conversion.py を使用します。

python3 scripts/classify_conversion.py "README cards must be below install commands and hooks should block drift"

この分類器は意図的にシンプルにしています。選択した成果物で十分だという証明ではなく、計画の補助として扱ってください。

ガイダンスが役に立たなくなった場合

提案する不変条件がリポジトリの動作または現在のツール契約と矛盾する場合は、それをコード化する前に、インストール済みのツールと公式のバージョン対応情報源を確認してください。古い回避策をバリデーターに固定しないでください。失敗したアドバイス、情報源／バージョン、そして違いを明確に示すフィクスチャを添えて、正規のスキル修正を提案してください。インストール済みのコピーを黙って更新したり、確認できていない証拠を検証済みだと主張したりしないでください。

リファレンスガイド

必要な情報	参照先
成果物のパターンと、それぞれを選ぶ場面	references/conversion-patterns.md
検証の深さ、フィクスチャ、CI、フック、終了コード	references/verification.md
決定論的なチェックが脆くなるよくある原因	references/gotchas.md

注意点

1. 回避策を真実としてコード化しないでください。動作がツールのバージョンに依存する場合は、バージョンを確認するか、機能を試してください。
2. 生成されたアセットは、創作的な内容を決定論的にせずに、決定論的な制約を適用できます。寸法、形式、プロンプトファイルの差分、サイズ、配置を検証してください。
3. 適用ロジックの重複を避けてください。フック、CI、ローカルコマンドは同じスクリプトに処理を委ねる必要があります。
4. 現在の変更済み作業ツリーしか確認しないバリデーターは、ファイルが未追跡またはグローバルに無視されている場合、CI で失敗する可能性があります。パッケージ化が重要な場合は、git の可視性チェックを含めてください。
5. 修正コマンドのない厳格なチェックは、エージェントにチェックの回避を促します。失敗したときに対処できるようにしてください。