💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

원문 렌더가 준비되기 전까지 텍스트 가이드로 표시합니다.

はじめに — スペックがコードになった時代

「シニアエンジニアの主力言語は英語(自然言語)だ」というジョークがあります。2026年、このジョークはもはやジョークではありません。Googleのデザインドック文化をまとめたMalte Ublの「Design Docs at Google」は今でもGeekNewsとHacker Newsで定期的に再浮上しますが、最近の再注目の文脈は変わりました。AIコーディングエージェントが普及し、よく書かれたスペックや設計ドキュメントがほぼそのまま動くコードに変換される時代が来たからです。

Claude CodeやCodexのようなエージェントに仕事を任せたことがある方なら実感しているはずです。曖昧な設計を渡せば曖昧なコードが返ってきて、明確なデザインドックを渡せば数日分の仕事が数時間で返ってきます。CLAUDE.mdやAGENTS.mdを書くことが新しいエンジニアリングの慣行として定着したのも同じ流れです。書くことはもはや「ソフトスキル」ではなく、人とAIの両方を動かす実行インターフェースなのです。

この記事は、ふわっとした「文章力の重要性」の説教ではありません。デザインドックとADRの具体的なテンプレート、セクション別の書き方、レビューを通過するドキュメントの技術、悪い文章を直すビフォー/アフター、そしてAIを書くことに活用する実践プロンプトまで — 明日から使えるものだけを詰め込みました。

文章力がシニアのレバレッジである理由

コードは一度にひとつのシステムを動かしますが、文章は一度に複数の人の頭を動かします。具体的には3つのレバレッジがあります。

1. 非同期組織の帯域幅

会議は参加者の数だけ時間を消費しますが、ドキュメントは一度書けば無限に読まれます。10人が参加する1時間の設計会議は10人時(person-hour)を消費します。同じ内容を2時間かけてドキュメントに書き、各自が10分ずつ読めば約3.7人時です。さらにドキュメントは、6ヶ月後に入社した新メンバーにも、深夜に障害対応するオンコールエンジニアにも、再び機能します。会議はそうはいきません。

2. 思考の品質検証

Amazonがパワーポイントを禁止して6ページのナラティブを強制している理由は有名です。文章はごまかしを許さないからです。頭の中では完璧に見えた設計が、文章にした瞬間に穴を露呈します。「ここでキャッシュを無効化すればいいだろう」と考えることと、無効化のタイミングと競合状態を文章として書き出すことは、まったく異なるレベルの思考を要求します。

3. AI時代の増幅

2026年の新しい変数です。よく書かれたデザインドックは、AIエージェントにそのまま入力できる実行計画です。「コンテキストエンジニアリング」がプロンプトエンジニアリングに代わるキーワードとなった今、良いドキュメントを書く能力とAIに良いコンテキストを与える能力は、事実上同じ能力です。ドキュメントが書けないエンジニアは、AIレバレッジでも遅れを取ります。

ドキュメント類型マップ — いつ何を書くか

ドキュメントごとに目的と寿命が異なります。間違った類型を選ぶと努力が無駄になります。

| --- | --- | --- | --- | --- |

| ADR | なぜこう決めたのか | 戻しにくい決定の直後 | 永久 | 1〜2ページ |

選択基準を一行でまとめるとこうです。**これからやる仕事の設計はデザインドック、すでに下した決定の記録はADR、合意が必要な提案はRFC、事故の教訓はポストモーテム、繰り返す手順はランブック。** 最もよくある間違いは、ADRを書くべき場面で何も書かないことと、デザインドックで十分な場面でRFCプロセスを回して全員を疲弊させることです。

デザインドックテンプレート — セクション別の書き方

Googleスタイルのデザインドックをベースに、実務で磨いた骨格です。そのままコピーして使っていただいて構いません。

デザインドック: 注文イベントパイプライン v2

状態: レビュー中 | 作成者: キム・ヨンジュ | レビュアー: A, B | 最終更新: 2026-06-12

