← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-0106type: adrstatus: accepted
pagemode: Standardkruchten: Existence / Propertyscope: platformimplementation_status: Done (PRproposed_at: 2026-06-02 23:00approved_at: 2026-06-02 23:27deciders: [email protected] (単独)business: meta
型付き辺: 出 6 / 入 0
細分化する: ADR-0042 関連: ADR-0050 ADR-0063 ADR-0132 ADR-0107 ADR-0130全体は INDEX →

ADR-0106: プロンプト管理に索引カタログ・実行済みアーカイブ・設計パターン集を追加する (ADR-0042 拡張)

  • Status: Accepted (PR #1327 merge = 受理の規約により 2026-06-02 受理。2026-06-11 の Status×Impl 整合調査で遡及反映・代表取締役指示)
  • Mode: Standard
  • Kruchten Type: Existence / Property
  • Scope: platform
  • Implementation Status: Done (PR #1326)
  • 起案者: [email protected] ([email protected])
  • 起案日時 (JST): 2026-06-02 23:00
  • 承認日時 (JST): 2026-06-02 23:27
  • Deciders: [email protected] (単独)

TL;DR（要旨・専門語ゼロ）: プロンプトのファイルが増えすぎて、探す邪魔になり・実行後も放置され・良い書き方を再利用できていなかった。そこで (1) 全プロンプトを 1 枚の索引に自動でまとめ、(2) 一度使い終わった使い捨てプロンプトは「使用済み」の印を付けて一覧から外し、(3) よく効いた書き方を別ページにまとめる、の 3 つを決める。本番プロンプトの厳格管理 (ADR-0042) はそのままに、それ以外の散らかりを片付ける仕組みを足す。

1. コンテキスト

1.1 背景 (Background)

ADR-0042 は本番プロンプト (Type 1) のライフサイクルを厳格管理する一方、調査プロンプト (Type 3) と一度きりの操作プロンプト (one-shot: 起案 KV〔Key-Value ストア〕投入 / 実装指示 / 事後検証) は「最小管理」と位置づけ、規約を置かなかった。

1.2 現状 (Current State / As-Is)

docs 配下のプロンプト .md は 65 本に達し、うち one-shot 25 本は実行後も status: ready-to-execute のまま残存。nav と全文検索を圧迫し、どこに何があるか・何が実行済みかを横断把握する手段がない。

1.3 課題 (Problem)

3 つの痛みがある。(1) 数が多く管理不能、(2) ドキュメントを探すとき邪魔、(3) 効いた書き方のノウハウ分析ができない。実測で one-shot 25 本中 23 本が実行済み ADR 対応にもかかわらず未アーカイブだった。

1.4 制約・要件 (Constraints & Requirements)

  • ADR-0042 の Type 1 厳格管理・prompt.meta.yaml 規約 (ADR-0063) は変更しない。
  • プロンプト本文・ADR 本体は書き換えない (one-shot は frontmatter の status のみ)。
  • 既存の docs lint (nav-lint R4/R5・frontmatter・link-check) を壊さない。
  • 索引は手作業で陳腐化しない仕組みにする (自動生成)。

1.5 目標 (Goals / To-Be)

プロンプトを「探す入口 1 枚 + 使用済みの可視化 + 設計型の蒸留」で管理可能にする。Non-Goals: Type 3・one-shot に Type 1 並みの meta.yaml を課すこと、プロンプトの物理削除。

2. 判断基準 (Decision Drivers)

ADR-0050 の Q42 9-tag MCDA を適用 (WSM + K.O. criterion / Suhr 1999 CBA〔Choosing By Advantages〕準拠)。

2.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#maintainable[Must] (×2.0)索引が陳腐化せず追従するか
2#usable[Must] (×2.0)探す・実態把握の入口が 1 つに集約されるか
3#operableHigh (×1.0)既存 lint (nav R4/R5・frontmatter) を壊さず運用できるか
4#suitableHigh (×1.0)ADR-0042 の Type 体系と整合するか
5#efficientMedium (×0.5)導入・継続コスト

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

2.2 評価軸 × 案スコア表

各案を 0-5 で評価。加重和は (Σ score × 係数) / (満点 × Σ 係数) で正規化 (0.0-1.0)。

軸係数採択 (自動カタログ + archived + パターン集)X1 現状維持X2 全 meta.yaml 強制X3 物理削除
#maintainable [Must]×2.05132
#usable [Must]×2.05133
#operable High×1.04522
#suitable High×1.05323
#efficient Medium×0.54513
加重和 (正規化、満点 32.5)0.9380.4770.5080.523
K.O. 通過 (Must ≥3)✓❌ (#maintainable=1, #usable=1)✓❌ (#maintainable=2)

採択首位 = 自動カタログ + archived + パターン集。

3. 検討した代替案 (Considered Options)

  • 案 A: 自動カタログ + status: archived + パターン集 (採用)
    • Good, because 索引が自動生成で陳腐化せず、探す入口が 1 枚に集約される。
    • Good, because ADR-0042 の Type 体系を壊さず隙間 (Type 3・one-shot) だけ補える。
    • Bad, because one-shot 25 本の status 更新と nav 整理の初期手間がかかる。
  • 案 B (X1): 現状維持
    • Good, because 追加作業ゼロ。
    • Bad, because 散らかりと管理不能が継続 (#maintainable=1, #usable=1 で K.O.)。
  • 案 C (X2): 全プロンプトに Type 1 並みの meta.yaml を強制
    • Good, because 全プロンプトが機械管理可能になる。
    • Bad, because 使い捨ての Type 3・one-shot に過剰な規約で、運用負荷が高い。
  • 案 D (X3): 古いプロンプトを物理削除
    • Good, because ファイル数が即座に減る。
    • Bad, because 起案・実装の監査証跡が失われ、#maintainable=2 で K.O.。

4. 決定 (Decision Outcome)

採用: 案 A。理由: 本番の厳格管理 (ADR-0042) を温存しつつ、散らかりの実体 (Type 3・one-shot) だけを最小コストで片付けられるから。

具体規約:

  • 索引 SSoT: scripts/prompt-catalog.mjs が docs 配下のプロンプトを走査し docs/_internal/06_ops/prompt_catalog.md を自動生成する。手書き禁止・--check で CI 整合確認可。探すときはまず本カタログを見る。
  • アーカイブ規則: 対応 ADR が Accepted の one-shot プロンプトは、ファイルを移動せず frontmatter を status: archived に更新し、nav (_config.json) から外し、.docs-nav-lint-allowlist.json のパターンで orphan 警告を抑止する。
  • 設計パターン集: 実プロンプトで効いた「中身の型」を docs/_internal/05_how-to/prompt_patterns.md に蒸留する (外部ベストプラクティスは RQ-044、運用は prompt_lifecycle_guide、規約は prompt-lint_rules と非重複)。

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • 探す入口が 1 枚に集約され、nav の prompt 関連が 22 本減る。
  • one-shot の実行済み状態が可視化され、status が実態に一致する。
  • 効いた設計型が再利用可能になり、新規プロンプトの品質が安定する。

5.2 負の影響 (Bad)

  • カタログ生成スクリプトの保守対象が 1 つ増える。
  • アーカイブ判定が frontmatter の status 更新に依存し、更新を怠ると再び乖離する。

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

  • archived プロンプトは削除せず残すため、ファイル総数自体は減らない (監査証跡優先)。
  • nav 除去に伴う R4 接頭辞の連番振り直しが将来も必要 (接頭辞は他 doc 未参照のため R5 波及なし)。

コスト試算 (Cost Estimate)

  • 初期 (AI 支援あり): カタログ script 2h / アーカイブ照合 + 25 本更新 ~1h / パターン集 ~1h = 計 **4h** (PR #1326 実績)。
  • 初期 (手作業換算・参考): 上記 1.5 倍の **6h**。
  • 継続: 新規プロンプト追加時のカタログ再生成 ~1min、実行後の status: archived 更新 ~2min/本。
  • 削減効果: 探索の認知コスト削減 + one-shot 25 本の棚卸し (1 回切り ~1h 相当の手作業を恒久回避)。

6. 撤退条件 (Rollback Plan)

  • 再評価トリガー: カタログ生成スクリプトの保守コストが月 30min を超える、または --check が頻繁に false 検出する。
  • 判定タイミング: 3 ヶ月後 (2026-09-02)。
  • 判定主体: 代表取締役。
  • ロールバック手順: (A) prompt-catalog --check を CI から外し手動運用に格下げ (5min) → (B) カタログ自動生成を廃止しカタログ .md を静的ファイル化 (30min)。archived status と allowlist パターンは残置。

Confirmation (準拠確認 / Fitness Function)

  • 検証手段: node scripts/prompt-catalog.mjs --check (カタログが最新か) + node scripts/docs-nav-lint.mjs (nav R4/R5 整合・archived は allowlist で警告抑止)。
  • 実行頻度: PR ごと (CI)。
  • 違反時の対応: --check 不一致なら再生成してコミット (自動 fail)。月次で archived 漏れ (Accepted ADR 対応で status: ready-to-execute 残存) が 5 本未満であることを確認。

7. 参照 (References)

7.1 プロジェクト内参照

  • 関連 ADR: ADR-0042 (拡張元 / プロンプトライフサイクル管理) / ADR-0063 (prompt-lint 規約) / ADR-0050 (Q42 MCDA) / ADR-0105 (用語 Tier 規約)
  • 関連 PR/Issue: #1326
  • 既存 doc: scripts/prompt-catalog.mjs / docs/_internal/06_ops/prompt_catalog.md / docs/_internal/05_how-to/prompt_patterns.md / docs/_internal/06_ops/prompt_lifecycle_guide.md

7.2 設計根拠 (Theoretical Foundation)

  • arc42 ch.12 Glossary / 用語 SSoT: arc42
  • Suhr, The Choosing By Advantages Decisionmaking System, Quorum Books, 1999 (ISBN: 1-56720-217-9)