---

name: doc-writing description: DOCUMENTATION.md の方針に従って新規ドキュメントを作成する。パッケージ README、showcase README、docs/ のドキュメントを対象とする。

ドキュメント作成ガイド

意図

新しいドキュメントを docs/DOCUMENTATION.md の方針に従って作成する。 テンプレートに沿いつつ、読者が必要な情報を過不足なく提供する。

作成手順

1. ドキュメントの種類を特定

引数からどの種類のドキュメントを作成するか判断する:

種類	トリガー
パッケージ README	新パッケージの追加
Showcase README	新 showcase の追加
docs/ ドキュメント	新しいトピックの文書化

2. DOCUMENTATION.md のテンプレートを読む

docs/DOCUMENTATION.md を読み、該当するテンプレートを確認する。

3. 対象の理解

• パッケージ README: ソースコードの公開 API（index.ts の export）を読み、型定義を把握する
• Showcase README: example のソースコードを読み、使用している API と実装パターンを把握する
• docs/ ドキュメント: 対象トピックの範囲と想定読者を確認する

4. ドキュメント作成

パッケージ README

テンプレートに従い、以下の順序で作成:

1. タイトル + 1行説明: パッケージの役割を英語で簡潔に
2. Philosophy（基盤パッケージのみ）: 設計思想
3. Installation: pnpm add @ydant/<name>
4. Usage: 基本的な使用例。import から始まり、動作するコード例
5. API: 公開されている全関数・インターフェース・型
6. Module Structure（複数ファイルの場合）: ファイル名と役割

API セクション作成のルール:

• ソースコードの index.ts から export されているものを全てカバー
• 関数シグネチャは TypeScript のコードブロックで記述
• 説明文はパラメータの意味、戻り値、副作用を含む

Showcase README

テンプレートに従い、以下の順序で作成:

1. タイトル: # Showcase N: <名前> 形式
2. 機能: 箇条書きで 3〜4 項目
3. 実装のポイント: 躓きやすい箇所をコード例付きで 2〜4 個
4. 実行: pnpm run dev

「実装のポイント」作成のルール:

• API の使い方そのものはパッケージ README に委ねる
• この showcase 特有の躓きポイント、パターン、ベストプラクティスを記述
• ✅/❌ 形式で正しい/間違った使い方を対比するのは有効

docs/ ドキュメント

1. 既存の docs/ ファイルのどこにも収まらない情報か再確認
2. 想定読者を明確にする
3. 作成後、CLAUDE.md の Documentation Structure テーブルに追加
4. DOCUMENTATION.md の「ファイルと役割」テーブルにも追加

5. 関連ファイルの更新

ドキュメント作成後、以下を確認・更新する:

作成物	更新が必要なファイル
パッケージ README	ルート README（日英両方）の Packages テーブル
Showcase README	ルート README（日英両方）の Examples テーブル
docs/ ドキュメント	CLAUDE.md の Documentation Structure テーブル

6. レビュー

作成が完了したら /doc-review で品質をチェックする。

7. 方針へのフィードバック

作成中に以下のような摩擦があれば記録する:

• テンプレートの構造が対象に合わなかった箇所
• 配置ルールでは判断できなかった情報の種類
• テンプレートにないセクションを自然に追加した箇所

これらは DOCUMENTATION.md の方針を改善するためのシグナルである。 テンプレートを無理に守るよりも、摩擦を正直に残す方が方針の成長につながる。

現時点の方針

• テンプレートは基本に据える（パッケージ間の一貫性が品質を支える）
• ただし、テンプレートに収まらない場合は無理に合わせず、摩擦を記録して方針の見直しにつなげる
• パッケージの性質に応じたオプションセクション（Philosophy, Module Structure）の有無は判断
• 「書きすぎない」ことも重要。API の詳細はコードと JSDoc に委ね、README は概要とユースケースに集中

今後の検討事項

• パッケージ README の scaffolding コマンド
• showcase の初期テンプレートファイル生成
• JSDoc からの API セクション自動生成
• 作成時に記録された摩擦の蓄積と、テンプレート改善への反映フロー