Guide 記述標準
Guide Authoring Standard
docs/ja/specdojo/guides/ 配下の各 *-guide.md が従うべき構成・記述ルール・Frontmatter 規約・禁止事項・運用ルールを定義します。Frontmatter の共通原則は document-metadata-standard.md に従い、機械検証は参照スキーマに従います。
1. 適用範囲
- 対象:
docs/ja/specdojo/guides/配下のすべての*-guide.md - 目的: guide の構成・記述品質を統一し、読み手が考え方・手順・使い方を理解して実行できる説明文書を提供する
- 位置づけ: guide は規範（must）ではなく、理解・操作・判断を助ける説明と手順を扱う。規範事項は対応する standard / rulebook、規約の前提となる方針・概念は philosophy を正本とする
- Frontmatter 共通原則: document-metadata-standard.md
- 参照スキーマ: guide-frontmatter.schema.yaml
- ファイル名・ID 規則: docs-structure-guide.md
2. 見出しレベルと章番号の原則
#はタイトルのみ。章は##から開始する。- 章番号は 1 始まりの連番。スキップしない（例:
## 1., 次は## 2.）。 - 章番号末尾には必ず
.を付ける。 - 章への参照は章番号ではなく章タイトルで記載する。
- タイトル直下に 英語名（1行） を置き、その直下に 目的・概要（1〜3文） を置く。
3. 導入ブロック
目的・概要の直下、最初の ## 見出しより前に、次の3ブロックをこの順で置く。各ブロックは **ラベル** だけの段落で始め、内容は箇条書きで書く。
| ラベル | 書く内容 |
|---|---|
| 対象読者 | この guide を読む役割・立場（誰が読む文書か） |
| この文書で分かること | 読み終えたときに得られる知識・判断材料の範囲 |
| 次に読む文書 | この guide の直後に進む文書（2〜3件）。網羅的な一覧は置かない |
markdown
**対象読者**
- Schedule や登録簿のタスクを人またはエージェントで実行・監視する開発者、運用者
**この文書で分かること**
- 実行経路の選び方、自動・手動実行、状態遷移、blocked 復帰
**次に読む文書**
- エージェント設定は [exec設定ガイド](exec-config-guide.md) を参照してください。- 「次に読む文書」には、その guide の直接の後続だけを書く。目的別の横断一覧は specdojo-overview-guide.md の
目的別の次の読み物を唯一の正本とし、各 guide に同じ一覧を複製しない。 - 同じ理由で、guide の末尾に全 guide を並べる「詳細ガイド」章を置かない。特定のテーマに閉じた関連文書の列挙は妨げない。
- 機械検証は guide-content.schema.yaml を SSOT とし、
npm run lint:fmで検証する。
4. Frontmatter 規約
- ファイル名は
<name>-guide.mdとする。 id/type/statusを必須とし、共通原則は document-metadata-standard.md に従う。typeはguide固定とする。idはauthority、英小文字・数字・ハイフンで構成し、一意にする（正確な制約は参照スキーマに従う）。statusはdraft/ready/deprecatedのいずれかとする。
| 項目 | 必須 | 説明 |
|---|---|---|
| id | ○ | specdojo:<name>-guide 形式の一意 ID |
| type | ○ | guide 固定 |
| status | ○ | draft / ready / deprecated |
| based_on | 任意 | 根拠ドキュメント |
| supersedes | 任意 | 置き換え関係 |
- 機械検証は guide-frontmatter.schema.yaml を SSOT とする。
記述例:
yaml
---
specdojo:
id: specdojo:docs-structure-guide
type: guide
status: draft
---5. 構成の原則
- guide は固定の標準章構成を持たず、テーマ単位で章立てする。
- 冒頭（H1 と概要）で、目的・対象読者・前提が読み取れるようにする。
- 手順は番号付きリストで示し、操作・設定はコマンドや設定例などの具体物を添える。
- 規範事項（must）は対応する standard / rulebook へリンクし、guide 側で再定義しない。
- 章が長くなる場合は、テーマ単位の小見出し（
###）で分割する。
6. 記述ガイド
- 文体は「です・ます」体を既定とする。standard / rulebook の規範文（「である」体）とは役割を分け、guide は読み手に語りかける説明・手順の文書として統一する。1 つの guide 内で「です・ます」と「である」を混在させない。
- 読み手が再現できる粒度で手順を書き、前提と結果を明示する。
- スクリーンショット、コマンド、設定例、画面名など、操作に必要な具体物を活用する。
- 用語は対応する standard / rulebook と整合させ、命名ゆれを持ち込まない。
- 推奨表のカラム定義（例: 操作、目的、手順、注意点）を 1 つ以上提示する。
- 未確定事項や仮置き情報は、本文中に次の共通ラベルで記述する。
- TODO: 後で人または生成 AI が確認・追記・修正する必要がある事項
- UNDECIDED: 情報不足ではなく、意思決定が未了で未確定の事項
- ASSUMPTION: 現時点で仮置きしている前提・仮説
_CONTEXT_:: 下書きへの指示。記法と反映・記録は ドキュメントメタ情報標準 の「文脈の目印」に従う。
- リンクはファイルがある場合に記載し、ない場合はバッククォートで仮置きする。
7. 禁止事項
- 章番号なし見出し（例:
## 基本操作）を使用しない。 - 章番号末尾の
.を省略しない。 - 規範（must ルール・規約）を guide で新規に定義しない。standard / rulebook を正本とする。
- 曖昧語（十分、適切、問題ない）を根拠なく使用しない。
- デッドリンクを記載しない。
_TODO_:/_UNDECIDED_:/_ASSUMPTION_:/_CONTEXT_:以外の独自ラベルを、共通ルール未定義のまま追加しない。導入ブロックの3ブロックを省略しない。ラベル名を変えない。順序を入れ替えない。- 全 guide / reference を並べた目的別の横断一覧を、
specdojo:specdojo-overview-guide以外に置かない。
8. 運用ルール
- 参照先の standard / rulebook / ツール仕様が変わった場合は、guide の手順・記述を追従させる。
- 操作手順や画面が変わった場合は、具体物（コマンド・設定例・画面名）の整合を確認する。
- 表は必要に応じて SpecDojo VS Code 拡張の
SpecDojo: Format Markdown Tableコマンドで揃える。