ハードコードされた閾値の『鮮度』を疑う：staleness検知をCIに組み込む発想

リポジトリのコードを読んでいて、ふと 「この閾値、いつ決めたっけ?」 と思ったことはありませんか? 私は最近、MAX_RETRY = 3 という値を見て、自分が3年前に書いたものだが、今も適切なのか思い出せないことがありました。

これは AI 駆動開発になってさらに深刻化します。なぜなら AI agent はリポジトリの既存値を「正解」として踏襲するからです。本記事は、ハードコードされた値に「鮮度」の概念を持ち込む運用ルールの記録です。

事の発端：Claude Code が古いタイムアウト値を踏襲した

新しい API クライアントを Claude Code に書かせていたら、こんなコードが出てきました。

1
TIMEOUT = 30  # seconds
2
MAX_RETRY = 3
3
RETRY_BACKOFF = [1, 2, 4]

これらの値を聞かれず提示されたので、「リポジトリ内の他のクライアントを参考にした?」と聞くと、

はい、existing_client.py の値を踏襲しました。

確かに existing_client.py には同じ値がありました。しかし、その値は3年前に別のチームメンバーが「とりあえず」で入れた値で、その後のサービス変化を反映していませんでした。本来は TIMEOUT = 5、MAX_RETRY = 5 の方が今の SLA に合います。

つまり、古い値が「リポジトリの正解」として agent に学習され、新しいコードにも伝染したのです。

ハードコード値が腐る3つのパターン

リポジトリ内のハードコード値は、時間とともに以下のように腐ります。

1. 外部仕様の変化

API のレートリミットが変わった
レスポンスサイズの上限が変わった
認証方式が新しくなった

書いた時点の仕様で RATE_LIMIT = 100 と入れていても、提供側が変えれば古くなります。

2. 内部 SLA の変化

レスポンスタイム要件が「1秒」から「200ms」に厳格化
リトライ予算が削減された
バックオフ戦略が変わった

組織やプロダクトの方針変化で、適切な値が変わります。

3. 環境の変化

インフラのスループットが上がってタイムアウトを短くできる
並列度が増えて1リクエストあたりの予算が変わる
監視粒度が細かくなって早めにエラー検知できる

これらは「古いから危険」ではなく、**「古いから機会損失」**になります。

「最終確認日」を値に持たせる

シンプルな対処は、ハードコード値に 「いつ正しさを確認したか」 をコメントで持たせることです。

1
# Last verified: 2026-04-15 (against External API v3.2)
2
TIMEOUT = 5
3

4
# Last verified: 2026-03-20 (against SLA doc rev 4)
5
MAX_RETRY = 5

このコメントがあると、コードレビュー時や agent が読む時に**「鮮度」**が分かります。1年以上前の値が出てきたら警戒できます。

staleness 検知を CI に組み込む

コメントを書くだけだと、結局誰も見ません。CI で staleness を機械検知する仕組みを入れます。

Step 1: 鮮度マーカーをパースするスクリプト

1
import re
2
from datetime import datetime, timedelta
3
from pathlib import Path
4

5
STALENESS_DAYS = 365  # 1年経ったら警告
6
PATTERN = re.compile(r'# Last verified: (\d{4}-\d{2}-\d{2})')
7

8
stale = []
9
for py_file in Path('.').rglob('*.py'):
10
    for i, line in enumerate(py_file.read_text().splitlines(), 1):
11
        m = PATTERN.search(line)
12
        if not m:
13
            continue
14
        verified = datetime.strptime(m.group(1), '%Y-%m-%d')
8 collapsed lines
15
        age = (datetime.now() - verified).days
16
        if age > STALENESS_DAYS:
17
            stale.append(f"{py_file}:{i} verified {age} days ago")
18

19
if stale:
20
    print("STALE values detected:")
21
    print("\n".join(stale))
22
    exit(1)

Step 2: CI 設定に追加

1
on: [pull_request, schedule]
2
schedule:
3
  - cron: '0 9 * * 1'  # 毎週月曜 9 時に走らせる
4
jobs:
5
  staleness-check:
6
    runs-on: ubuntu-latest
7
    steps:
8
      - uses: actions/checkout@v4
9
      - run: python scripts/check_staleness.py

PR のたびに走らせると邪魔なので、スケジュール実行にして週次レポート的に扱うのがオススメです。

AI agent への明示指示

このルールを CLAUDE.md に書き込みます。

1
## ハードコード値の鮮度管理
2

3
定数・閾値・タイムアウト・URL・APIバージョンを定義する際は、必ず
4
`# Last verified: YYYY-MM-DD (verified against XXX)` のコメントを
5
直前の行に付ける。
6

7
既存リポジトリから値を踏襲する場合は、コメントの日付を確認すること:
8
- 1年以内: そのまま使ってよい
9
- 1年以上: 「この値の鮮度が古いです。最新の仕様を確認しますか?」と
10
  ユーザーに確認すること

これを書いておくと、Claude Code が古い値を踏襲しようとした時に必ず一言確認してくれます。

既存リポジトリへの段階的導入

「全部の定数にコメントを付ける」のは現実的でないので、段階的に入れます。

Phase 1: 新規追加分のみ強制

新しい値を追加する時だけ、必ずコメントを付ける。既存値は触らない。これだけでも数ヶ月後には「鮮度が分かる値」の比率が増えます。

Phase 2: 変更時にも要求

既存値を変更する PR では、コメントも更新する。CI で「変更されたが verified コメントが更新されていない」ケースを検出。

Phase 3: 「鮮度不明」値の棚卸し

四半期に一度、コメントが付いていない値を全件抽出して「これは妥当か」を確認する祭りを開く。AI agent に「この値の妥当性を確認するためにどんな調査をすべきか」を提案させると効率的です。

なぜ AI 駆動開発でこの問題が深刻化するのか

人間だけで書いていた時代、古いハードコード値は 「書いた人の記憶」 で何とか管理されていました。「あれはお試しで入れた値だから、本番では見直そう」と覚えていた人が、レビューや改修のタイミングで指摘していました。

しかし AI agent には記憶がありません。リポジトリにあるものは全て「現在採用されている正しい値」と認識します。これが伝染すると、新しいコードに古い値が複製されていくという事故が起きます。

つまり AI 駆動開発では、「コードの中の知識の鮮度」を機械的に管理する必要が出てきます。人間の記憶という暗黙の仕組みが効かなくなるからです。

副次効果：レビュー観点の言語化

このルールを運用していると、「値を見る時の観点」が言語化されます。

いつ確認したか?
何に対して確認したか?（API バージョン、SLA ドキュメント、など）
確認方法は再現可能か?

これはコードレビューの品質にも効きます。reviewer が「この値、最近確認した?」と聞きやすくなります。

まとめ：定数にも賞味期限がある

ハードコードされた値は、書いた瞬間の前提を永遠に保持します。一方で、世界はその後も変わり続けます。この乖離が事故と機会損失を生みます。

対処は、

値に「最終確認日」コメントを付ける
CI で staleness を機械検知
AI agent に古い値の踏襲を確認させる

の3つです。特に AI 駆動開発では、agent がリポジトリ内の値を「正解」として学習するので、「正解ラベル」を時間でフィルタする仕組みが必要になります。

定数を見るたびに「これ、いつ正しかった値?」と問えるリポジトリを作っておくと、agent との協働品質が一段上がります。