documentation-guide

# ドキュメント作成ガイド 本スキルは、リポジトリ内の Markdown ドキュメントを作成・更新する際に従うべきルールを定義する。 ## 適用範囲 - `docs/` 配下の全ドキュメント - `README.md` - その他リポジトリ内に作成する Markdown ファイル全般 > セッション内部の作業用ファイル（`plan.md` 等）には適用しない。 ## ルール ### 1. プロフェッショナルなフォーマット - 絵文字は **原則使用禁止** とする - 例外: どうしても注意を引く必要がある箇所（重大な警告、破壊的変更など）に限り、最小限の使用を許可する - 装飾目的での絵文字（見出しの先頭、一覧のアイコンなど）は禁止 ### 2. 概要セクションの必須化 - 全てのドキュメントの先頭に **「概要」セクション** を設けること - 概要セクションを読むだけで、ドキュメント全体の内容を大まかに把握できるようにすること - 大量のドキュメントは人間にとって負荷が高い。概要セクションで読者が必要な箇所を素早く特定できるようにする **構成例:** ```markdown # ドキュメントタイトル > メタ情報（対象システム、関連ドキュメントへのリンクなど） --- ## 概要 このドキュメントは〜を定義する。 ### 主要なポイント（表や箇条書きで簡潔に） | 項目 | 内容 | |------|------| | ... | ... | --- ## 1. 詳細セクション ... ``` ### 3. 図表は Mermaid で記述 - フローチャート、シーケンス図、依存関係図などの図表は **Mermaid** で記述すること - AA（アスキーアート）による図表記は禁止 - ディレクトリツリー構造（`├──` 等）はコードブロックのままでよい（Mermaid 化不要） **使い分け:** | 内容 | 記法 | |------|------| | フローチャート | `flowchart TD` / `flowchart LR` | | シーケンス図 | `sequenceDiagram` | | 依存関係・構成図 | `graph LR` / `graph TD` | | クラス図 | `classDiagram` | | ディレクトリツリー | コードブロック（` ``` `）| ### 4. 簡潔さの重視 - 冗長な説明は避け、要点を明確に記述すること - 同じ情報を異なる形式で繰り返さない - 表形式で整理できる情報は表を使う - 長文の段落よりも箇条書きや表を優先する ### 5. 構造化 - 見出しレベルは `#`（H1）から `####`（H4）まで使用可能。H5 以下は使用しない - 関連ドキュメントへのリンクは相対パスで記述する - コードサンプルには適切な言語指定を付ける（` ```csharp `, ` ```mermaid ` 等）