AIでアーキテクチャ文書を書く方法：6セクションのテンプレート、AIが役立つ場所、制約をでっち上げる場所

アーキテクチャ文書は何のためにあるか

次の人のために1つの問いに答えます。なぜシステムはこの形なのか？ 運用方法ではなく（それはランブック）、ユーザーに何をするかでもなく（それはPRD）、どの部品が存在し、その間をデータがどう動き、どの選択が偶然ではなく意図的に行われたかです。

読者は半年後に加わるエンジニア、あるいは長い休みの後のあなたです。10分で読めない文書は読まれません。2ページ、図1枚、決定の表1つ。

6セクションのテンプレート

「下書き担当」の列がこの記事の要点です。テンプレート自体は平凡で、分業こそがAIを危険ではなく有用にします。

コンテキスト

2文とリンク1つ。与えられた文書を要約する作業なので、エージェントはうまくやります。今日存在するものを名指しさせてください。「リマインダーは存在しない。カレンダー同期とメール送信は存在する」。

制約

設計が守らなければならない硬い制限です。「顧客データはEUリージョンに留める」「メールプロバイダーは毎分100通に制限」「エンジニア2人、1サイクル」「来四半期に置き換える同期レイヤーは変更しない」。

このセクションはエージェントが文書を見る前に自分で書いてください。制約の下書きを頼まれたエージェントはもっともらしいものを出します。「同時1万ユーザーに対応」「水平スケール可能」「マルチリージョンのフェイルオーバーに対応」。どれもあなたのものではありません。文書に入った瞬間、コンポーネントのセクションはそれらに合わせて設計され、1日40通のメールを送る機能のためにキュー、キャッシュ、バックアップリージョンができあがります。

コンポーネント

エージェントの初稿は通常、触る部品の妥当な一覧です。あなたの仕事は削ることです。発明された制約を満たすために追加されたコンポーネントを除き、意図的に手を付けない部分に「触らない：X、Y」の行を加えます。レビュー担当者にとっては、触る一覧より「触らない」一覧のほうが役に立ちます。

データフロー

番号付きの手順です。「1. 毎時0分にcronが起動。2. 送信済みフラグのない24時間以内の予約を取得。3. テンプレートを描画。4. プロバイダー経由で送信。5. 送信済みにする」。エージェントがPRDとコンポーネントから下書きし、あなたが各手順を既存のコードと照合します。バグの大半は手順2にあり、予約テーブルに論理削除の列があることをエージェントは知りません。

決定

後で誰かが疑問に思いそうな選択ごとに1行：選択肢、採用、理由。エージェントは思いつかなかった選択肢を並べるのが得意で、選ぶのは苦手です。あなたのチームや経緯を知らないからです。代替案を求め、「採用」と「理由」のセルは自分で書きます。3〜6行が普通です。12行あるなら、その文書は2つの機能を扱っています。

リスク

エージェントは15個挙げます。5つに絞り、それぞれに1行の緩和策を付けます。緩和策のないリスクは心配事であってリスクではありません。

AIが役立つ場所と害になる場所

役立つ：

• PRDからのコンテキスト、コンポーネント、データフローの初稿。 文書を読んで構造的に言い直す作業で、これは得意です。
• 各決定の下の代替案。 「他に何ができるか？」は、考えていなかった選択肢を確実に1つ出します。
• 整合性チェック。 「データフローのすべてのコンポーネントがコンポーネントのセクションに現れているか？」は、疲れた人の見落としを捕まえます。
• リスクのブレインストーミング。 刈り込むなら。

害になる：

• 制約。 発明され、もっともらしく、設計を左右します。上述のとおり。
• 選択肢からの選択。 期限を抱えた2人チームに合うものではなく、教科書的な答えを選びます。
• 現状についての主張。 「既存の同期レイヤーはwebhookを公開している」が実際は違う。エージェントが今日のシステムについて言うことはすべてコードと照合する必要があります。
• 規模。 放っておくと、あなたの規模ではなく学習データの規模に合わせて設計します。

私たちのルール：エージェントは与えられた入力を言い直すものなら何でも書いてよい。世界についての事実や選択は人が書く。

Atrixでのやり方

