documentation-guide

name	documentation-guide
description	ドキュメント作成時の共通ルール。Markdown ドキュメントを新規作成・更新する際には、必ずこのスキルを参照して従ってください。

ドキュメント作成ガイド

本スキルは、リポジトリ内の Markdown ドキュメントを作成・更新する際に従うべきルールを定義する。

適用範囲

• docs/ 配下の全ドキュメント
• README.md
• その他リポジトリ内に作成する Markdown ファイル全般

セッション内部の作業用ファイル（plan.md 等）には適用しない。

ルール

1. プロフェッショナルなフォーマット

• 絵文字は 原則使用禁止 とする
• 例外: どうしても注意を引く必要がある箇所（重大な警告、破壊的変更など）に限り、最小限の使用を許可する
• 装飾目的での絵文字（見出しの先頭、一覧のアイコンなど）は禁止

2. 概要セクションの必須化

• 全てのドキュメントの先頭に 「概要」セクション を設けること
• 概要セクションを読むだけで、ドキュメント全体の内容を大まかに把握できるようにすること
• 大量のドキュメントは人間にとって負荷が高い。概要セクションで読者が必要な箇所を素早く特定できるようにする

構成例:

# ドキュメントタイトル

> メタ情報（対象システム、関連ドキュメントへのリンクなど）

---

## 概要

このドキュメントは〜を定義する。

### 主要なポイント（表や箇条書きで簡潔に）

| 項目 | 内容 |
|------|------|
| ... | ... |

---

## 1. 詳細セクション ...

3. 図表は Mermaid で記述

• フローチャート、シーケンス図、依存関係図などの図表は Mermaid で記述すること
• AA（アスキーアート）による図表記は禁止
• ディレクトリツリー構造（├── 等）はコードブロックのままでよい（Mermaid 化不要）

使い分け:

内容	記法
フローチャート	flowchart TD / flowchart LR