← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:32
commonid: adr-0063type: adrstatus: accepted
pagemode: Standardkruchten: Existence/Propertyscope: platformimplementation_status: Not Startedproposed_at: 2026-05-22 23:06approved_at: 2026-05-22 23:20 (Pipeline 通常 flow v3 …deciders: [email protected] (単独)business: meta
型付き辺: 出 9 / 入 1
細分化する: ADR-0042 関連: ADR-0050 ADR-0059 ADR-0060 ADR-0061 ADR-0062 ADR-0106 ADR-0054 ADR-0058 部分修正された: ADR-0070全体は INDEX →

ADR-0063: prompt-lint Rule Reference SSoT 確立

  • Status: Accepted
  • Mode: Standard
  • Scope: platform
  • Kruchten Type: Existence/Property
  • Implementation Status: Not Started
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-22 23:06
  • 承認日時 (JST): 2026-05-22 23:20 (Pipeline 通常 flow v3 49/50 通過)
  • Review After: 2026-08-22 (3 ヶ月), 2026-11-22 (6 ヶ月), 2027-05-22 (1 年)
  • Deciders: [email protected] (単独)

コンテキスト

1.1 背景 (Background)

ADR-0042 (LLM Prompt Lifecycle Management Policy) で確立した Type 1 production prompts の規約検証は scripts/prompt-meta-lint.mjs で実装されているが、規約 doc 集約なし。

1.2 現状 (Current State / As-Is)

  • 対象: prompts/production/*/prompt.meta.yaml (現状 6 dirs: body-generation / gate0-triage / gate1-socratic / gate2-consistency / gate3-parallel-review / gate4-scoring)
  • 9 REQUIRED_FIELDS (id / owner / status / semver / model_pin / output_schema / eval_suite / eval_pass_threshold / kv_key) 【注: model_pin は 2026-06-08 廃止 → 現 8 種。理由は prompt-lint_rules.md §5.5】
  • threshold 検証: eval_pass_threshold >= global_min_threshold (.promptpolicy.yaml 0.70)
  • semver_rules + state_transitions (draft → experiment → candidate → production → deprecated → archived、90 日 auto-archive) は .promptpolicy.yaml 内のみ
  • ADR-0042 本文には設計意図のみ、Rule Reference は不在

1.3 課題 (Problem)

痛みの定量化 (proxy 実測 + 再評価):

  • proxy 実測 (n=6): 6 prompts の prompt.meta.yaml 新規作成・更新時、9 フィールド意味確認に prompt-meta-lint.mjs ソース + .promptpolicy.yaml + ADR-0042 本文の 3 箇所参照往復 が必要。実測 ~15-25min/prompt (session log proxy)

  • 集計データ実体 (n=6 内訳, proxy):

    #session 起点主な参照対象工数 (min)
    1body-generation 起案 (ADR-0042 V1)9 fields 意味確認 + threshold 値検討~25
    2gate0-triage 移植model_pin 形式確認 + state transition~20
    3gate1-socratic 起案output_schema 設計 + eval_suite 命名~25
    4gate2-consistency 起案semver 境界判断~15
    5gate3-parallel-review (3 vendor) 起案kv_key 命名 + owner~20
    6gate4-scoring N=1 簡略化threshold 0.70 維持 + state~15
    合計(9 fields × 6 prompts)~120min ≈ 2h

  • 集計手順: git log --all --oneline -- prompts/production/ で commit 抽出 → git diff で field 編集行 count → 平均 ~3-5min/field × field 数

  • 信頼区間: ±25% (1.5-2.5h)

  • 再評価: Jr 入社後 2 ヶ月 (2026-12) で実測 n≥10 prompts に置換、上記表を実測データで更新

規約改訂時の整合性:

  • 9 フィールドの意味と必須理由が散在 (3 箇所参照)
  • semver/state_transitions の運用判断 (major/minor/patch 境界、transition trigger) が暗黙
  • 新規 prompt 追加時の参照コスト: 6 dirs を見て勘で書く属人運用
  • ADR-0058 (frontmatter-lint SSoT, Accepted+実装済) との不整合 (同パターン未適用)

1.4 制約・要件 (Constraints & Requirements)

  • ADR-0054 (10 節 + YAML codeblock + AST 整合性) 構造踏襲
  • doc 行数 ≤500 (400 warn / 500 error)
  • ADR-0042 (Prompt Lifecycle) との整合
  • .promptpolicy.yaml との二重管理を避ける (doc=人間可読、yaml=機械可読 truth)
  • 既存 adr-lint-doc-consistency.mjs (ADR-0054 + ADR-0058 Phase 2 拡張済) との整合

1.5 目標 (Goals / To-Be)

docs/_internal/05_how-to/prompt-lint_rules.md 新規、9 必須フィールド + threshold + semver + state transition 規約を 1 doc 集約。ADR-0054 + ADR-0058 同パターン で SSoT 確立。

決定

ADR-0054 10 節構造 + YAML コードブロック方式踏襲。ADR-0058 (Accepted+実装済) の adr-lint-doc-consistency.mjs 拡張パターン準拠 で、docs/_internal/05_how-to/prompt-lint_rules.md を新規作成し、9 必須フィールド + threshold + semver + state transition を 1 doc に集約する。既存 scripts/adr-lint-doc-consistency.mjs を拡張して 3 way CI (script / doc / .promptpolicy.yaml) 整合性を自動検証する。

採用方針詳細

10 節構造:

  1. Purpose / 2. Severity Legend / 3. Category Legend (Required / Threshold / Lifecycle) / 4. Summary Table / 5. Required Fields Detail / 6. Threshold Rules / 7. Semver Rules / 8. State Transitions / 9. Legacy / 10. Changelog

YAML コードブロック (各 field 8 フィールド): id / severity (error|warn) / category (required|threshold|lifecycle) / since / status: active / fixable: false / description / related_adrs

9 必須フィールド一覧:

FieldCategoryDescription
idrequiredプロンプト識別子 (kebab-case)
ownerrequired担当者 (email)
statuslifecycledraft / experiment / candidate / production / deprecated / archived
semverrequiredsemver 形式 (major.minor.patch)
model_pin—廃止 2026-06-08 (runtime 未使用・SSoT=gateway.ts MODELS)
output_schemarequired出力スキーマ参照 (JSON Schema or 'free-text')
eval_suiterequiredpromptfoo eval suite 名
eval_pass_thresholdthresholdglobal_min_threshold 以上必須
kv_keyrequiredCloudflare KV active pointer key

実装方式: 既存 adr-lint-doc-consistency.mjs 拡張 (ADR-0058 Phase 2 同パターン、3 way 整合 CI)。不採用: 新 script 新設 (保守負荷増) / regex のみ (AST 採用、ADR-0058 で実証)。

Special case 除外 (allowlist): .adr-lint-doc-consistency-allowlist.json に prompt_lint_special_cases 追加: id_pattern + skip_rules + reason (例: experimental-* で threshold 未確定許容)。初期 ≤ 3 件、超過は ADR 再評価。

判断基準 (Decision Drivers)

ADR-0050 / ADR-0054 / ADR-0058 と同 Q42 5 軸 + WSM + K.O. (Suhr 1999 CBA 準拠)。

3.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#maintainable[Must] (×2.0)9 フィールド + 規約 3 カテゴリの保守一元化、3 箇所参照排除
2#suitable[Must] (×2.0)ADR-0042 Immutability 維持 + scope (prompts/) 適合
3#operable[High] (×1.0)CI 3 way 整合自動検証、Pipeline 内運用負荷
4#reliable[High] (×1.0)regex でなく AST + try/catch、ADR-0058 実証パターン
5#usable[Medium] (×0.5)Jr onboarding 参照容易性、9 fields 通読性

K.O. criterion: Must 軸の score < 3 は不採用。

3.2 評価軸 × 案スコア表

軸係数採択案X1 yaml schemaX2 ADR-0042 追記X3 何もしないX4 ADR-0058 統合
#maintainable [Must]×2.053 (人間可読性低)2 (Immutability 違反)13 (scope 越境)
#suitable [Must]×2.0541 (Immutability 違反)12 (frontmatter と別系統)
#operable High×1.055555
#reliable High×1.054324
#usable Medium×0.553313
加重和 (正規化)1.0000.7380.4610.2920.554
K.O. 通過 (Must ≥3)✓✓❌❌❌

採択首位 = ADR-0054 + ADR-0058 同パターン。

検討した代替案 (Alternatives Considered)

  • 採用案: ADR-0054 + ADR-0058 同パターン (第四適用例) — 実証済、保守一元化
  • X1: yaml schema (JSON Schema) のみ — 機械可読だが人間可読性低 (#maintainable=3)、加重和 0.738 で次点だが SSoT 効果薄い
  • X2: ADR-0042 本文追記 — K.O. (Immutability 違反、#suitable=1)
  • X3: 何もしない — K.O. (#maintainable=1、Jr 入社で属人運用崩壊)
  • X4: ADR-0058 doc に統合 — K.O. (frontmatter と prompt は別系統、scope 越境、#suitable=2)

影響 (Consequences)

5.1 正の影響 (Good)

  • ADR-0042 prompt lifecycle 規約の SSoT 確立、6 prompt + 将来増分対象
  • Jr 引き継ぎコスト削減 (9 フィールド意味の質疑応答 ~1.5h → 1 doc 通読)
  • prompt 新規追加時の手戻り削減 (semver/state 判断基準明文化)
  • ADR-0054 + ADR-0058 パターンの 第四適用例 として実証性向上

5.2 負の影響 (Bad)

  • 初期コスト ~5-7h (doc + CI 拡張)
  • .promptpolicy.yaml と doc の二重管理 → 3 way CI で整合性自動検証
  • 9 fields + threshold + semver + state の 4 カテゴリで Summary Table 拡大、500 行制約注意

5.3 中立・トレードオフ (Neutral / Trade-offs)

影響範囲:

  • 改修対象: docs/_internal/05_how-to/prompt-lint_rules.md 新規 (~250-350 行)、scripts/adr-lint-doc-consistency.mjs 拡張 (+50-80 行)、.adr-lint-doc-consistency-allowlist.json に prompt_lint_special_cases 追加
  • 検証対象: prompts/production/*/prompt.meta.yaml (6 dirs、将来増分対象)、.promptpolicy.yaml (global SSoT、doc から正規参照)
  • 波及: Pipeline 内 prompt 運用が主スコープ (他 AI Agent 影響なし、ADR-0042 経由)、CI workflow paths 拡張のみ
  • Decider: 代表取締役 (単独) / レビュアー: prompt-meta-lint.mjs 実行結果 + sub workspace audit / 将来 stakeholder: Jr (2026-10)

運用上の罠:

罠対処
semver 境界判断 (major/minor/patch trigger)§7 に判断 flow chart + 例示 (output_schema 変更=major / threshold 厳格化=minor)
state transition trigger (draft→experiment 等)§8 に各 transition の許容前提 (eval pass / owner approval) を明示
eval_pass_threshold ぎりぎり (0.70)§6 に「global_min 0.70 厳守、超過なら experimental allowlist」明示
.promptpolicy.yaml と doc 二重管理3 way CI で値整合 (yaml / doc / script)、ADR-0058 同方式
model_pin 形式揺れ (claude-opus-4-7 vs claude-4-7)§5 に正規形式 + 慣用形式の対応表
YAML codeblock parse errortry/catch + WARN 出力 (削除なし、ADR-0058 Phase 2 同方針)

コスト試算:

  • 初期実装: doc 執筆 ~3-4h + CI 拡張 ~2-3h = 5-7h、レビューバッファ +30% で 7-9h
  • 継続運用 (12 ヶ月): .promptpolicy.yaml 同期 0.7-1h/年 + 月次 review 3h/年 + 新 prompt 追加更新 ~1-1.5h/年 = **5-6h/年**
  • 削減: Jr 引き継ぎ 1.5h (1 回切り) + 判断迷い回避 20min/件 × 月 2 件 = ~0.67h/月 = **8h/年**
  • ROI (改定: 継続運用控除込み):
    • 元式 (誤): (7-9h 初期 - 1.5h Jr 効果) ÷ 0.67h/月 = 8-12 ヶ月で回収 — 継続運用 5-6h/年 を控除していない楽観値
    • 正式: (7-9h 初期 - 1.5h Jr 効果) ÷ (8h/年 削減 - 5-6h/年 継続運用) = 5.5-7.5h ÷ 2-3h/年 net 削減 = 約 2-3.5 年で回収
    • net 削減維持: 継続運用は削減効果を完全には打ち消さず、年 2-3h の純削減を確保 (Jr 入社後加速で改善)
    • 長期 ROI 観点: 3 年回収後は年 2-3h の永続削減、5 年累積で ~10-15h 削減

撤退条件 (Rollback Plan)

6.1 撤退判断指標

  • 3 ヶ月後 (2026-08-22): 新規 prompt 0 件 → 「過剰防衛」、WARN 維持 or 削除検討
  • false-positive 率 > 30% (allowlist 3 件超) → revert
  • adr-lint-doc-consistency.mjs 維持コストが他 rule 系の 2 倍超 → 撤退

6.2 ロールバック手順 (3 段階)

  • (A) ADR Superseded のみ: doc + CI 拡張 touched せず、Status=Superseded
  • (B) CI 拡張 revert + doc 保持: adr-lint-doc-consistency.mjs の prompt-lint rule 削除 (~50-80 行) + allowlist フィールド削除
  • (C) 全廃: doc → _deprecated/ 移動 (30min) + (B) 同 + ADR-0042 / .promptpolicy.yaml 参照を _meta/README.md 再集約 (30min)。合計撤退コスト ~1-1.5h

6.5 Confirmation (準拠確認)

  • 検証 1 (機械): adr-lint-doc-consistency.mjs 拡張で 3 way CI (script / doc / .promptpolicy.yaml) 整合検証、毎 PR、違反時 CI fail で merge block
  • 検証 2 (機械): docs:build + 行数 ≤500 (400 warn)、毎 PR、warn は次回改修候補、error は merge block
  • 検証 3 (手動 + AI dry-run): Jr (2026-10) onboarding 目視 + 中間検証 2026-08-22 / 11-22 に AI dry-run、違反検出時は doc 改訂 PR

検証可能な完了条件

#観測指標目標値測定
1doc 完成 (10 節 + 9 fields + 規約 3 カテゴリ)≤ 500 行wc -l
2各 field YAML 8 フィールド9 × 8 全件AST 抽出
33 way CI 整合 (.promptpolicy.yaml + script + doc)0 FAILCI ログ
4nav 登録F.X.X entrydocs-nav-lint.mjs
5docs:build + 故意違反テスト0 warn、検出可テスト PR
63 ヶ月後 新規 prompt 件数 ≥ 1 + 規約遵守率 100%件数 ≥1, 遵守 100%git log + prompt-meta-lint
7Jr onboarding 工数 (2026-10 実測)≤ 30minJr 入社後実測

Review After / 負債化リスク

  • Review After: 2026-08-22 (3 ヶ月、新規 prompt 1 件以上 + 規約遵守率 100%) / 2026-11-22 (6 ヶ月、.promptpolicy.yaml 改訂追従 + Jr 入社後運用) / 2027-05-22 (1 年、semver/state 運用実態反映 doc 改訂)
  • リスク 1: prompt 数 20+ で Detail 肥大化 → Progressive Disclosure 分割 (閾値: 9 → 15 fields or doc ≥ 400 行、ADR-0054 §X5 パターン)
  • リスク 2: ADR-0042 v2 でフィールド変更時の doc 同期負荷 / promptfoo 等 eval ツール変更で eval_suite / eval_pass_threshold 規約改訂
  • リスク 3: lint rule 群肥大化 (frontmatter + dev-spec + prompt + adr + docs-nav の 5 系統) → 1 年後 umbrella ADR (docs-lint-suite.mjs、ADR-0057 §7.2 言及) 検討
  • 将来検討事項: 真の SSoT 化 (script ← doc 動的 import) は本 ADR スコープ外、Jr 入社後 6 ヶ月で別 ADR 検討 (ADR-0058 §5.3 整合)

参照 (References)

過去決定との関係 + namespace 分離

ADR関係namespace
ADR-0042 (Refines)prompt lifecycle 規約 SSoT 集約。本文は 片方向参照のみ (Immutability)prompts/production/*/prompt.meta.yaml
ADR-0054 (Confirms 第四適用例)10 節 + YAML codeblock 構造踏襲—
ADR-0058 (Confirms 同パターン第三適用例, Accepted+実装済)adr-lint-doc-consistency.mjs 拡張 + 3 way CIdocs/ 配下 frontmatter (別系統)
ADR-0059 (補完並立)docs-nav-lint R5docs/index.md / _config.json (別系統)
ADR-0060 (補完並立)memory システム~/.claude/projects/<slug>/memory/ (別系統)
ADR-0061 (補完並立)handover prompttasks/prompts/ (別系統)
ADR-0062 (補完並立)dev-spec-lintdocs/dev/dev_*.md (別系統)
ADR-0050 (Confirms)Q42 9-tag MCDA—

関連資料

  • 既存 script: scripts/prompt-meta-lint.mjs (ADR-0042 起源、9 REQUIRED_FIELDS) / scripts/adr-lint-doc-consistency.mjs (ADR-0054 + ADR-0058 Phase 2 拡張済、本 ADR で prompt-lint rule 追加)
  • 既存 doc / config: .promptpolicy.yaml (global threshold / semver / state SSoT) / docs/_internal/05_how-to/frontmatter-lint_rules.md (ADR-0058 実装、同パターン参照モデル)
  • 将来統合: docs-lint-suite.mjs umbrella (ADR-0057 §7.2)
  • 関連 PR/Issue: PR #929 (本 ADR 起案、Pipeline auto-PR、Proposed merge), PR #930 想定 (本 audit + Accepted)

8. 参照: Pipeline 審査履歴 (2026-05-22 実行時, 通常 flow)

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を通常 flow (retroactive=false) で審査した結果のログ。v1 (169 行) は audit 未実行、v2 (300 行) は Cloudflare 100s edge timeout 524 リスクで投入見送り、v3 (193 行) に圧縮して投入 → 49/50 で Standard 閾値 40 + Critical 閾値 45 双方クリア。ADR-0056 §8 / ADR-0058 §11 / ADR-0057 §8 / ADR-0059 §11 / ADR-0060 §8 / ADR-0061 §8 / ADR-0062 §8 で確立した §audit history パターンの 第八適用例 (本日 audit 通過 5 件目)。デフォルトでは折りたたまれており、▶ をクリックで展開する。

📋 Pipeline 審査履歴 全 Gate 結果 (合格 Score 49 / 50) — クリックで展開

Pipeline 圧縮戦略 (v2 → v3、ADR-0062 524 経験を活用)

ADR-0062 (dev-spec-lint) で v2 (306 行) → 524 timeout → v3 (175 行) で通過した経験から、本 ADR は最初から v3 圧縮版 (193 行) で投入し 524 を回避。両 ADR で圧縮戦略の有効性が実証された。

Gate 0-4 結果

  • Gate 0 Triage: needsAdr=true / triageMode=Standard / 理由: ADR-0042 prompt lifecycle 規約の SSoT 確立、6 prompt + 将来増分対象
  • Gate 1 Socratic: pass=true (追加質問 0 件)
  • Gate 2 Consistency: PASS (9 ADR + namespace 分離明示)
  • Gate 3 Parallel Review: 3 vendor 出力は §改善余地 に要約
  • Gate 4 Scoring: 49 / 50
#採点項目点数コメント
1問題定義5proxy 実測 n=6 + 内訳表 + git log 集計手順 + 信頼区間 ±25% + Jr 入社後の実測置換計画 (2026-12) まで明示。
2代替案5X1〜X4 の 4 案、K.O. 判定 + 加重和スコア表で定量比較。
3判断基準5Q42 5 軸 + Must/High/Medium 係数 + K.O. criterion + 加重和正規化。
4過去 ADR 整合性5ADR-0042/0050/0054/0058〜0062 の 9 件を Refines/Confirms/補完並立 で分類、namespace 分離明示。
5影響範囲5改修対象 + 検証対象 + 波及 + Decider/レビュアー/将来 stakeholder。
6運用上の罠56 罠 (semver / state / threshold / 二重管理 / model_pin / YAML parse) と対処を表で明示。
7ロールバック性5撤退判断指標 3 + A/B/C 3 段階 + 撤退コスト ~1-1.5h。
8コスト試算4初期 7-9h + 継続 5-6h/年 + 削減 ~0.67h/月 + ROI 8-12 ヶ月と粒度高いが、ROI 計算に継続運用 5-6h/年を控除しておらず楽観的。実質 2.8-3.5 年の可能性 (本 PR で §7 ROI 計算式を正式化、約 2-3.5 年に改定)。
9完了条件57 指標 + 目標値 + 測定手段すべて観測可能。
10長期的影響5Review After 3 段階 + リスク 3 件 + 将来検討事項。

合計: 49 / 50 (Standard 閾値 40 → PASS, Critical 閾値 45 → PASS)

改善余地 (本 PR で反映済)

#指摘反映先効果
1§7 ROI 計算に継続運用 5-6h/年を控除しておらず実質 2.8-3.5 年回収の可能性§7 ROI を 2 段階明示: 元式 (誤) + 正式 (継続運用控除込み)、約 2-3.5 年で回収。net 削減 2-3h/年 + 長期 ROI 観点 (5 年累積 10-15h) も追記コスト試算 4/5 → 5/5 見込

改善効果見込: 49/50 → 50/50 達成可能性。

Reviewer 補足 (本 PR で反映外、Review After で対応予定)

  • proxy 実測 (n=6) の Jr 入社後実測置換 (2026-12) — §1.3 で既に明示済、確実な実行を Review After 2026-08-22 / 11-22 / 2026-12 でリマインド

Status 遷移

  • v1 起案 (2026-05-22 KV 投入) → audit 未実行 (Phase 2 改善判定で v2 直接 POST)
  • v2 投入見送り (ADR-0062 v2 で 524 timeout を経験、同サイズで失敗予見) → v3 (193 行、-36%) 圧縮版投入
  • v3 → Pipeline 通常 flow 49/50 通過 → auto-PR #929 生成 (Proposed)
  • 本 PR で Status: Proposed → Accepted に更新、改善余地 1 件 (§7 ROI 計算式) を同時反映