architecture-md-builder

Architecture.md ビルダー

matklad の定める標準ガイドラインと、現代的な AI エージェント向けドキュメント作成パターンに従い、あらゆるコードベースの決定版となるマップとして、プロダクション品質の ARCHITECTURE.md ファイルを作成します。

このスキルを使う場面

• 新規または既存のリポジトリのアーキテクチャドキュメントを作成するとき
• コードベースを監査して、その構造を把握するとき
• 開発者や AI エージェント向けのオンボーディングドキュメントを作成するとき
• ユーザーから「アーキテクチャをドキュメント化して」「architecture.md を作成して」「このコードベースをマッピングして」と依頼されたとき

基本原則（matklad のガイドライン）

標準的な ARCHITECTURE.md は、以下の原則に従います。

1. 俯瞰的な概要 - 解決する課題と、概要レベルのアプローチ
2. 大まかなコードマップ - モジュールとその関係（州レベルではなく国レベル）
3. 名前の付いたエンティティ - 重要なファイル、型、モジュールを名前で記載（リンクは使わず、シンボル検索を利用）
4. アーキテクチャ上の不変条件 - 制約、行わないこと、存在しないパターン
5. レイヤーの境界 - システム間の移行点
6. 横断的な関心事 - 複数のモジュールにまたがる課題

詳しい説明は references/matklad-guidelines.md を参照してください。

ワークフロー

フェーズ 1：ベストプラクティスの調査（任意）

アーキテクチャドキュメントのパターンに詳しくない場合は、Exa 検索を使います。

# Search for exceptional architecture.md examples
python3 ~/.claude/skills/exa-search/scripts/exa_search.py \
  "architecture.md documentation best practices" \
  --category github -n 10

# Find matklad's original guidelines
python3 ~/.claude/skills/exa-search/scripts/exa_research.py \
  "matklad ARCHITECTURE.md guidelines rust-analyzer"

フェーズ 2：コードベースの調査

コードベースを徹底的にマッピングするため、2～4 個の調査エージェントを並行して起動します。

Use the Task tool with subagent_type=Explore for each major system area:

1. Core/Engine - Entry points, main abstractions, data structures
2. Transport/API - HTTP, WebSocket, message handling
3. Database/Persistence - Schema, migrations, queries
4. Frontend/UI - Components, state management, routing

エージェントへのプロンプトでは、次の点を尋ねます。

• 主な抽象化と型は何ですか？
• このシステム内でデータはどのように流れますか？
• 主なファイルと、その行数はどれくらいですか？
• 一貫して使われているパターンは何ですか？
• コードが適用している不変条件は何ですか？

目標とする出力： システム全体を網羅する、エージェントごとに約 10,000～15,000 語の分析。

フェーズ 3：ARCHITECTURE.md の草案作成

次の構成に従ってドキュメントを作成します。

# Architecture

Brief intro: what this document is for, who it's for.

## Bird's Eye View

- What problem does this solve?
- What is the core paradigm/approach?
- Key design principles (3-5 bullets)

[ASCII diagram showing major components]

## High-Level Data Flow

[Mermaid flowchart showing data flow]

## Codemap

### System 1 (`path/`)
Description, key files with line counts, key abstractions table.

### System 2 (`path/`)
...

## Architectural Invariants

Rules that are ALWAYS true. Code patterns that are NEVER violated.

## Cross-Cutting Concerns

Issues that span multiple modules (auth, logging, error handling).

## Layer Boundaries

Diagram showing layers and their interfaces.

## Key Files Reference

| File | Lines | Purpose |
|------|-------|---------|
| ... | ... | ... |

## Common Questions

FAQ format: "Where do I find X?" → Answer

セクションごとの詳しいガイダンスは references/document-structure.md を参照してください。 ひな形として assets/architecture-template.md を参照してください。

フェーズ 4：検証

正確性を確認するため、2～3 個のレビューエージェントを起動します。

Use the Task tool with subagent_type=Explore to verify:

1. General accuracy - Do descriptions match actual code?
2. Line counts - Are they roughly accurate?
3. File references - Do all referenced files exist?

検証チェックリスト：

• 参照されているファイルがすべて存在する
• 行数の推定が実際の行数の 20% 以内である
• ASCII/Mermaid 図が正しく表示される
• ドキュメントが「X を行うものはどこにあるか？」という問いに答えている
• 以前のバージョンから古い情報が残っていない

フェーズ 5：修正の適用

レビュー結果に基づいてドキュメントを更新します。

• 行数を修正する
• 構成に不足しているファイルを追加する
• 不正確な説明を修正する
• 件数を更新する（例：「11 個のモジュール」→「13 個のモジュール」）

品質ガイドライン

図

コンポーネント間の関係にはASCII 図を使います。

┌─────────────┐     ┌─────────────┐
│  Frontend   │────▶│   Backend   │
└─────────────┘     └─────────────┘

データフローにはMermaid 図を使います。

flowchart TB
    A[Input] --> B[Process]
    B --> C[Output]

行数

主要なファイルにはおおよその行数を記載します。

• 読者が複雑さの目安をつかむのに役立ちます
• wc -l を使って確認します
• 10 または 50 の単位に丸めます

名前の付いたエンティティ

ファイル、型、モジュールはリンクを使わず、名前で参照します。

• 良い例：「不変のメモリ実装については WorkingMemory.ts を参照してください」
• 悪い例：「WorkingMemory を参照してください」

理由：シンボル検索（Cmd+T、osgrep）のほうが、リンク切れを起こすリンクより信頼性が高いためです。

不変条件

コードが決して行わないことを記載します。

• 「WorkingMemory はインプレースで変更されません」
• 「API キーがブラウザーに渡ることはありません」
• 「すべてのデータベースクエリでプリペアドステートメントを使用します」

目標とする長さ

• 小規模プロジェクト：200～400 行
• 中規模プロジェクト：400～700 行
• 大規模プロジェクト：700～1000 行
• 最大：約 1200 行（それ以上になる場合は、リンク付きドキュメントに分割します）

出力

単一ファイル：プロジェクトのルートにある ARCHITECTURE.md

任意で、新しいアーキテクチャドキュメントへの参照を CLAUDE.md または README.md に追加します。

使用例

User: "Create an architecture.md for this repo"

1. Launch 3 exploration agents targeting core, transport, and frontend
2. Synthesize findings into ARCHITECTURE.md following the template
3. Launch 2 review agents to verify accuracy
4. Apply corrections
5. Commit and optionally update CLAUDE.md

リソース

• references/matklad-guidelines.md - 標準ガイドラインとその根拠
• references/document-structure.md - セクションごとの詳細なガイダンス
• assets/architecture-template.md - ひな形