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 | #operable | High (×1.0) | 既存 lint (nav R4/R5・frontmatter) を壊さず運用できるか |
| 4 | #suitable | High (×1.0) | ADR-0042 の Type 体系と整合するか |
| 5 | #efficient | Medium (×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.0 | 5 | 1 | 3 | 2 |
#usable [Must] | ×2.0 | 5 | 1 | 3 | 3 |
#operable High | ×1.0 | 4 | 5 | 2 | 2 |
#suitable High | ×1.0 | 5 | 3 | 2 | 3 |
#efficient Medium | ×0.5 | 4 | 5 | 1 | 3 |
| 加重和 (正規化、満点 32.5) | 0.938 | 0.477 | 0.508 | 0.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)