1. 要約 (3文以内)

注文イベント処理を単一コンシューマからパーティションベースの

並列処理に移行する。目標はp99処理遅延を8秒から500ms以下に

減らすこと。マイグレーションはデュアルライトで4週間かけて

段階的に行う。

2. 背景と問題

- 現在の構造と、何がなぜ痛いのか (指標を含む)

- このドキュメントを読むのに必要な最小限のコンテキスト

3. ゴール / 非ゴール

ゴール:

- p99遅延500ms以下

- コンシューマ障害時の自動再処理

非ゴール:

- イベントスキーマの変更 (別プロジェクト)

- リアルタイム分析のサポート

4. 提案する設計

- アーキテクチャ概要 (ダイアグラム)

- データモデル、API、障害処理、セキュリティ

- 主要なトレードオフとその根拠

5. 検討した代替案

- 代替案A: 現構造 + 垂直スケーリング (却下理由)

- 代替案B: 完全新規システム (却下理由)

- 比較テーブル必須

6. 懸念事項とオープンクエスチョン

- まだ答えのないことを正直に

7. マイグレーションとロールバック計画

8. 測定計画

- 成功をどの指標でいつ判定するか

セクション別のコツは次の通りです。

1. **要約**: ドキュメントで最も重要な3文です。忙しいレビュアーはここしか読みません。「何を、なぜ、どうやって」がすべて入っていなければなりません。本文を書き終えた後、最後に書き直してください。

2. **背景と問題**: 新入社員が読んでも理解できるレベルが基準です。ただし長くてはいけません。リンクで置き換えられる背景はリンクに置き換えます。核心は「痛みの定量化」です — 「遅い」ではなく「p99が8秒なのでCSチケットが週40件発生している」。

3. **ゴール/非ゴール**: 非ゴールこそが本当の中身です。非ゴールを明示しないと、レビューがスコープ論争に流れ、実装中に範囲が膨らみます。「今回はやらないこと」を釘付けにすることが、ドキュメントが与える最大の平和です。

4. **提案する設計**: ダイアグラム1枚は10段落に勝ります。トレードオフを隠さないでください。レビュアーはどうせ見つけます。先に言えば信頼が積み上がり、隠してバレれば信頼が削られます。

5. **検討した代替案**: このセクションのないデザインドックは、デザインドックではなく通告文です。後ほど詳しく扱います。

6. **オープンクエスチョン**: 「わからない」と書けるドキュメントが良いドキュメントです。レビュアーのエネルギーをまさにこの地点へ誘導する効果もあります。

ADRの書き方 — コンテキスト、決定、帰結

ADR(Architecture Decision Record)は「なぜ」を記録する最も軽い形式です。Michael Nygardの原型そのままに、3つの部分で十分です: コンテキスト(決定時点の状況と制約)、決定(何をすることにしたか)、帰結(この決定で得るものと受け入れるもの)。

実際の例を2つ見てみましょう。

ADR-014: メッセージキューにKafkaではなくSQSを使う

状態: 承認済み (2026-05-20)

コンテキスト

注文イベントパイプラインにメッセージキューが必要。1日あたり

約200万イベント、ピーク時は秒間300件。チームにKafka運用

経験者がおらず、インフラ専任は0.5人分。イベント順序の保証は

注文ID単位でのみ必要。

決定

SQS FIFOキューを使う。注文IDをメッセージグループIDとして

使い、部分的な順序を保証する。

帰結

- (+) 運用負担ゼロ、既存のAWS IAM体系を再利用

- (+) ピークトラフィックの10倍まで追加作業なしで吸収

- (-) スループット上限が存在。秒間3,000件超で再設計が必要

- (-) リプレイがKafka比で不便。別途アーカイブバケットを運用

- 再検討トリガー: 1日のイベントが2,000万件に達した時

ADR-021: フロントエンドの状態管理を追加ライブラリなしで行う

