describe-design

設計の説明

コードベースを調査し、機能やシステムの仕組みを説明するアーキテクチャ文書を作成します。出力は、人間の読者と将来の AI エージェントの両方に向けて構成された Markdown ファイルです。

ワークフロー

ステージ 1：対象範囲の定義

調査を始める前に、何を文書化するかを把握します。

1. 文書化する機能、システム、またはコンポーネントを尋ねます。
2. 対象読者（開発者、AI エージェント、またはその両方）を明確にします。
3. 文脈から明らかでない場合は、コードベースの場所を確認します。

ステージ 2：初期調査

コードベースを広く調査し、全体像を把握します。利用できる場合は、軽量で高速な調査方法を使います（たとえば、実行環境がサブエージェントに対応している場合は、高速な Explore サブエージェントを使用します）。

1. ディレクトリ構造を確認し、主要なエントリポイントを特定します。
2. README、設定ファイル、既存のドキュメントを読みます。
3. 対象機能に関連する主要なファイルとモジュールを特定します。
4. コードベースの構成について全体像を把握します。

ユーザーに概要レベルのアウトラインを提示します。

## Proposed Outline

1. [Component A] - Brief description
2. [Component B] - Brief description
3. [Component C] - Brief description

* Have I correctly captured the scope of the research? Reply "yes" to continue.
* Otherwise, please let me know what I've misunderstood.

ユーザーが対象範囲を確認したら、詳細な調査に進みます。

ステージ 3：詳細な調査

承認されたアウトラインの各コンポーネントについて、次の作業を行います。

1. エントリポイントからコードの実行経路をたどります。
2. コンポーネント間の依存関係と連携を特定します。
3. 設定オプションと、その定義場所を記録します。
4. データの保存場所や永続化の仕組みを確認します。
5. コード参照インデックス（ファイルパスと主要な関数名・クラス名）を作成します。

この情報の大部分は、初期のコード調査を活用して把握するようにします。必要に応じて追加のファイルを読みます。ステージ 2 で対象範囲が大幅に変わった場合は、2 つ目のコード調査サブエージェントを利用できます。

調査を終えるタイミング

次の条件を満たしたら、草案を作成できます。

• 正常系をたどれる — 典型的なリクエストや操作をエントリポイントから完了まで、抜けなく追えます。
• 境界を説明できる — 対象範囲と外部の要素を明確に説明できます。
• 図を描ける — プレースホルダーのボックスを使わずにアーキテクチャを描けます。
• 「何が何と通信するか」に答えられる — 各コンポーネントの入力と出力を把握しています。

まだ調査が終わっていないサイン：

• 不確かな点がある：「これは……とつながっていると思う」「おそらく……を呼び出している」
• 未解決の参照がある：調査していないモジュールへのインポートや呼び出しが見つかった
• つながりが不明：コンポーネント A から B にデータがどう渡るか説明できない

調査しすぎているサイン：

• 代表的なサンプルを調べるのではなく、ディレクトリ内のすべてのファイルを読む
• 外部ライブラリやフレームワークの内部にまで踏み込む
• アーキテクチャに影響しない実装の詳細まで調べる

ステージ 4：文書の草案

以下のテンプレートに従って文書を作成します。ユーザーに草案を提示してレビューを依頼し、フィードバックに基づいて修正します。利用できる場合は、AskUserQuestion ツールを使って、重要な決定事項についてユーザーに確認します。

ステージ 5：最終化

1. 書き込む前にファイルの場所を確認します。 リポジトリの慣例に基づいてパスを提案してもかまいません（例：docs/architecture/、ARCHITECTURE.md）。ただし、場所についてユーザーの明示的な確認を得ずに、ファイルを書き込んではいけません。ユーザーが事前にパスを指定している場合は、それを確認とみなします。
2. 確認済みの場所に最終文書を書き込みます。

文書テンプレート

以下のテンプレートを出発点として使用します。対象機能に合わせて調整し、該当しないセクションは省略し、特有の要素についてはセクションを追加し、対象読者に最適な構成に変更します。

# [Feature/System Name] Architecture

## Overview

[1-2 paragraph summary of what this feature/system does and why it exists]

## Architecture Diagram

```mermaid
flowchart TD
    A[Entry Point] --> B[Component]
    B --> C[Data Store]
```

## Components

### [Component Name]

**Purpose**: [What it does]

**Location**: `path/to/file.ext`

**Key Functions**:
- `functionName()` - Brief description
- `anotherFunction()` - Brief description

**Interactions**:
- Receives input from: [Component]
- Sends output to: [Component]

## Data Flow

[Description of how data moves through the system, from input to output]

## Configuration

[How features are enabled, disabled, or configured. Include file paths and
environment variables.]

## Code References

| Component | File | Key Symbols |
|-----------|------|-------------|
| Auth | `src/auth/index.ts` | `authenticate()`, `AuthConfig` |
| Cache | `src/cache/redis.ts` | `CacheManager`, `invalidate()` |

## Glossary

| Term | Definition |
|------|------------|
| [Term] | [Project-specific definition] |

コード参照の規則

リファクタリング後も有効な参照を使用します。

• パス：リポジトリのルートからの相対パスを使用します（src/auth/login.ts）。
• シンボル：行番号ではなく、関数名やクラス名を参照します。
• 形式：path/to/file.ext を使用し、主要なシンボルは別途記載します。
• アンカー：必要に応じて検索パターンを使用します（auth/ 内の handleAuth 関数）。

避けること：

• コードのコピー：コードをドキュメントに貼り付けないでください。コードはすぐに古くなります。ドキュメントは、読者をソースに案内するガイドにしてください。コードの処理を説明し、参照先を記載します。
• 行番号：編集のたびに変わります。
• 絶対パス：リポジトリ相対パスのみを使用します。

Mermaid 図

アーキテクチャを視覚化するには Mermaid を使用します。

コンポーネントの関係にはフローチャートを使用します。

flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
    C --> D[(Database)]

リクエストのフローにはシーケンス図を使用します。

sequenceDiagram
    Client->>API: Request
    API->>Service: Process
    Service-->>API: Response
    API-->>Client: Result

図は、ドキュメントで説明する特定の機能に焦点を当ててください。関係のないコンポーネントを詰め込みすぎないようにします。

執筆ガイドライン

• 説明し、コピーしない：コードの処理内容と参照先を説明します。実装の詳細が必要な読者は、常に最新の実際のソースを確認できます。
• ざっと見て把握できる構成にする：すばやく確認できるように、見出し、表、リストを使用します。
• 具体的にする：実際のファイルパス、関数名、設定キーを記載します。
• 2 種類の読者に対応する：人間にはわかりやすく、AI には一貫した構成で記述します。
• 最新の状態を保つ：コードの状態やバージョンに関する前提があれば明記します。