feat(lint): env_keys drift 検知を本番経路へ拡張 + AI フレンドリーさダッシュボードを追加

[yusuke0610]

概要

env 名 SSoT（env_keys.py）の drift 検知を本番注入経路まで拡張し、あわせて「AI フレンドリーなアーキテクチャ」の効果を PR 履歴から月次観測するダッシュボードを追加する。

変更内容

1. lint-env-keys の強化（scripts/lint-env-keys.sh）

従来は「env_keys.py ⊆ docker-compose.yml」の正方向のみの検証で、事故時に最も痛い本番注入経路（cloud_run）が手順書頼みだった。以下の 3 検知を追加:

検知	内容
cloud_run 逆方向	infra/modules/cloud_run/main.tf の env 名（静的 env block + secret locals キーの 27 件）がすべて env_keys.py に存在するか。rename/削除時の旧名残留・typo を検知
compose 逆方向	同上を docker-compose.yml にも適用
リテラル参照禁止	backend/app での os.getenv("XXX") / os.environ["XXX"] 直書きを禁止（env_keys 定数経由を機械強制。従来は規律のみ）

• 3 検知とも一時的に違反を注入するネガティブテストで fail することを確認済み
• 既存コードは全チェック green（make lint-env-keys を nix 経路で確認）
• env_keys.py docstring / Makefile help を実態に追従

2. AI フレンドリーさダッシュボード（新規）

• scripts/metrics-ai-friendliness.sh: マージ済み PR（bot 除く 307 件）から手戻りコミット率 / CodeRabbit 指摘密度 / ルール追記コミット数を月次集計し、docs/metrics/ai-friendliness.md（mermaid xychart）を全再生成
• PR 単位の計測値は docs/metrics/ai-friendliness-data.json に保持（マージ済み PR は不変のため差分のみ API 取得）
• make metrics-ai-friendliness ターゲットと README 導線を追加

レビュー時の注意

• 手戻り率が 2026-05 から「上昇」して見えるのは規約導入起因（review(...) 規約と CodeRabbit の導入以前は観測不能）。ダッシュボードの「読み方の注意」に観測開始月を動的算出して明記済み
• docs/metrics/ai-friendliness-data.json（44KB / 307 レコード）は生成データのコミュニケーションであり、レビュー対象外として読み飛ばして OK
• CI の fail 条件が 3 つ増える（今後 infra の env rename 追従漏れで CI が落ちるようになる。それが目的）

テスト

• make lint-env-keys（nix 経路）green
• 新検知 3 種のネガティブテスト（違反注入 → fail → 復元）
• ruff check app/core/env_keys.py pass
• ダッシュボード初回生成 + キャッシュヒットでの再生成を確認
• アプリ実行コードの変更なし（env_keys は docstring のみ）のため test-backend / test-web への影響なし

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added an “AI friendliness” dashboard with monthly charts and trend data.
  • Added a command to regenerate the dashboard data and report.

• Bug Fixes

  • Improved environment key validation across app, compose, and cloud deployment config to catch mismatches earlier.
  • Strengthened checks to prevent direct string-based environment lookups in the backend.

• Documentation

  • Updated help text and project docs to include the new dashboard and related validation guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f66bdc06-573d-4a45-aa6a-7bcba694f7f5

📥 Commits

Reviewing files that changed from the base of the PR and between 55b1e36 and c59c936.

📒 Files selected for processing (7)

• Makefile
• README.md
• backend/app/core/env_keys.py
• docs/metrics/ai-friendliness-data.json
• docs/metrics/ai-friendliness.md
• scripts/lint-env-keys.sh
• scripts/metrics-ai-friendliness.sh

---

📝 Walkthrough

Walkthrough

Adds a new metrics-ai-friendliness Makefile target and script that regenerates a cached PR metrics JSON and a generated Markdown dashboard, linked from README. Separately extends lint-env-keys.sh and its documentation to add reverse env-name checks against Cloud Run Terraform and backend literal-reference detection.

Changes

AI friendliness metrics dashboard

Layer / File(s)	Summary
Metrics generation script scripts/metrics-ai-friendliness.sh	New script fetches merged PRs/commits/review comments via GitHub API, caches per-PR metrics, aggregates monthly stats (rework rate, comments per PR, rule-touch counts), and renders the dashboard.
Generated cache data and dashboard doc docs/metrics/ai-friendliness-data.json, docs/metrics/ai-friendliness.md	Adds populated cache JSON and generated Markdown dashboard with metric definitions, caveats, Mermaid charts, and a monthly data table.
Makefile target and README link Makefile, README.md	Adds metrics-ai-friendliness target/help text and a README link to the generated dashboard.

Env-key drift lint extension

Layer / File(s)	Summary
Reverse env-key and literal-reference checks scripts/lint-env-keys.sh	Adds CLOUD_RUN_TF parsing and reverse validation of compose/cloud_run env names against env_keys.py, backend literal-reference detection for os.getenv/os.environ, and an updated success message.
Drift-check documentation updates backend/app/core/env_keys.py, Makefile	Updates drift-detection explanatory comments to describe compose/cloud_run reverse checks and literal-reference validation scope.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• yusuke0610/devforge#424: Extends the same lint-env-keys.sh SSoT drift-check logic and env_keys.py documentation introduced in this earlier PR.

Poem

A rabbit counts each PR's trail,
Rework and comments, month by tale.
Cloud Run's env names, checked both ways,
Literal strings get no free pass, always.
Dashboards bloom in charts of green — hop, review, and glean! 🐰📊

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: expanded env_keys drift detection and the new AI friendliness dashboard.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/env-lint-hardening-and-ai-metrics

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}