状態: 承認済み (2026-06-02)

コンテキスト

管理者ダッシュボードの新規開発。サーバー状態がデータの95

パーセントで、クライアント専用状態はモーダルの開閉やフィルタ

程度。チームはすでにReact Queryを使用中。過去のプロジェクト

でReduxボイラープレートの保守に四半期あたり約2週間を費やした

実績がある。

決定

グローバル状態ライブラリを追加しない。サーバー状態はReact

Query、クライアント状態はURLクエリパラメータとコンポーネント

ローカル状態で処理する。

帰結

- (+) 依存と学習コストがゼロ、状態の出所が明確

- (-) 複雑なクライアント状態が増えるとprop drillingのリスク

- 再検討トリガー: 3階層以上のprop伝達が5箇所以上発生した時

ADRで守るべき3つの原則です。

1. **決定の直後に書く。** 2週間も経てば「なぜそうしたのか」の半分は蒸発します。ADRは記憶ではなく現場の記録です。

2. **未来の懐疑者のために書く。** ADRの読者は、6ヶ月後に「一体なぜSQSにしたんだ?」とgit blameをたどってきた人です。その人が同じ論争を繰り返さずに済むようにするのが目的です。

3. **再検討トリガーを明示する。** 「この条件になったらこの決定は再協議する」と書いておけば、ADRが教条になるのを防げます。

レビューされるドキュメントの技術 — 読む人の10分を設計する

ドキュメントは書くのが半分、読まれるのが半分です。レビュアーの10分を設計する技術です。

1. **結論ファーストの強制**: すべてのセクションの最初の文が、そのセクションの結論でなければなりません。レビュアーが最初の文だけ読んで飛ばしても全体の論旨がつかめるドキュメントが良いドキュメントです。

2. **レビュー依頼のスコープ指定**: 「全体的に見てください」は最悪の依頼です。「セクション4の障害処理方式と、セクション5の代替案B却下理由、この2点について意見が欲しいです」のように、レビュアーのエネルギーを配分してあげてください。

3. **読了時間の明示**: ドキュメントの冒頭に「想定読了時間8分」と書きます。些細に見えますが、「後で読もう」キューからドキュメントを引き出す効果は絶大です。

4. **コメント期限の設定**: 「6月19日までにコメントがなければ承認とみなして進めます」は無礼ではなく配慮です。期限のないレビュー依頼は永遠に終わりません。

5. **質問を埋め込んでおく**: 意見が必要な箇所に「オープンクエスチョン: XとYのどちらが良いでしょうか?」をインラインで埋め込むと、レビュアーは白紙から批評を始めるよりずっと参加しやすくなります。

悪いドキュメントを直す — ビフォー/アフター

抽象的なアドバイスより実際の校正が早いです。よくある悪い段落を直してみましょう。

ビフォー:

現在のシステムにはさまざまな問題があり、改善が必要である。

性能も良くなく、保守も難しい。したがって、新しいアーキテクチャ

を導入すれば、多くの側面でさまざまなメリットが期待される。

問題点: 定量化なし(「良くなく」)、主体なし(「期待される」)、根拠のない結論(「したがって」)、すべての言葉が曖昧(「さまざまな」「多くの側面」)。

アフター:

注文照会APIのp99遅延が3.2秒である(目標500ms)。原因は

注文・決済・配送テーブルの3重ジョインである(付録Aの実行計画

を参照)。リードモデルを分離すればジョインが除去され、p99を

400ms以下に下げられる。コストはイベント同期コード約2週間分と

最大1秒の結果遅延であり、注文照会画面はこれを許容する

(PM確認済み、リンク)。

変わったこと: すべての主張に数字、すべての因果に根拠、すべてのトレードオフに受容可能性の確認。文の数はほぼ同じですが、情報密度は5倍です。良いテクニカルライティングとは華麗な文章ではなく、**検証可能な文章**を書くことです。

