architecture-md

ARCHITECTURE.md ジェネレーター

コードベースの全体像を新規参加者がつかめる、高品質な ARCHITECTURE.md ファイルを生成します。 matklad の記事に基づいています。最大の貢献者のボトルネックはコードを書くことではなく、どこを変更すればよいかを見極めることです。ARCHITECTURE.md はそのギャップを埋めます。

基本原則

1. 短く、安定させる -- 頻繁に変わる可能性の低いことだけを記述します。コードと同期させる必要はありません。年に数回見直します。
2. まずは俯瞰する -- 解決策ではなく、解決しようとしている課題から始めます。
3. 説明文よりコードマップ -- すべてのモジュールについて、「X を実行するものはどこか？」と「これは何をするものか？」に答えます。
4. リンクではなく名前を挙げる -- 重要なファイル、モジュール、型の名前を挙げます。ハイパーリンクは付けません（リンクは古くなるためです）。シンボル検索を促します。
5. 不変条件は重要です -- 意図的に存在しないものを明確に示します。重要な不変条件は、存在しないものとして表れることが多く、コードを読むだけでは推測できません。
6. 境界を示す -- レイヤー間の API 境界は、その背後にあるあらゆる実装を制約します。コードを手当たり次第に読んで境界を見つけるのは困難です。
7. 横断的な関心事は最後に扱う -- コードマップの後に、あらゆる場所に関係し、特定の場所には属さない事項（エラー処理、テスト、設定）を説明します。

ワークフロー

ステップ 1：コードベースを調査する

tree、glob、読み取りツールを使って、プロジェクトを把握します。

• README、package.json/Cargo.toml/pyproject.toml を読み、プロジェクトの目的を確認します
• tree -L 2 -d（または同様のコマンド）を実行して、ディレクトリー構造を確認します
• エントリーポイント（main ファイル、index ファイル、bin ディレクトリー）を特定します
• モジュール境界にある主要なファイルを読み、レイヤーを把握します

ステップ 2：アーキテクチャを特定する

次の項目を整理します。

• 解決する課題 -- このプロジェクトは何をしますか？入力と出力は何ですか？
• 大まかなモジュール -- 各トップレベルディレクトリー／パッケージは何をしますか？
• データフロー -- システム内でデータはどのように流れますか？入力 -> ？？？ -> 出力
• API 境界 -- どのモジュールが公開インターフェースで、どれが内部実装ですか？
• アーキテクチャ上の不変条件 -- 構造によってどのようなルールが適用されますか？意図的に存在しないものは何ですか？
• 横断的な関心事 -- エラー処理、テスト戦略、設定、オブザーバビリティ

ステップ 3：ARCHITECTURE.md を作成する

以下のテンプレートに従います。ほとんどのプロジェクトでは、ドキュメント全体を約 300 行以内に収めます。

テンプレート

# Architecture

[One paragraph: what this project does at the highest level. What problem it solves.]

## Bird's Eye View

[How data flows through the system at the coarsest level.
Input -> Processing stages -> Output.
Keep this to 1-3 paragraphs.]

## Code Map

[Brief intro: "This section describes the high-level structure of the codebase.
Pay attention to **Boundary** and **Invariant** callouts."]

### `path/to/module-a/`

[What this module does in 1-3 sentences. Key types: `ImportantType`, `AnotherType`.]

**Boundary:** [If this is an API boundary, say so and what it means.]

**Invariant:** [What's deliberately absent or enforced. E.g., "This module never does I/O"
or "Nothing here depends on the HTTP layer."]

### `path/to/module-b/`

[Repeat for each significant module.]

### `path/to/module-c/`

[...]

## Cross-Cutting Concerns

### Error Handling

[How errors are handled across the codebase. Is it Result-based? Exceptions?
Do errors propagate or get caught at boundaries?]

### Testing

[Testing strategy. Where do tests live? What kinds of tests exist?
What are the important test boundaries?]

### [Other concerns as applicable]

[Configuration, observability/logging, code generation, build system, etc.
Only include sections that are genuinely cross-cutting.]

ルール

含める内容

• ディレクトリー／モジュールの役割（それぞれ 1～3 文）
• 重要な型、トレイト、インターフェース、関数の名前（シンボル検索用）
• レイヤー間の API 境界
• アーキテクチャ上の不変条件 -- 特に意図的に存在しないもの
• システムレベルのデータフロー
• 複数のモジュールに影響する横断的な関心事

省略する内容

• 個々のモジュールの実装詳細（これはインラインドキュメントに記載します）
• 特定のファイルや行へのリンク（古くなるためです）
• 通常の PR で変わること
• 網羅的な API ドキュメント（これは rustdoc/typedoc/javadoc の領域です）
• セットアップ手順（これは README に記載します）
• コントリビューションガイドライン（これは CONTRIBUTING.md に記載します）

スタイルルール

• コードマップには、バッククォートで囲んだパスを使った ### \path/to/module/`` 形式の見出しを使用します
• Boundary: と Invariant: を先頭に付けた注記を使用します（太字のラベルで、引用ブロックにはしません）
• モジュールの説明は 1～3 文に収めます
• 型の名前はバッククォートで囲みます：「主要な型：FooBar、BazQux」
• 現在形かつ能動態で書きます
• 抽象的な表現より具体的な表現を選びます：「入力処理を扱う」ではなく「CLI 引数を解析する」

品質チェックリスト

仕上げる前に、以下を確認してください。

• 新しい参加者は、このドキュメントだけで「X を実行するもの」を見つけられますか？
• API の境界は明確に示されていますか？
• アーキテクチャ上の不変条件（特に、存在しないもの）は明記されていますか？
• 各セクションは、更新なしで 6 か月間維持できるほど安定していますか？
• 重要な型やモジュールは、リンクではなく名前が記載されていますか？
• コードマップの前に、全体像が示されていますか？
• 横断的な関心事は扱われていますか？
• コードマップの順序は、データフローまたは依存関係の方向と一致していますか？
• 約 300 行未満ですか？（短いほど読まれ、保守されやすくなります）

参考例

すべてのパターンを示す、架空の TypeScript プロジェクト向けの完全な ARCHITECTURE.md の例については、references/example.md を参照してください。