architecture-md-writer

ARCHITECTURE.md の執筆

コントリビューターがシステムの構成、調査を始める場所、必ず守るべき制約をすばやく把握できるアーキテクチャドキュメントを作成します。実装の細部より安定した構成を優先し、対象範囲が適切でない場合を除き、新しいファイルを作成するより既存の ARCHITECTURE.md を編集してください。

ワークフロー

1. 対象範囲とドキュメントの構成を判断します。

• タスクの対象がリポジトリのルート、サブシステム、またはその両方かを確認します。
• ルートの ARCHITECTURE.md はシステムの全体図として扱い、百科事典のような完全な資料にはしません。
• 独立した構造、ライフサイクル、または制約を持つサブツリーに限り、独自のページを設ける理由がある場合に、ネストされた ARCHITECTURE.md ファイルを追加します。
• ネストされたドキュメントを追加する場合は、親ドキュメントからリンクし、その対象範囲を一行で説明します。
• アーキテクチャドキュメントを分割、統合、追加、削除するか判断する際は、ドキュメントの構成を変更する前に guides/document-topology.md を読んでください。

2. 安定したコード構造から背景情報を集めます。

• 既存のドキュメントは、境界、用語、意思決定の経緯を把握する目的に限って読みます。
• エントリーポイント、パッケージの境界、長期にわたり維持されるディレクトリ、インターフェース、バックグラウンドジョブ、ストレージの境界、外部連携を確認します。
• 重要なフローを1つか2つ選び、最初から最後まで追跡して、システムの実際の動きを反映させます。
• 文章を作成する前に、責務、相互作用、不変条件を把握します。

3. 役に立つ最小限のドキュメントを作成します。

• システムまたはモジュールの目的、主な構成要素、それらの連携方法を説明します。
• 網羅的な一覧より、具体的なファイルやディレクトリを調査の起点として示すことを優先します。
• 説明を短くできる場合に限り、小さな ASCII 図を使用します。Mermaid は使用しないでください。
• 固定的なテンプレートを押し付けず、システムに合ったセクション名を選びます。
• 新しいドキュメントを作成する場合、セクションを再編成する場合、またはコンポーネント、実行時のフロー、コードの経路、不変条件の示し方を選ぶ場合は、執筆前に guides/section-patterns.md を読んでください。

4. ドキュメントを高レベルで長く使える内容に保ちます。

• クラス単位、関数単位のカタログは省きます。
• 設計上の制約に関係する場合を除き、セットアップ手順、コーディング標準、運用手順書、チュートリアルは省きます。
• 長い意思決定の記録を本文に埋め込む代わりに、根拠やトレードオフの経緯については ADR へリンクします。
• 不明瞭な箇所は推測せず、説明を控えて、最適な調査開始用ファイルを示します。

5. コントリビューターにとって役立つ内容か確認します。

• 新しいエンジニアが、主な構成要素は何か、動作の調査をどこから始めるべきか、何を壊してはいけないかを把握できるようにします。
• 通常のリファクタリングで古くなるような記述を削除します。
• 既存のドキュメントを更新する場合は、残すすべての記述を現在のコードと照合し、正しくなくなったものは修正または削除します。
• リンク、ファイルパス、親子間のアーキテクチャドキュメントへの参照を検証します。
• 読者がドキュメントからコードを探せるよう、リポジトリ内の用語を維持します。

執筆ルール

• 短い段落と階層の浅い箇条書きを優先します。
• 外側から内側へ、まずシステムの構成を示し、次に最も重要なフローとファイルを説明します。
• start here ファイルを明示します。
• 不変条件は、曖昧な価値観ではなく、強制可能なルールとして記述します。
• モジュールのドキュメントがある場合は、親アーキテクチャにおける位置づけを示し、親ドキュメントへのリンクを付けます。
• ADR が存在しない場合は、その事実を簡潔に記すだけにし、根拠を作り上げないでください。
• 物語調の冗長な記述より、検索しやすい見出しと具体的なパスを優先します。