私たちのAIエージェントは、与えたブリーフとPRDから、Develop実行の3つの成果物の1つとして要件と計画済みissueと並んでアーキテクチャ文書を生成します。上の分業に従うのは、そうブリーフしているからです。実行のブリーフは制約を入力として名指しし、エージェントには追加しないよう指示します。文書はDocsのページとして保存され、版履歴、コメント、ライブ共同編集があるので、コンポーネントと決定に対するエンジニアの編集はエージェントの下書きとの差分として見えます。

ブロック図はページ内のホワイトボードに描きます。AtrixのホワイトボードはExcalidrawのボードで、箱と矢印を手で描き、描いたものはテキストの隣で編集可能なまま残ります。テキストから図を生成する機能はありません。エージェントに図を作らせたいなら、番号付きのデータフローを出させてそれを元に描いてください。6コンポーネントの機能なら10分ほどです。MiroのAIやEraserのDiagramGPTのようにテキストから図を生成するツールは別の記事で扱います。

実例（抜粋）

コンテキスト：予約リマインダー。PRD v3。今日リマインダーは存在せず、カレンダー同期とメール送信は存在する。

制約（人）：同期レイヤーは変更しない。プロバイダー上限は毎分100通。エンジニア1人、1サイクル。データはEUのみ。

コンポーネント（エージェントが下書き、人が削った）：リマインダースケジューラ（新規）、リマインダーテンプレート（新規）、予約クエリ（既存、読み取りのみ）、メール送信（既存）。触らない：同期レイヤー、カレンダーUI。

データフロー：先に挙げた5手順。手順2はテーブルを確認した上で論理削除された予約を除外するよう修正。

決定：cronかキューか（cron。1日40通で、キューは運用すべき2つ目のシステムになる）。予約ごとかバッチ送信か（バッチ。プロバイダー上限内に収めるため）。テンプレートの保存先（Docsのページ。新しいテーブルではない）。

リスク：cronの重複による二重送信（緩和：送信前に送信済みフラグを書く）。プロバイダー障害（緩和：翌時間に再試行、1時間未満はアラートなし）。タイムゾーンの誤り（緩和：UTCで保存・比較し、予約のゾーンで描画）。

エージェントの下書きは、自分で書いたスケーラビリティ制約を満たすためにRedisキューと「通知サービス」を追加していました。どちらも削り、文書は1ページ半に収まりました。

よくある質問

アーキテクチャ文書には何を含めるべきですか？

6セクションです。コンテキスト、制約、コンポーネント（触るものと触らないもの）、番号付き手順のデータフロー、選択肢と理由を含む決定の表、緩和策付きのリスク5つ。目標は2ページと図1枚です。

AIはソフトウェアのアーキテクチャ文書を書けますか？

PRDからコンテキスト、コンポーネント、データフロー、代替案を下書きでき、それはうまくやります。制約を書いたり決定を下したりすべきではありません。制約を発明し、教科書的な選択肢を選ぶからです。すべての事実と選択に人の責任者を置いた下書きツールとして扱ってください。

アーキテクチャ文書とADRの違いは何ですか？

アーキテクチャ決定記録（ADR）は1つの決定を扱います。コンテキスト、選択肢、選択、帰結。機能のアーキテクチャ文書は表に複数の決定を持ち、その周りにコンポーネントとデータフローがあります。小さなチームは通常、表を文書内に置き、複数の機能に影響する行だけを独立したADRに昇格させます。

アーキテクチャ文書の長さはどれくらいが適切ですか？

2ページ、10分で読める長さ。それより長ければ2つの機能を扱っているか、ランブックを吸収しています。運用の詳細は外に出してください。

アーキテクチャ文書に図を含めるべきですか？

はい。主要なデータフローを矢印で示したコンポーネントのブロック図を1枚。番号付きデータフローから手で描いてください。10分で済み、描く行為そのものが抜けている矢印を見つけます。

アーキテクチャ文書はいつ書くべきですか？

PRDを凍結した後、issueを作る前です。コンポーネントのセクションが作業の分割を決めるからです。issueができてから書くと、それは行ったことの記述になり、別の文書です。

次のステップ

今取り組んでいる機能について、制約セクションを5分で手書きし、PRDとその制約を使っているエージェントに渡して残りの5セクションを求めてください。PRDテンプレートはエージェントが必要とする番号付き要件を与え、AtrixではAIエージェントのDevelop実行がアーキテクチャ文書をチームで編集できるページとして返します。