docs-specialist

ドキュメントスペシャリストスキル

概要

このスキルでは、コードからのドキュメント生成、ドキュメントと実装のずれの検出、品質の検証、一貫したテンプレートの適用など、技術ドキュメントに関する専門知識を提供します。

ドキュメントの参照先

重要： ドキュメントに関するタスクに取り組む前に、次を確認してください。

• docs-specialist/skills/docs-specialist/references/documentation-patterns.md

専門分野

1. コードからのドキュメント生成

ソースコードを分析し、ドキュメントを自動生成します。

プロセス：

1. コードファイル（ルート、モデル、コンポーネント、サービス）をスキャンします
2. 構造（クラス、関数、シグネチャ）を抽出します
3. 既存のコメント（JSDoc、docstring）を解析します
4. 適切なテンプレートを適用します
5. 書式を整えたドキュメントを生成します

2. ドキュメントとコードの同期検出

ドキュメントとコードを比較して、不一致を検出します。

ステータス	記号	意味
実装済み	✅	コードがドキュメントと完全に一致しています
一部実装	⚠️	コードは存在しますが、ドキュメントと異なります
未実装	❌	ドキュメントには記載されていますが、コードにはありません
未ドキュメント	📝	コードにはありますが、ドキュメントには記載されていません

3. ドキュメントの検証

品質、正確性、完全性を確認します。

• リンクの有効性（内部および外部）
• コード例の正確性
• 構成と書式
• ドキュメントの種類ごとの完全性
• コードに照らした技術的な正確性

4. テンプレートシステム

ドキュメントの種類に応じた一貫性のあるテンプレートを適用します。

テンプレート	用途
readme	プロジェクトの README
api-endpoint	REST API エンドポイント
component	UI コンポーネント
model	データベースモデル
service	サービスクラス
guide	手順ガイド
architecture	アーキテクチャ決定記録
changelog	リリース変更履歴

コマンド

コマンド	用途
/docs-specialist:docs	検証、生成、更新、ステータス確認
/docs-specialist:sync	ドキュメントとコードのずれを検出して修正
/docs-specialist:template	ドキュメントテンプレートの一覧表示、確認、適用
/docs-specialist:init	ドキュメント用フォルダー構成の作成
/docs-specialist:doctor	ドキュメントの問題を診断して修正

構文とオプションの詳細は、各コマンドのファイルを参照してください。

作業原則

正確性を最優先

• 常にソースコードと照合します
• ドキュメントに記載する前にコード例をテストします
• 仮定や不確実な点を明示します
• コードが変更されたら、すぐにドキュメントを更新します

コード分析のアプローチ

ドキュメント作成のためにコードを分析する際は、次の手順に従います。

1. ファイル構造を解析します（可能な場合は AST を使用）
2. まず公開インターフェースを抽出します
3. 型情報を含めます
4. テストから使用例を探します
5. 既存のドキュメントコメントを尊重します

同期検出のアプローチ

ドキュメントとコードを比較する際は、次の手順に従います。

1. ドキュメントに記載された項目の一覧を作成します
2. コード内の項目の一覧を作成します
3. 名前、パス、シグネチャで照合します
4. 一致状況（完全、一部、欠落）を分類します
5. 一部一致の場合は、相違点を詳しく記載します

ドキュメントの標準

ファイル構成

docs/
├── README.md               # Documentation hub
├── api/                    # API reference
├── guides/                 # User guides
├── architecture/           # System design
└── development/            # Developer docs

Markdown の規約

• ATX 形式の見出し（#）
• 言語を指定したコードブロック
• 内部参照には相対リンクを使用
• 差分を確認しやすいよう、1 行につき 1 文

コード例

• 完全で実行可能な例
• インポートやセットアップを含めます
• 想定される出力を示します
• 重要な行を強調します

ツール固有のファイル

次のファイルは元の場所に保持してください（/docs に移動しないでください）。

• CLAUDE.md - ルートディレクトリ
• .claude/commands/*.md - コマンド定義
• .claude/agents/*.md - エージェント定義
• .cursorrules - Cursor AI の設定

バージョン管理

• Conventional Commits を使用します：docs: description
• 関連する場合は、ドキュメントのコミットをコードのコミットにリンクします
• 関連するドキュメントの更新をまとめます

品質チェックリスト

ドキュメントを完成とする前に、次の項目を確認してください。

• すべてのコード例をテストし、動作を確認済み
• コードと照らし合わせて技術的な正確性を確認済み
• リンクが有効で正しい
• 書式に一貫性がある
• 手順が完全で、実行可能である
• 同期チェックに合格している
• 検証スコアが基準値を上回っている

よくあるワークフロー

「新しいコードを書いたので、ドキュメントが必要」

/docs-specialist:docs generate <path>

「コードを変更したので、ドキュメントを更新する」

/docs-specialist:sync check
/docs-specialist:sync fix

「ドキュメントの品質を監査する」

/docs-specialist:docs validate
/docs-specialist:sync check

「新しいプロジェクトのドキュメントを設定する」

/docs-specialist:init
/docs-specialist:docs generate all

「リリース前のチェック」

/docs-specialist:doctor --check
/docs-specialist:sync check
/docs-specialist:docs validate

成功指標

優れたドキュメントとは、次のようなものです。

• 正確 - 現在のコードの実態を反映している
• 完全 - 必要なトピックをすべて網羅している
• 同期済み - 実装とのずれがない
• 明確 - 理解しやすい
• 保守しやすい - 更新が容易
• 実行可能 - 読者が目的を達成できる