| name | document-write |
| description | ドキュメントの新規作成または更新を行う場合にこのスキルを使用してください。
既存文書との整合性を保ちながら、記述・同期・自動生成を進めるためのガイドラインを提供します。
|
ドキュメントの新規作成・更新スキル
このスキルは、主に Markdown 文書の新規作成または更新を行う場合の進め方と記述方針を提供します。
人間と AI エージェントの双方が参照し、作業や判断に使える状態を目指します。
有効化するタイミング
レビューや問題発見が主目的の場合は、document-review を使う。
進め方
- 対象文書と周辺文書を読み、語彙、見出し構成、記法の平仄を把握する
- 対象読者と利用場面を整理し、読後に何ができるべきかを明確にする
- 実装、設定、一次情報を確認し、更新対象の事実関係を固める
- 新規作成か追記かを判断し、文書の責務が分散しすぎない配置を選ぶ
- 本文、図、コード例、リンクを更新し、周辺文書との参照関係を整える
- 実装や運用手順との整合性に加え、リンク、見出し、Markdown の崩れ、コード例やコマンド例の再現性を確認する
代表的な作業パターン
技術文書を新規作成する場合
- 文書の責務を先に決め、1 つの話題に集中させる
- 対象読者が人間か AI エージェントか、またはその両方かを意識し、読後に期待する行動を先に決める
- 設計文書、仕様書、運用手順書など、読者と用途に応じて置き場所と見出し構成を決める
- 図が必要な場合は Mermaid または PlantUML を使う
コード変更時にドキュメント更新が必要な場合
- 関数・クラスのコメント、実装詳細、型注釈、発生可能な例外の説明を見直す
- 実装変更に伴って README、設計書、手順書にも追従が必要か確認する
- 変更したコード例やコマンド例が現在の実装で再現できる状態に保つ
API文書の自動生成・更新を行う場合
- OpenAPI/Swagger 仕様書などの生成元と生成物の関係を把握する
- 修正は生成元(source of truth)側で行い、生成物への直接修正は再生成で失われる前提で扱う
- 自動生成で反映されない補足説明がある場合は、手書き部分との責務を分ける
- 再生成手順や更新契機が必要なら文書内または周辺文書に残す
既存の文書体系に合わせて追記・修正する場合
- 周辺文書を読み、語彙、見出し構成、記法、文体の平仄を揃える
- 似た内容の文書が既にある場合は、新規作成ではなく既存文書への統合を優先する
- 同じ内容を別の場所で重複管理しない
README やセットアップ手順を更新する場合
- 新しい前提条件、環境変数、CLI 引数、依存関係、権限要件を反映する
- 初回セットアップや日常運用の手順が上から順に実行できる構成を保つ
- ローカル開発、CI、本番運用など、読者ごとの差分がある場合は誤読されないように分ける
ドキュメント記述の方針
- このスキルは Markdown 文書を対象とする汎用ガイドとして扱う
- 図をテキストで管理する必要がある場合は、Mermaid または PlantUML を優先する
- 説明は、箇条書きよりも段落で自然に読める構成を優先する
- 見出しに番号を振らない
- 見出しは 4 階層以上にしない
- 文書は 1 つの話題に集中させる
- 外部仕様を前提とする場合は、一次情報を付与する
- 実装から直接読み取れない推測は書かない
- 曖昧な表現を避ける
- 作業の記録や今後の方針を書く場合は、作業の方向性だけを示す記述で終えない
- 現状の問題、判断理由、次に触る責務・ファイル、未決事項を具体的に残す
- 既存文書のスコープが広くなってきた場合、または現在の作業内容に対して広すぎる場合は、文書の責務を絞る提案を行う
- 日本語の改行は文章のまとまりで入れる
- 段落内で改行する場合は、原則として「。」のあとで入れる
- Markdown の強制改行を使う場合は、行末に半角スペース 2 つを入れる
- 既存のドキュメントが存在する場合は、文体、見出し構成、語彙、記法の平仄を崩さない
- 規約や方針を文書化する場合は、必要に応じて
推奨 / 非推奨 の具体例を併記し、レビュー時の判断基準が実例で読める状態にする
- 新規追記時は既存の見出し階層に沿って統合し、必要に応じて話題を分割して浅い階層を保つ
- 箇条書きは、同列の項目を複数並べる場合、手順を示す場合、確認事項や規約を列挙する場合に使う
- 単一の要点だけを述べる場合は段落で記載し、1 項目だけの箇条書きは避ける