反対意見の扱い方 — 代替案比較テーブルの義務化

説得力のあるドキュメントの秘密をひとつ挙げるなら、これです。**反対者が言うであろうことを、先に言ってしまうこと。** 検討した代替案セクションに比較テーブルを義務化すれば、自然とそうなります。

| --- | --- | --- | --- |

| 実装コスト (高) | 2週間 | 1週間 | 2日 |

テーブルが強制するものは2つです。第一に、却下された代替案にも長所があることを認めることになります(代替案Bの実装コスト2日は本当に魅力的です — これを隠すとレビュアーが見つけ出し、ドキュメント全体の信頼が崩れます)。第二に、判断基準と重みを明示することになり、論争が「好みの争い」から「基準の合意」へと移ります。レビュアーが結論に反対しても、「重みの見方が違う」に論点が絞られれば、その論争は生産的です。

ドキュメント文化の導入ガイド — 軽く始める

ドキュメント文化のないチームにフルセットのプロセスを押し付けると必ず失敗します。段階的な導入経路です。

1. **第1段階 (ひとりで、今週から)**: 次に「戻しにくい決定」が出たとき、ADRを1枚書きます。許可を求めないでください。ただ書いてPRに添付します。ADRは1枚ものなので誰も反対しません。

2. **第2段階 (チーム、1ヶ月)**: ADRディレクトリをレポジトリに作り(docs/adr/)、テンプレートを入れておきます。「戻すのに1週間以上かかる決定はADRを残そう」という軽い合意だけを作ります。

3. **第3段階 (チーム、四半期)**: 新規プロジェクト1つにデザインドックを試験適用します。効果を測定すること: 実装中の方向転換の回数、レビューで発見された設計欠陥の数。

4. **第4段階 (組織)**: デザインドックレビューを定例化しますが、「すべての仕事にデザインドック」は絶対に禁止です。基準の例: 2人週以上の仕事、またはチーム境界を越える変更のみ。

核心の原則は、**ドキュメントが仕事を助けるという体感が、強制より先に**来なければならないということです。最初のADRが6ヶ月後、新入社員の「なぜこうなってるんですか?」にリンクひとつで答えた瞬間、文化はひとりでに広がります。

AIを書くことに活用する方法と限界

2026年にデザインドックを白紙から書く人はまれです。しかしAI活用には、うまくいくパターンと失敗するパターンが明確に分かれます。

うまくいくパターン3つです。

1. **ドラフト生成ではなく構造生成**: 「Xについてのデザインドックを書いて」は、もっともらしいが中身のないドキュメントを生みます。代わりに、自分の考えを書き殴ったメモを渡して構造化させてください。

プロンプト例1 — 構造化:

以下は新しいイベントパイプラインについて私が書き殴った

思考メモだ。これをデザインドック構造(要約/背景/ゴール/

設計/代替案/リスク)に再配列せよ。ただし内容を捏造するな。

メモにない部分は [TODO: 作成者の入力が必要] と表示せよ。

[メモを貼り付け]

2. **批判の依頼 — 最も過小評価されている使い方**: AIはドラフト作成より敵対的レビューでより大きな価値を発揮します。

プロンプト例2 — 敵対的レビュー:

あなたはこのデザインドックを却下させようとする厳しい

スタッフエンジニアだ。次の観点から最も痛い質問を5つ作れ:

1) 定量的根拠のない主張 2) 検討されていない障害シナリオ

3) 非ゴールに隠れたスコープリスク 4) 代替案比較の偏向

各質問について、ドキュメントのどこを直せば防御できるかも

提示せよ。

3. **読者シミュレーション**: 「このドキュメントをインフラの文脈を持たない新人バックエンドエンジニアが読むと仮定し、理解が詰まる地点を順に列挙せよ」のような依頼は、リハーサル2回目の読者を代替してくれます。

