Exact Doc Writing

---
name: doc-writing
description: 開発ドキュメント（CLAUDE.md, docs/ 等）を作成・更新する際のベストプラクティス。
---

# 開発ドキュメント作成ガイドライン

開発ドキュメント（CLAUDE.md, docs/ 等のエージェント向けドキュメント）を作成・更新する際は、以下の原則に従う。

## 原則1: 実装をコピーしない

ドキュメントにソースコードをそのままコピーしてはならない。実装の詳細はコード自体が持つべきであり、ドキュメントに転記すると以下の問題が生じる:

- **陳腐化リスク**: コードが変更されてもドキュメントが更新されず、不整合が生じる
- **冗長性**: コードを読めばわかることを二重管理することになる
- **メンテナンスコスト**: 変更のたびにドキュメントとコードの両方を更新する必要が生じる

### 代わりにすべきこと

- アルゴリズムやアーキテクチャの **概要・意図・Why** を記述する
- 具体例や入出力例で振る舞いを説明する
- 実装の詳細はコードおよびテストへの参照で誘導する（例: 「詳細は実装とテストコードを参照してください。」）

## 原則2: コード側のコメントを充実させる

ドキュメントに実装を書く代わりに、コード自体のコメント（JSDoc等）を充実させることも検討する。LSPツールでコードを参照するだけで理解できる状態が理想。

- 各モジュール・関数・定数に対して、役割と意図を簡潔に記述する
- 非自明な設計判断やワークアラウンドには `NOTE:` コメントで理由を残す
- ドキュメントからはコードの場所（ファイルパス）を示し、参照を促す

## 原則3: 適切な抽象度で書く

ドキュメントは「コードを読まなくても全体像を把握できる」レベルで書く。

**書くべきもの:**
- アーキテクチャの全体像（レイヤー構成、コンポーネント間の関係）
- 処理フロー（リクエストライフサイクル等のシーケンス）
- 構成要素の一覧と各要素の役割（1行説明レベル）
- 設定・環境変数・外部依存の一覧
- 具体的な入出力例

**書くべきでないもの:**
- 関数の実装コード
- 変数の宣言や型定義の転記
- コードを読めば自明なロジックの詳細

## 原則4: 構造化された参照体系を維持する

ドキュメントは階層化し、各レベルで適切な詳細度を保つ。

```
CLAUDE.md（プロジェクトルート）
  → 全体概要、技術スタック、共通ルール
  → 各パッケージの CLAUDE.md への参照

packages/<pkg>/CLAUDE.md
  → パッケージの構成、主要な型、依存関係、開発コマンド
  → docs/ への参照

docs/<topic>.md
  → アーキテクチャ詳細、処理フロー、設計判断の背景
  → ソースコードへの参照
```

各レベルで情報を重複させず、より深い詳細は下位のドキュメントまたはコード自体に委譲する。