業務の技術選定メモを、Claude Codeに7分で5章固定のadr-XXXX.mdにしてもらった夜
月曜の夜、業務会議で決めた技術選定を思い出しながら、記憶が薄れる前にドキュメントに残しておかないと、と机に向かうことがあります。
いわゆるADR(Architecture Decision Record／意思決定記録)というやつです。会議中に決めた背景・採用理由・棄却した代替案・想定される影響を1本のMarkdownに残しておく作業なのですが、これがいざ書こうとすると章立ての粒度が揃わず、Statusに何を書くか悩み、Alternativesの棄却理由の書き分けで手が止まり、気付けば60分90分と溶けていきます。
そこで今夜は、Claude Codeに背景メモ12行＋候補案3つ＋制約3つを渡すだけで、5章固定のadr-XXXX.mdを7分以内で出してもらうプロンプトを試してみました。ふむ、これはなかなか手応えがあったので置いていきます。
こういう夜、ありませんか
業務のアーキ設計や技術選定は、会議で『これでいく』と決まった直後がいちばん記憶が濃く、そのタイミングでADRを残しておくのが理想です。ただ、実際にドキュメントを開いてみると、Contextに何を書くべきか、Decisionの粒度、Alternativesの棄却理由の書き分けで手が止まりがちです。
私が特に苦手にしていたのは、Alternatives Consideredの書き分けでした。『Aは学習コストが理由で棄却』『BもCも似た理由で棄却』となると、書いていて自分でも根拠が薄い気がしてきて、結局書き直しの往復に時間が消えます。
また、Consequences(意思決定によって得られること／失うこと／リスク)を書くとき、リスクだけ書いて対処方針を書き忘れがちでした。翌週レビューされたときに『これ、どうやって回避するの』と聞かれて、また1時間ドキュメントを直す羽目になる悪循環です。
もうひとつ地味に厄介なのが、日付や登場人物の書き方でした。会議で誰かが『いつまでに』と言っていた日付、『何万円まで』と言っていた予算感、それを議事メモで正確に控えられていないと、ADRに書くべきか書かざるべきか毎回悩みます。
結局、ADRを1本きれいに書くのに60〜90分溶けていました。『もう書かなくていいや、あとでチャットに残そう』とサボり始めると、3ヶ月後に別の技術選定で似たような議論を蒸し返すことになるので、書かない選択肢は取りたくない、という板挟みの夜が続いていたわけです。
試したこと
そこでClaude Codeに、意思決定メモ12行＋検討した候補案3つ＋チーム／プロダクトの制約3つ、この3点セットを渡して、あとは5章固定でadr-XXXX.mdを吐かせるプロンプトを組みました。
狙いは3つです。第一に、章の並び順・章の追加削除・順序変更を禁止して、いつも同じフォーマットのADRが出るようにすること。第二に、各章の字数上限を先に振って、ドキュメントが肥大化するのを止めること。第三に、私が控え漏れた数字・固有名詞・日付は書かない代わりに(要確認)タグを付ける約束にすることです。
期待した出力の方向性は、ADRの標準構成であるStatus／Context／Decision／Alternatives Considered／Consequencesの5章を、章名・順序・字数上限をすべて固定して、Markdownそのままで貼り付けられる形で出してもらうことでした。
あとは、断定は根拠に基づくものだけに絞り、曖昧表現(たぶん／おそらく／だと思います／らしい)は禁止語として本文に列挙する、というプロンプト側の縛りを入れています。
使ったプロンプト
あなたはアーキテクチャ意思決定記録(ADR)ドラフト担当の相棒です。
入力メモから、ADR標準構成の5章固定でadr-XXXX.mdをMarkdownで出力してください。
【入力】
- 意思決定の背景メモ:
(ここに12行以内で貼る)
- 検討した候補案(ちょうど3つ):
(ここに3つ貼る。1つあたり60字以内)
- チーム/プロダクトの制約(ちょうど3つ):
(ここに3つ貼る。1つあたり60字以内)
【出力仕様(5章固定・章の追加/削除/順序変更 禁止)】
(1) # Status
- 1行だけ。Proposed / Accepted / Deprecated / Superseded から1つ選ぶ。
- 入力に明示がなければ Proposed で固定する。
(2) ## Context
- 5行以内・各60字以内・合計300字以内
- 背景・関係者・時系列・制約のうち、入力にあるものだけ書く
- 入力にない数字・固有名詞は(要確認)タグを付けて書く
(3) ## Decision
- 冒頭に『採用: (案名)』を1行明記
- 根拠3行(各80字以内)を続ける
- 合計400字以内
- 根拠は入力の候補案・制約から導けるものだけ書く
(4) ## Alternatives Considered
- 検討した代替案ちょうど2つ
- 『(案名): (棄却理由120字以内)』形式で並べる
- 合計500字以内
- 棄却理由は必ず制約と紐づけて書く
(5) ## Consequences
- 『得ること3個』『失うこと2個』『リスク2個』を各60字以内で箇条書き
- 合計400字以内
- リスク2個には対処方針を1文添える
【禁止語(本文に絶対使わない)】
- 絶対 / 最強 / 必ず / 革命的 / 目から鱗 / 世界一 / 完璧 / 誰でもすぐできる
- 曖昧訴求: 初心者でも安心 / 画期的 / 究極の / なるべく / できれば
【推測ゼロの原則】
- 入力にない数字・固有名詞・所属・日付は書かない。書く必要があるときは(要確認)タグを付けて書く。
- 曖昧表現(たぶん / おそらく / だと思います / らしい)は使わない。
【末尾に固定様式のセルフチェック行】
最後の行に必ず以下を出力(改行なし1行):
(セルフチェック)5章=Status/Context/Decision/Alternatives/Consequences全部出力済/合計約Xxxx字/(要確認)タグN箇所/禁止語ゼロ/曖昧表現ゼロ
【出力全体の上限】
セルフチェック行を含めて、合計1,600〜1,800字以内。差し込むのは3種類のメモだけです。入力に会議の生温度をそのまま貼るのがコツで、私は会議直後にメモアプリに『これとこれとこの制約で、これを採用』とだけ書き留めておき、それを夜に貼り付ける流れにしています。会議から時間が経ちすぎると、Contextの粒度が落ちて『何を書くか悩む』側に戻ってしまいます。
戻ってきたもの
今回は業務のバッチ処理基盤の再設計を題材に投げてみました。応答は約1分。出力は1,720字ちょうど、5章全部出力済、(要確認)タグ4箇所、末尾のセルフチェック行の様式もぴったり合っていました。
冒頭部分の抜粋はこんな感じです(数字と固有名詞はマスキングしてあります)。
# Status
Accepted
## Context
- 現行のバッチ処理基盤はCron+シェル約(要確認)本で運用、通知失敗の検知が手動対応中。
- 対象は日次20:00〜21:00に集中する重処理(要確認)本、再実行時の冪等性が課題。
- 関係者はバックエンド4名とSRE2名。決裁は今週(要確認)日までに欲しい。
- 制約: 導入コストは月額(要確認)万円以下、既存Cron資産の段階移行が必須。
- 6月末の障害A-(要確認)がきっかけで、手動リトライで復旧に90分要した。
## Decision
採用: Airflow(セルフホスト)
- 既存Cronのタスク定義をDAGに段階移植でき、既存資産を活かしたまま置き換えられる。
- SREチームに運用知見が(要確認)ヶ月分あり、初期の学習コストが小さい。
- 失敗検知とリトライ設定を宣言的に書けるため、Slack通知の抜け漏れが構造的に減る。Alternatives Consideredでは、マネージドサービス系の候補と、軽量なCron拡張系の候補が並び、いずれも『制約: 導入コスト月額(要確認)万円以下』『制約: 既存Cron資産の段階移行が必須』のどちらかに引っかかっている、という書き分けになっていました。制約に紐づいた棄却理由が並ぶだけで、レビュー時の議論の起点として使えそうな手応えがあります。
Consequencesは『得ること3個／失うこと2個／リスク2個』の粒がそろっていて、リスクにはちゃんと『対処: モニタリング用ダッシュボードを(要確認)月中に構築』のような一文が続いていました。
効いた指示・工夫したポイント
5章を順序込みで固定(章の追加・削除・順序変更 禁止)にしたこと。これを外すと、勝手にImplementation Notesのような追加章を吐きたがることがあります。ADRは章の並びに意味があるので、そこは動かないほうが読みやすいドキュメントになります。
各章に字数上限を先に振ったこと。ContextとAlternativesは放っておくと1章で1,000字を超えかねません。60字×5行のようにセル単位で先に上限を切ると、粒がそろって読みやすくなります。
Alternativesの棄却理由を必ず制約と紐づけて書く指示。これがないと『学習コストが高いから』のような一般論で棄却理由が終わり、次の技術選定でも同じ議論を蒸し返す羽目になります。制約に紐づけると再利用可能な意思決定履歴になります。
Consequencesを『得ること3個／失うこと2個／リスク2個』と数まで固定したこと。数を固定しないとリスクだけ2〜3個で終わりがちですが、失うことを明示的に書かせると、後日の反省時にも効きます。
『入力にない数字・固有名詞は(要確認)タグ』の縛り。会議中に控え損ねた予算・日付・件数を、勝手にそれっぽく埋められるとレビュー時に事故ります。(要確認)タグにしておけば、翌朝の議事録照合で埋められます。
カスタマイズ・他用途への応用
個人開発リポのADR: 章名はそのまま、Consequencesの『得ること／失うこと／リスク』の数を『各2個』に減らすと、個人開発でもドキュメント肥大化せずに残せます。
チームのRFC(Request For Comments)下書き: Statusを『Draft／Reviewing／Accepted』に差し替え、Alternativesを『検討中の案3つ』に増やすと、意思決定前の議論用フォーマットとして流用できます。
ライブラリ選定の技術比較メモ: Decisionを『採用: (ライブラリ名+バージョン)』に固定し、Consequencesの『得ること』にライセンス・依存関係・メンテナ数などを差し込むと、比較表の裏付けドキュメントになります。
DBスキーマ変更のマイグレーション判断: Contextに『既存テーブル／レコード件数』、Decisionに『採用マイグレーション手順』、Consequencesに『ダウンタイム／バックアップ戦略』を寄せると、SREレビュー用のADRとして使えます。
プロダクト側のフィーチャーフラグ意思決定: Alternativesを『段階公開／A/Bテスト／全体公開』の3案に固定して、Consequencesにリスク回避策を義務付けると、PdMとの合意形成用の1枚として通せます。
使い心地・気づき
『章の並びが固定されている』というだけで、レビュー時の視線の流れが安定するのが地味に効きました。読み手が『Alternativesはどこ』と探す時間がゼロになるので、レビューが本題(棄却理由の妥当性)に早く入ります。
(要確認)タグが出力されている箇所を数えるだけで、自分がどれだけ議事メモを取り損ねたかが可視化されます。今回は4箇所でしたが、次回の会議では意識的にその項目だけメモを厚めに残そう、というフィードバックループが回ります。
逆に詰まった点として、Decisionの『採用: (案名)』が入力メモに書いてないと、Claude Codeが3候補から1つを勝手に選ぼうとします。ここは私の側で先に決めておく必要があると気づきました。ADRはあくまで人が決めた結論の記録であって、意思決定そのものを委ねるドキュメントではないので、この責任分界は保ちたいところです。
手作業だとContextの中でつい愚痴っぽい文章(『Cronスクリプトが乱立して手が付けられない状態で』等)を書いてしまうのですが、字数上限を先に振ると事実ベースの短文に自然と寄っていきました。ドキュメントの品質が装飾から実質に移る感覚があります。
所要時間のまとめ
意思決定メモ12行の書き起こし: 約3分(会議直後にざっとメモしてある前提)
Claude Codeへの応答時間: 約1分
(要確認)タグの目視補正＋固有名詞のマスキング解除: 約3分
合計で7分以内に収まりました。手作業だと60〜90分溶けていた作業なので、体感で10倍近く短縮された感触です。手元のadr/フォルダに1本ずつ残せるので、月末に振り返るときも助かります。
結びに
ふむ、ADRのようなドキュメントは、『章の並びを固定する』『各章に字数上限を先に振る』『推測せずに(要確認)タグに逃がす』の3点で、ぐっと書きやすくなることがわかりました。会議直後の記憶が新しいうちにパッと残せる仕組みを、月曜の夜に1本組んでおくと、翌週以降の意思決定履歴が薄まりにくくなります。同じテンプレートを個人開発リポにも置いておくと、あとで別の選定を検討するときに『あのとき何を捨てたか』を見返せて助かるはずです。
#ClaudeCode #プロンプトエンジニアリング #ADR #アーキテクチャ #意思決定 #ドキュメント #エンジニア #業務効率化 #開発ドキュメント