限界も明確です。第一に、**決定は委任できません。** AIは代替案を列挙しトレードオフを整理してくれますが、重みを決めるのは組織のコンテキスト(チームの力量、政治、予算)を知る人の仕事です。第二に、**もっともらしさの罠**があります。AIが書いたドキュメントは文章が滑らかなのでレビューを通過しやすいですが、滑らかさと正確さは無関係です。数字、リンク、システム名は必ず人が検証しなければなりません。第三に、自分の考えがない状態でAIドラフトから始めると**アンカリング**されます。白紙の思考10分が先、AIはその後です。

ライティング訓練ルーティン

書くことは筋肉なので、ルーティンがすべてです。負担の少ない順に提案します。

1. **週1回、決定ひとつをADRに** (15分): 最もコスパの良い訓練です。形式が決まっているので白紙の恐怖がありません。

2. **PR説明を3段落構造で** (毎回5分): 何を/なぜ/どう検証したか。PR説明は最も頻繁に書くテクニカルライティングです。

3. **他人のデザインドックにコメントする** (週30分): 書く前に読む。良いドキュメントに出会ったら「なぜ読みやすかったのか」を一行メモしてください。

4. **四半期に1回、フルサイズのデザインドック** (半日): 実戦。上のルーティンが積み重なっていれば、思ったより楽に書けます。

5. **要約訓練** (随時): 読んだ技術記事を3文に要約してチームチャンネルに共有します。圧縮こそテクニカルライティングの核心の筋肉です。

ポストモーテムとランブック — ミニテンプレート

デザインドックとADRの次によく書くことになる2つの形式も、骨格を用意しておけば作成時間が半分に減ります。

ポストモーテムは「非難なし(blameless)」の原則が形式より重要ですが、形式が原則を守ってくれます。人の名前ではなく役割とシステムを主語に書かせるテンプレートが、その装置です。

ポストモーテム: 注文API障害 (2026-06-08)

深刻度: SEV-2 | 影響: 23分間で注文作成失敗約1,200件

作成: オンコールエンジニア | レビュー: チーム全体 (6/10会議)

タイムライン (すべてKST)

- 14:02 デプロイ完了 (PR 1077)

- 14:05 エラー率アラーム発火

- 14:11 オンコールがデプロイとの関連を確認、ロールバック開始

- 14:25 エラー率正常化

根本原因

コネクションプール設定が環境変数の欠落でデフォルト値(5)に

落ちた。ステージングはトラフィックが低く再現されなかった。

良かったこと / 悔やまれること

- (+) アラームからロールバック決定まで9分

- (-) 環境変数の検証がデプロイパイプラインになかった

アクションアイテム (担当/期限必須)

- 必須環境変数のスキーマ検証を追加 — A, 6/15, INFRA-310

- ステージング負荷テストの定期化 — B, 6/22, PERF-20

ランブックは「深夜3時の自分」が読者だということだけ覚えておけば十分です。判断を要求せず、コピーして貼り付けられるコマンドと期待される出力を書きます。

ランブック: 注文イベントコンシューマの再起動

いつ使うか: コンシューマラグのアラーム (指標リンク) が10分以上続く時

1. 現在のラグを確認 (期待値: 正常時1,000未満)

kubectl exec -it consumer-0 -- ./check-lag.sh

2. コンシューマを再起動

kubectl rollout restart deployment/order-consumer

3. 5分後にラグを再確認。減らなければ → エスカレーション: データチームのオンコール

注意: 絶対にパーティションリセットコマンドを先に実行しないこと (データ損失)

レビューコメントに答える技術

ドキュメントを書く技術の半分は、コメントに答える技術です。よく書かれたドキュメントがコメント対応で崩れるケースをよく見ます。原則は5つです。

1. **すべてのコメントに答える**: 無視されたコメントひとつが、レビュアー全体の参加意欲をくじきます。反映しない場合でも「反映しない理由」を書きます。

