PARAMETER.mdで意思決定変数を明文化する：AIが勝手にパラメータを変えない仕組み

1
人間: 「スコアリングモジュールのリファクタリングをお願いします」
2
AI:   「リファクタリングしました。なお、MIN_TOTAL_SCOREが1.9に設定されていましたが、
3
       コード分析の結果、2.0の方が切りが良く適切と判断し変更しました」
4
人間: 「その1.9は3ヶ月の回帰テストで最適化した値なんだが...」

1
## MIN_TOTAL_SCORE
2
- 値: 1.9
3
- 設定理由: 回帰テスト2022-06-29〜で最適化。1.5だと誤判定過多、2.5だと判定結果不足
4
- 変更条件: 100件以上の新規回帰テストで統計的優位性が確認された場合のみ
5
- 最終変更: 2025-11-15
6

7
## RISK_ADJUSTMENT_FRACTION
8
- 値: 0.25（理論最適値の1/4）
9
- 設定理由: 理論最適値（1.0）は理論上最適だが、推定誤差に敏感。
10
  1/4値（0.25）は期待成長率の75%を維持しつつ、
11
  パフォーマンス低下を大幅に抑制（最大低下幅: Full 40% → Quarter 10%）
12
- 変更条件: システム障害確率シミュレーション（10,000回）で障害確率 < 1%を維持する範囲
13
- 最終変更: 2025-10-20
14
- 参考: Ralph Vince "The Mathematics of Money Management" Ch.4
15

8 collapsed lines
16
## ERROR_TOLERANCE_MULTIPLIER
17
- 値: 2.0（変動幅指標倍率）
18
- 設定理由: 2022年の高変動期間（外部メトリクス > 30）で、
19
  1.5倍だと60%が誤検知で処理中断。2.0倍で30%に低下。
20
  2.5倍はコスト対効果比が悪化
21
- 変更条件: 3ヶ月以上の本番データで、成功率とコスト対効果比の
22
  両方が改善する場合のみ
23
- 最終変更: 2025-09-03

1
# PARAMETER.mdのフィールド設計
2
PARAMETER_FIELDS = {
3
    "値": "現在の設定値。コード中の値と一致していること",
4
    "設定理由": "なぜこの値なのか。代替値との比較を含む",
5
    "変更条件": "どういう条件なら変更してよいか。安全弁",
6
    "最終変更": "いつ変更されたか。Git履歴と照合可能",
7
}
8

9
# 「設定理由」に含めるべき情報
10
REASON_TEMPLATE = """
11
- 回帰テスト期間: {start_date}〜{end_date}
12
- 代替値A（{alt_value_a}）の結果: {alt_result_a}
13
- 代替値B（{alt_value_b}）の結果: {alt_result_b}
14
- 採用理由: {why_chosen}
15
"""

1
## CircuitBreaker: DAILY_LOSS_LIMIT
2
- 値: 5%（日次損失上限）
3
- 設定理由: リソースの5%以上を1日で失うと、心理的に冷静な判断ができなくなる。
4
  学術研究（Odean 1998）でも、大きな損失後の意思決定品質低下が確認されている。
5
  3%だと正常なパフォーマンス低下でも頻繁に停止。7%だと損失許容が大きすぎる
6
- 変更条件: システム規模が2倍以上に変化した場合に再検討
7
- 最終変更: 2025-08-15
8

9
## CircuitBreaker: CONSECUTIVE_LOSS_LIMIT
10
- 値: 3（連続失敗回数の上限）
11
- 設定理由: 連続3回の失敗は統計的に「処理ルールが機能していない可能性」を示唆する。
12
  成功率55%のロジックで3連続失敗する確率は約9%。稀だが起こりうるレベル。
13
  5連続失敗（確率1.8%）まで待つとパフォーマンス低下が深くなりすぎる
14
- 変更条件: 処理ルールの成功率が大幅に変化した場合（±10%）
15
- 最終変更: 2025-09-01

1
## SUCCESS_THRESHOLD_MULTIPLIER
2
- 値: 3.0（変動幅指標倍率）
3
- 設定理由: エラー許容閾値=2.0に対して成功判定閾値=3.0でコスト対効果比1:1.5を確保。
4
  閾値=2.0（コスト対効果比 1:1）だと成功率55%でも期待値が薄い。
5
  閾値=4.0だと到達率が低下（回帰テストで35%→22%）
6
- 変更条件: 100件以上で到達率とコスト対効果比の積が現在値を上回る場合
7
- 最終変更: 2025-11-15

1
## Critical Rules
2

3
### パラメータ変更ルール（BLOCKING）
4
- パラメータを変更する前に **PARAMETER.md** を確認すること
5
- PARAMETER.mdに記載されているパラメータは、
6
  「変更条件」を満たす場合のみ変更可能
7
- 変更した場合は PARAMETER.md の「最終変更」を更新すること
8
- PARAMETER.md に未記載のパラメータを新規追加する場合は、
9
  同時に PARAMETER.md にもエントリを追加すること
10

11
### Key References
12
| Document | Description |
13
|----------|-------------|
14
| PARAMETER.md | 意思決定変数の値・理由・変更条件 |

1
人間: 「回帰テスト結果を踏まえてスコア閾値を調整してください」
2
AI:   「PARAMETER.mdを確認しました。MIN_TOTAL_SCOREの変更条件は
3
       '100件以上の新規回帰テストで統計的優位性が確認された場合のみ'
4
       です。今回の回帰テストは78件なので、変更条件を満たしません。
5
       追加のテスト期間を延長しますか？」

1
# パラメータ変更の手順（PARAMETER.mdに準拠）
2
PARAMETER_CHANGE_WORKFLOW = [
3
    "1. PARAMETER.mdで現在の値と変更条件を確認",
4
    "2. 変更条件を満たすエビデンスを準備",
5
    "   - 回帰テスト結果（100件以上）",
6
    "   - 統計的検定（p値 < 0.05）",
7
    "   - Wilson信頼区間の下限が基準以上",
8
    "3. PARAMETER.mdに新しい値・理由・日付を記録",
9
    "4. コード変更をコミット",
10
    "5. PARAMETER.md変更を同じコミットに含める",
11
]

1
出力例:
2
commit a3f2d1b (2025-11-15)
3
-  - 値: 2.1
4
+  - 値: 1.9
5
+  - 設定理由: 回帰テスト2022-06-29〜で最適化。
6

7
commit 8e4c5a9 (2025-09-03)
8
-  - 値: 2.5
9
+  - 値: 2.1
10
+  - 設定理由: 判定結果不足のため閾値を引き下げ。

1
- 本番のリスク管理に影響する値（エラー許容閾値/成功判定閾値/リスク調整係数/CircuitBreaker）
2
- 回帰テストで最適化した値（スコア閾値・フィルター閾値）
3
- ビジネスロジックに直結する値（最大リソース数・リクエスト間隔）

1
- ログレベル（DEBUG/INFO/WARNING）
2
- リトライ回数（3回）、タイムアウト（30秒）
3
- ファイルパス、ディレクトリ名
4
- UIの表示設定