意思決定 / オプション文書の品質基準
すべてのエンジニアリング上の意思決定、スパイク、または選択肢と推奨事項を提示するオプション文書に、これらのルールを適用してください。読み手は、前提知識がなく忙しいチームメイトです。文書は、読み飛ばしが可能で、平易で、証明可能である必要があります。
想定読者：前提知識なし
- 読者は、内部の暗黙知を一切知らないと想定してください。すべての用語、頭字語、サービス名、ツール、使用パターンについて説明を加えるか、ハイパーリンクを付けてください（例：CDC、Debezium、Kafka、SNS、SQS、Outbox、Logical Replication、Temporal）。「誰もこれが何を意味するか知らない」という前提です。
- 何かに言及する前に、それが何であり、何をするのかを平易な言葉で説明してください。専門用語だけではなく、平易なフレーズ＋リンクを優先してください。
- 依頼がない限り、独立した用語集セクションは追加しないでください。代わりに、インラインで用語にリンクを張ってください。
文体
- ポイントを先に述べてください（BLUF：結論ファースト）。詳細に入る前に、主要な結論を最初に提示してください。
- 短く。一行で済むものは段落にしないでください。セクションがテキストの壁のように見える場合は、切り詰めてください。長い文書は誰も読みません。
- 平易な言葉。AI生成のようなスラング、聞こえは良いが中身のない言葉、文書自身の進化の説明、文書内で自分の推論を擁護すること（例：「直接的な証拠であって理論ではありません」など）は禁止です。
- どの箇所にもemダッシュ（—）は使用しないでください。強調にALL-CAPS（すべて大文字）は使わず、太字を使用してください。機械生成的に見える装飾的な番号や中点区切りは使用しないでください。
- チームが行う作業には「私たち」を、著者の意見/傾向には「私は」を使用し、明確に区別してください。
構造
- 冒頭に推奨事項 / TL;DR を配置。 数行で：傾向、主な理由（箇条書き）、チームの意見を聞いて変更される生きた文書としての最初の見解として提示してください。実際に無関心だったり柔軟性がある場合はそれを明示しつつ、それでもなお好みとその理由を述べてください。
- 各オプションごとに折りたたみ可能なブロック（トグル）を1つずつ。 折りたたまれた行には、短いラベルと一行の平易な英語による概要を示してください。ブロック内：簡単な図、仕組み、再利用するもの（証拠へのリンク付き）、新規のもの、スケール/トレードオフ、小さなコードまたは設定のスケッチ。表面はスキャン可能に保ってください。
- 同じ階層のセクションは並列に（一貫性は必須）。 オプション/ツール/候補は兄弟関係にあるため、すべてのセクションは同じテンプレートに従う必要があります：同じサブセクション見出しを同じ順序で、図/メディア/コードスケッチの有無も同じ、同じ詳細度。テンプレートは最もしっかりしたセクションから一度決めて、すべてに適用してください。あるセクションを追加・編集する際は、他のセクションも再度調整してください。各セクションが独自の形状に漂流することを決して許さないでください。構造がバラバラだと手抜きに見え、比較が容易であるという目的全体が損なわれます。これは繰り返し発生する失敗パターンです。共有する前に確認してください。
- オプションは、単一の明確な軸でグループ化（例：いつ起こるか、または どのように）。2つの軸を1つのグループに混在させたり、重複する誤った同列カテゴリを作成しないでください。あるものが別のオプションの実装詳細（実行環境、配置場所など）である場合は、それを同列に列挙せずに、そのオプションの中に折り込んでください。
- 共有される/最も難しいコア部分を、オプションだけでなく図示し、独自のスケッチを用意してください（例：作成/更新 および 削除など、完全なライフサイクルを扱ってください）。
- 図（mermaid）を使用して説明。正確に保ってください（例：テーブルを別個のDBとして描画しないでください）。
- 最後はフィードバックを求めて終了（「他のアイデアは？」）。唐突に終わらないでください。
- メタデータは最小限に、必要なものだけ（多くの場合、チケットリンクのみ）。ステータスや著者が気にしない定型行は削除してください。
オプションの網羅性
- 通常の2～3つだけでなく、オプションを網羅的に列挙してください。実際の問題には多くの選択肢があります。明らかに悪いものも含め、全容が見えるようにしてください（それらは弱い/ベースラインとラベル付けしてください）。
- 「何もしない」ベースラインを常に認識し、その結果を記載してください。
- 実際の情報源（ドキュメント、Stack Overflow、Reddit、ベンダー/パターンリファレンス）を調査して、オプションと正しい用語を見つけてください。Wikipediaだけに頼るのは怠惰なデフォルトです。関連する一次情報源を見つけてください。
- 確立されたデザインパターンは正しく名前を付け、リンクを張ってください。パターン名を誤って適用しないでください。引用する前に、そのパターンが実際に適合することを確認してください。
証拠（最も重要なルール）
- システムが既に持っているものに関するすべての主張には、証拠へのハイパーリンク（ソースファイルと行、インフラ設定、チケット）を付けてください。仮定やごまかしは禁止です。
- 主張をリンクで証明できない場合は、事実として述べるのではなく、「未確認」とマークしてください。
- 実際のファイル/インフラを自分で読んで確認してください。サブエージェントの調査結果を自分の目で確認せずに事実として主張しないでください。「自分で読んだ」と「エージェントが報告した」を区別し、必要に応じて確信度を明記してください。
- 静かに意見を変えないでください。チェックによって以前の主張が変わった場合は、何が間違っていたか、なぜかを述べ、修正してください。
- 追求された場合、前提と自分の結論に疑問を投げかけ、守るのではなく再検証してください。
- すべての識別子、ファイル名、チケット、PR、参照にハイパーリンクを張ってください。読者に裸のIDを追跡させないでください。
オプション文書の内容
- 難しい共有コア部分（どのオプションを選んでも必要な作業）を、それを包むラッパー/メカニズムから分離し、どれが実際の労力とリスクかを示してください。
- 長所と短所を根拠に基づいて示してください。過大評価しないでください（例：「作業の大部分とほぼすべてのリスク」→正確な表現に和らげてください）。
- 各オプションが何を再利用するか（既に存在するもの）と、何が新規かを記載してください。
プロセス
- 最小限の、的を絞った編集を行ってください。小さな変更のために文書全体を書き直さないでください。
- 敏感な表現については、チャットで下書きを表示し、適用する前に反復してください。
- 付随するレビュー/Slackメッセージについては：非常に短く、心から歓迎する内容にしてください（みんな忙しく、読む気にならないでしょう）。緊急かどうかは尋ねられない限り述べないでください。レビュアーに最も有用な単一のフレーミングを提供してください。
最終確認
文書を共有する前に、以下を確認してください：
- 主要なポイント/推奨事項が冒頭にあり、短い。
- 「現在持っているもの」に関するすべての主張に証拠リンクがある。未確認の主張はラベル付けされている。
- 専門用語には説明があるかリンクが張られており、背景知識がない読者でも理解できる。
- オプションは単一の明確な軸でグループ化され、それぞれが折りたたみ可能で、平易な一行要約が付いている。
- emダッシュ、ALL-CAPSによる強調、自己言及、AI生成スラングがない。
- 「私たち」と「私は」が正しく使い分けられ、傾向は述べられているが柔軟性は明確にされている。
- 文書がフィードバックを促し、唐突に終わっていない。