2. **受け入れは速く、反論は丁寧に**: 正しい指摘は「良い指摘です、セクション4に反映しました(diffリンク)」で即座に処理します。同意できなければ根拠を挙げて答えますが、2往復しても平行線なら文書の外(通話)に持ち出します。

3. **コメントをドキュメント改善に還元する**: レビュアーが混乱したなら、それ自体がドキュメントの欠陥です。「コメントで説明したからいい」ではなく本文を直します。次の読者はコメントスレッドを読みません。

4. **決定権限を曖昧にしない**: すべてのコメントを多数決で処理するとドキュメントはラクダになります。「ご意見ありがとうございます。トレードオフを検討した結果、原案を維持します。根拠はXです」と言えなければなりません。

5. **レビュー終了を宣言する**: 反映が終わったら「コメント反映完了、状態を承認済みに変更します」と明示的に知らせます。終わらないドキュメントは信頼を失います。

事例 — ドキュメント1枚が会議5回を減らした話

具体的なイメージのために、架空の(しかしよくある)シナリオをひとつ見てみます。決済モジュールの分離をめぐって、バックエンド、インフラ、PMが3週間で5回の会議をしましたが結論が出ませんでした。毎回同じ論争が繰り返されたのですが、参加者が少しずつ違ったため、前回の会議の合意が次の会議で無効になっていたからです。

6回目の会議の代わりに、ひとりがデザインドックを書きました。代替案3つを比較テーブルに整理し、各チームの懸念を「オープンクエスチョン」として明示し、コメント期限を1週間に設定しました。結果: コメント19件、非同期での合意到達、会議は最終決定の30分1回で終わりました。ドキュメントがやったことは魔法ではありません。**論争の状態を保存したこと**です。会議は揮発性メモリなので毎回最初から計算し直していましたが、ドキュメントはディスクなので続きから計算できた、それだけのことです。

文章レベルのルール — クイック校正ガイド

構造が固まったら、次は文章です。テクニカルライティングで即効性のある文章ルール7つを、校正例とともにまとめます。

1. **受動態を能動態に**: 「決定された」→「バックエンドチームが決定した」。主語のない文は責任のない文です。

2. **二重否定の禁止**: 「不可能ではない」→「可能だ」。読者のパースコストを減らしてください。

3. **一文一主張**: 接続詞でつながった3行の文は3つの文に切ります。技術文書の文は短めが読みやすいのです。

4. **形容詞の代わりに数字**: 「大幅な改善」→「p99基準で62パーセントの改善」。数字がなければ、その主張はまだ検証されていません。

5. **代名詞の追放**: 「これ」「その方式」は2段落も過ぎれば何を指すのか誰にもわかりません。面倒でも名詞を繰り返してください。

6. **略語は初出で展開する**: チーム内部の略語は、新入社員と6ヶ月後の自分には外国語です。

7. **不確実性を正直に表記する**: 「たぶん大丈夫だろう」のような曖昧なヘッジの代わりに、「未測定。6月20日のベンチマーク後に確定」のように不確実性の解消時点を書きます。

これらのルールは校正段階で機械的に適用できるので、AIレビュープロンプトに「上の7つのルール違反を探せ」と入れれば、自己校正ループが作れます。

副次効果 — ドキュメントはオンボーディング資産だ

ドキュメント文化の最も過小評価されているリターンはオンボーディングです。デザインドックとADRが蓄積されたチームの新メンバーは、「なぜこう作られたのか」の歴史を時系列で読むことができます。これはコードツアー10回より速いコンテキストの伝授です。

実践のコツは3つです。

1. **オンボーディング読書リスト**: ADRディレクトリから核心の決定10個を選び、「入社初週の読書リスト」として用意しておきます。作るのに10分、新メンバーごとに数日を節約してくれます。

2. **新メンバーをドキュメントテスターに**: 入社者がドキュメントを読んで詰まった地点を記録してもらえば、ドキュメントの欠陥マップがタダで作れます。「ここで詰まりました」は最高のドキュメントレビューです。

