Doc Writer

---
name: doc-writer
description: ドキュメント執筆をサポートするスキル。ユーザーがPRDに基づいてドキュメントを作成、編集、または更新したい場合に使用します。このスキルは、docs/prd.md に記載されたプロダクト要求仕様書を参照しながら、技術ドキュメント、設計ドキュメント、ユーザーガイド、APIドキュメントなどの執筆を支援します。「ドキュメントを書く」「仕様書を作成」「ガイドを作る」などのドキュメント作成タスクに言及した場合にトリガーします。
---

# ドキュメントライター

このスキルは、PRD（docs/prd.md）を参照しながらドキュメント執筆を支援します。

## 前提条件

- プロダクト要求仕様書（PRD）は `docs/prd.md` に集約されている
- PRD には、プロダクトの概要、機能要件、技術要件、用語定義などが記載されている

## 執筆ワークフロー

### 1. コンテキスト確認

ドキュメント作成を開始する前に以下を確認：

1. `docs/prd.md` を読み込み、プロダクトの全体像を把握する
2. ユーザーに以下を確認：
   - 作成するドキュメントの種類（技術仕様書、ユーザーガイド、API ドキュメントなど）
   - 対象読者（開発者、エンドユーザー、ステークホルダーなど）
   - ドキュメントの目的と期待される成果

### 2. ドキュメント種類と構成

#### 技術仕様書

```
# [機能名] 技術仕様書

## 概要
## 背景と目的
## 技術要件
## アーキテクチャ
## API 設計
## データモデル
## セキュリティ考慮事項
## テスト計画
## 制約事項
```

#### ユーザーガイド

```
# [プロダクト名] ユーザーガイド

## はじめに
## クイックスタート
## 基本的な使い方
## 機能詳細
## トラブルシューティング
## FAQ
```

#### API ドキュメント

```
# [API名] API リファレンス

## 概要
## 認証
## エンドポイント一覧
## リクエスト/レスポンス形式
## エラーコード
## 使用例
## レート制限
```

#### 設計ドキュメント

```
# [機能名] 設計ドキュメント

## 概要
## 問題定義
## 解決アプローチ
## 設計詳細
## 代替案の検討
## トレードオフ
## 実装計画
```

### 3. 執筆プロセス

#### ステップ 1: PRD との整合性確認

- `docs/prd.md` から関連するセクションを特定
- PRD に記載された用語定義（Glossary）を参照し、一貫した用語を使用
- PRD の機能要件と技術要件を正確に反映

#### ステップ 2: アウトライン作成

- ドキュメント種類に応じた構成を提案
- ユーザーと構成を確認・調整
- 各セクションの概要を箇条書きで整理

#### ステップ 3: セクションごとの執筆

各セクションについて：

1. PRD から関連情報を抽出
2. 対象読者に適した表現で記述
3. 必要に応じて図表やコード例を追加
4. ユーザーからのフィードバックを反映

#### ステップ 4: レビューと改善

- ドキュメント全体の一貫性を確認
- 用語の統一性をチェック
- 冗長な表現を削除
- リンクや参照の正確性を検証

### 4. 品質基準

#### 必須要件

- [ ] PRD との整合性が取れている
- [ ] 対象読者に適した表現を使用している
- [ ] 用語が PRD の定義と一致している
- [ ] 構造が論理的で読みやすい

#### 推奨事項

- [ ] 具体的な例やコードサンプルを含む
- [ ] 図表で複雑な概念を視覚化
- [ ] 関連ドキュメントへのリンクを記載
- [ ] 変更履歴を管理

### 5. ファイル命名規則

作成するドキュメントは以下の命名規則に従う：

- 技術仕様書: `docs/specs/[feature-name]-spec.md`
- ユーザーガイド: `docs/guides/[topic]-guide.md`
- API ドキュメント: `docs/api/[api-name]-api.md`
- 設計ドキュメント: `docs/design/[feature-name]-design.md`

## 執筆時の原則

### 簡潔さ

- 一文は短く、明確に
- 不要な修飾語を避ける
- 箇条書きを効果的に使用

### 具体性

- 抽象的な説明よりも具体例を優先
- 数値や具体的な条件を明記
- 曖昧な表現（「など」「〜的な」）を最小限に

### 一貫性

- PRD で定義された用語を使用
- 文体を統一（です・ます調 or である調）
- フォーマットを統一

### 読者視点

- 対象読者の前提知識を考慮
- 専門用語には説明を追加
- 読者が求める情報を優先して配置

## インタラクティブな執筆

ユーザーとの対話を通じてドキュメントを改善：

1. **明確化の質問**: 不明点があれば積極的に質問
2. **段階的な確認**: セクションごとにフィードバックを求める
3. **選択肢の提示**: 複数のアプローチがある場合は選択肢を提示
4. **改善提案**: より良い表現や構成があれば提案

## PRD 参照のベストプラクティス

- PRD の「Intro & Goal」セクションから背景情報を取得
- 「What is it?」セクションから機能詳細を参照
- 「Glossary」から正式な用語定義を使用
- 「Tech Notes」から技術的な制約を確認