3. **最初の貢献をドキュメントで**: 最初の週にコードの代わりに「オンボーディングで発見したドキュメント改善PR」を出してもらえば、心理的負担なしに貢献サイクルを始められます。

落とし穴と反論

バランスのために、ドキュメント文化の暗い面も扱います。

**「ドキュメントが仕事を代替する組織」**は実在する病弊です。デザインドックの承認に6週間かかり、肝心の実装のエネルギーが残らない組織、ドキュメント作成自体が成果となり誰も読まないドキュメントが積み上がる組織があります。ドキュメントは決定を速くするための道具であって、決定を先送りする儀式ではありません。「このドキュメントがなければ何がまずいのか?」に答えられないなら、書かないでください。

**「コードこそドキュメントだ」**という反論にも一理あります。コードとドキュメントが食い違えばドキュメントは嘘になり、嘘をつくドキュメントはない方がましです。対応原則は寿命の分離です。「なぜ」を扱うドキュメント(ADR、デザインドック)は決定時点のスナップショットなので、コードと食い違っても価値が維持されます。「どうやって」を扱うドキュメント(ランブック、APIドキュメント)はコードの近くに(できれば同じレポジトリに)置き、コードレビューで一緒に更新すべきです。

最後に、**文章能力主義の影**です。ドキュメント文化の強い組織では、文章が流暢な人の意見が過大に代表されることがあります。特に非ネイティブが混ざるグローバルチームで実在する問題です。文章の華麗さではなく論拠の品質で評価するレビュー規範、そしてAIライティング補助の積極的な許容が現実的な補完策です。

チェックリスト

デザインドック発行前:

1. 要約3文だけ読んでも何を/なぜ/どうやってがつかめるか

2. すべての「遅い/多い/難しい」に数字が付いているか

3. 非ゴールのセクションがあるか

4. 代替案比較テーブルに却下された案の長所が書かれているか

5. オープンクエスチョンが正直に列挙されているか

6. レビュー依頼にスコープと期限が明示されているか

7. 想定読了時間が10分を超えるなら、削れないか

ADR発行前:

1. コンテキストに当時の制約(人員、時間、技術)が含まれているか

2. 帰結に短所(受け入れるもの)が最低ひとつあるか

3. 再検討トリガーが明示されているか

4. 1ページを超えていないか

おわりに

コードはコンピュータを説得し、ドキュメントは人を説得します。そして2026年には、ドキュメントがAIを通じてコードまで作り出します。書くことに費やす時間はコーディング時間を奪うコストではなく、コーディングの方向を定め、手戻りをなくす、最も利回りの高い投資です。

今週下した技術的決定がひとつあるなら、今日ADRを1枚残してみてください。15分で済みます。6ヶ月後の誰かが — もしかすると未来のあなた自身が — その1枚に感謝することになるでしょう。

参考資料

- Design Docs at Google (Malte Ubl): https://www.industrialempathy.com/posts/design-docs-at-google/

- ADR公式ホーム — Architectural Decision Records: https://adr.github.io/

- Michael Nygard — Documenting Architecture Decisions: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

- Google Technical Writing Courses: https://developers.google.com/tech-writing

- GeekNews — デザインドック関連の議論: https://news.hada.io/

- Hacker News — Design Docs at Google の議論: https://news.ycombinator.com/

- AWS — Architecture Decision Records ガイド: https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html

- GitHub — adr/madr テンプレートリポジトリ: https://github.com/adr/madr

- Anthropic — Claude Code メモリ(CLAUDE.md)ドキュメント: https://docs.anthropic.com/en/docs/claude-code/memory

- Write the Docs — テクニカルライティングのコミュニティとガイド: https://www.writethedocs.org/

- Diátaxis — ドキュメント類型分類フレームワーク: https://diataxis.fr/

- 37signals — Shape Up (ピッチドキュメントの書き方): https://basecamp.com/shapeup