| name | anytime-markdown-output |
| effort | low |
| description | Markdown ドキュメント（spec/tech/test/manual/proposal/plan/review/report）を出力・編集する際の構文・フロントマター・整形規約。/Shared/anytime-markdown-docs/ 配下に .md を作成/更新する時、見出し・テーブル・コードブロック・脚注・アドモニション・図表・フロントマター(type/c4Scope 等)を書く時、Markdown 出力仕様を確認する時に使用する。 |
path: "**/*.md"
Claude Code Markdown 出力仕様
更新日: 2026-07-11
type 別の記載内容（何を書くか）・索引 index.[lang].md 運用は anytime-doc-authoring スキル、既存設計書の読み方は anytime-spec-lookup スキルを参照。本スキルは構文・フロントマター・整形（どう書くか）を扱う。
1. ファイル命名規則
- 共通ドキュメント（設計書・テスト項目書・マニュアル等）:
[topic]/ フォルダを作成し、その中に [topic].[lang].md（日英両方）を出力する。画像は [topic]/images/ に配置する。
- 都度作成ドキュメント（plan・review）:
[YYYYMMDD]-[topic].[lang].md — 指示がなければ日本語のみ出力する。
- 予約ファイル
index.[lang].md（各フォルダ必須・OKF 段階開示）: 索引の構成・自動生成（scripts/gen-spec-index.mjs・手書き禁止）・再生成必須の運用は anytime-doc-authoring スキル §1.2 に集約した。ドキュメントを追加・更新・改名・削除したら同スキルに従い索引を再生成する。
lang は ja（日本語）/ en（英語）。- 分類が不明な場合はユーザーに確認する。
2. フロントマター仕様
/Shared/anytime-markdown-docs/ 配下に出力するすべての Markdown ファイルには、フロントマターを必ず付与する。
---
title: "ドキュメントタイトル"
date: "YYYY-MM-DD"
type: "spec"
lang: "ja"
author: "Claude Code v[CLIバージョン]"
category: "カテゴリ名"
excerpt: "ドキュメントの要約。200文字以内。"
---
2.1. フィールド定義
| フィールド | 必須 | 最大長 | 説明 |
|---|
title | Yes | 200 | ドキュメントタイトル |
author | No | 100 | 著者名。AI 生成の場合は Claude Code v[バージョン] を記載 |
lang | Yes | 5 | 言語コード。ja（日本語）または en（英語） |
type | Yes | - | ドキュメント種別。下記の種別一覧から選択 |
category | No | 100 | サブカテゴリ。/report ページでは一覧にチップ表示される |
excerpt | No | 500 | ドキュメントの要約。/report ページでは一覧・OG description に使用 |
thumbnail | No | 500 | サムネイル画像 URL（現在 UI 未使用） |
| skill | No | 100 | 利用スキル |
c4Scope | No | - | C4モデル要素IDの配列。type: "spec" の場合に付与する。詳細は 2.3 を参照 |
date | Yes | 30 | 作成日または公開日（YYYY-MM-DD 形式） |
updated | No | 30 | 更新日（YYYY-MM-DD 形式）。既存ファイルの内容を変更した場合に追加・更新する |
schemaVersion | No | 10 | フロントマター仕様の版。破壊的変更時に上げ、後方互換で進化させる（OKF のバージョン管理原則）。未指定時は最新仕様とみなす |
[!IMPORTANT]
\\\`author\\\` が AI の場合、\\\`Claude Code v2.1.85\\\` のように CLI バージョンを含めること。\\\\ バージョンは \\\`claude --version\\\` で取得する。
2.1.1. フロントマターの消費者（機械契約）
フロントマターは複数の機械的消費者が依存する「契約」である。以下のフィールドは表示・機能に直結するため、消費者を壊さないよう値の整合性を保つ。それ以外のフィールド・本文セクション構成はプロデューサー（書き手）の裁量である。
| フィールド | 消費者 | 用途 |
|---|
title / type / category / excerpt / date | web-app /report ページ | 一覧表示・カテゴリチップ・OG description・並び替え |
c4Scope | C4 モデルビューア | 要素選択時の関連ドキュメント自動表示（2.3） |
related | note-graph ビューア | ドキュメント間リンクのグラフ描画 |
[!NOTE]
機械契約フィールド（上表）を変更・廃止する場合は、消費者側の改修とセットで行う。仕様を破壊的に変更する際は schemaVersion を上げる。
2.2. ドキュメント種別（type）
type | 出力先フォルダ | 説明 |
|---|
spec | /spec/ | 設計書。機能仕様・アーキテクチャ設計・データモデル定義等 |
tech | /tech/ | 技術調査・技術記事。ライブラリ比較・技術検証・解説記事等 |
test | /test/ | テスト項目書。ユニットテスト・E2E テストのケース一覧 |
manual | /manual/ | マニュアル・手順書。ユーザー向け操作ガイド・セットアップ手順等 |
proposal | /proposal/ | 提案。改善提案・新機能提案・技術選定の提案等 |
plan | /Shared/anytime-markdown-docs/plan/ | 実装計画。タスク分解・スケジュール・依存関係の定義 |
review | /review/ | レビュー。コードレビュー結果・設計レビュー記録 |
report | /report/ | レポート。日次調査・週次調査・Issue 解決レポート等。Web アプリの /report ページに一覧表示される |
2.3. c4Scope（type: "spec" 専用）
type が spec のドキュメントには c4Scope フィールドを付与する。
C4モデルの要素選択時に関連ドキュメントを自動表示するために使用する。
- 値は C4モデルの要素ID（
sys_・pkg_ プレフィックス付き）の YAML 配列
- 設計書の記載対象に応じたレベルの要素IDを指定する
- 要素IDは C4 モデル API（
packages/web-app/src/app/api/c4/model/route.ts が返す model.elements）から取得する
---
title: "graph-core 設計書"
type: "spec"
c4Scope:
- "pkg_graph-core"
- "pkg_graph-core/engine"
---
| レベル | ID 例 | 用途 |
|---|
| システム | sys_anytime-markdown | システム全体の設計書 |
| コンテナ | pkg_web-app | パッケージ単位の設計書 |
| コンポーネント | pkg_graph-core/engine | パッケージ内モジュールの設計書 |
[!NOTE]
要素を選択すると、完全一致に加え子パス前方一致（`pkg_graph-core` 選択時に `pkg_graph-core/engine` も表示）でドキュメントが検索される。
3. 構文仕様
本仕様は GFM (GitHub Flavored Markdown) Spec をベースに、Claude Code が Markdown ファイルを出力する際に使用する構文を定義したものである。GFM は CommonMark の厳密なスーパーセットであり、本仕様はその中から必要な構文のみを抽出・限定している。
3.1. ATX 見出し (Section 4.2, Examples 32-49)
# 見出し1
## 見出し2
### 見出し3
# を1～3個使用# の直後に空白、行末は改行が必須
3.2. 水平線 (Section 4.1, Examples 13-31)
---
3.3. フェンスコードブロック (Section 4.5, Examples 89-117)
コードフェンスとは、3個以上の連続するバッククォート文字（`）の並びである。
- 開始フェンス: 3個以上の
`
- 終了フェンス: 開始以上の個数の
`
- インフォ文字列（言語指定）は開始フェンスのみ
- インフォ文字列にバッククォート不可
- 開始フェンスが N スペースインデントの場合、内容行から最大 N スペースを除去
- 閉じられなかったフェンスはドキュメント末尾で閉じる
3.4. テーブル (GFM 拡張, Section 4.10, Examples 198-205)
3.4.1 基本構造
| ヘッダ1 | ヘッダ2 | ヘッダ3 |
| --- | --- | --- |
| データ1 | データ2 | データ3 |
ヘッダ行 + セパレータ行 + 0個以上のデータ行で構成。
3.4.2 セパレータ行（delimiter row）
セパレータ行は、ハイフン（-）のみで構成されるセルからなり、オプションで先頭・末尾にコロン（:）を付与して左寄せ・右寄せ・中央寄せを指定できる。
| 構文 | 配置 |
|---|
--- | デフォルト（左） |
:--- | 左寄せ |
---: | 右寄せ |
:---: | 中央寄せ |
3.4.3 セル内のルール
- セル内容の前後の空白はトリムされる
- セル内でパイプを使う場合は
\| でエスケープ
- セル内ではインライン要素が解析される（コードスパン、強調等）
- セル内のハードブレーク（改行）は
<br> を使用する（\ は使用不可）
- ブロック要素は使用不可
3.4.4 セル数の不一致
- ヘッダ行とセパレータ行のセル数が不一致 → テーブルと認識されない (Example 203)
- データ行がヘッダより少ない → 空セルで補充
- データ行がヘッダより多い → 超過分は無視
3.4.5 具体例
Example 200: セル内のパイプエスケープ
| f\|oo |
| ------ |
| b `\|` az |
| b **\|** im |
3.5. コードスパン (Section 6.3, Examples 328-349)
バッククォート文字列とは、1個以上の連続するバッククォート文字（`）で、前後にバッククォートがないものである。コードスパンはバッククォート文字列で始まり、同じ長さのバッククォート文字列で終わる。
3.5.1 基本ルール
- 開始と終了で同じ数のバッククォートを使用
- 開始デリミタと同じ数のバッククォート文字列が最初に見つかった位置で閉じる
- バックスラッシュエスケープは効かない（内容はリテラル）
- 改行はスペースに変換される
基本的なコードスパン:
`code` → code
バックスラッシュはリテラル扱い:
`foo\bar` → foo\bar（エスケープされない）
改行はスペースに変換:
`foo
bar` → foo bar
3.5.2 先頭・末尾スペースの扱い
結果の文字列が先頭と末尾の両方がスペースで、かつスペースのみで構成されていない場合、先頭と末尾から各1文字のスペースを除去する。
- 先頭と末尾の両方がスペースで、かつスペースのみではない → 各1文字除去
- 片方だけスペース → 除去しない
- スペースのみ → 除去しない
`` `foo` `` → `foo`（前後スペース除去で ` が内容に含まれる）
`` ` `` → `（前後スペース除去）
` `` ` → ``（前後各1スペース除去、内側スペースは残る）
` ` → ` `（スペースのみなので除去しない）
3.5.3 バッククォート数の決定方法
内容に含まれるバッククォートの連続と衝突しない最小数を選ぶ。
| 内容 | 必要なデリミタ数 | 記法 |
|---|
| バッククォートなし | 1個 | `code` |
単独の ` あり | 2個 | `` foo`bar `` |
`` `` あり、単独 `` ` なし | 1個 | ` foo``bar ` |
`code` ← バッククォートなし → 1個で囲む
`` foo`bar `` ← 内容に1個の ` → 2個で囲む
` foo``bar ` ← 内容に2個の `` だが1個の ` なし → 1個で囲む
3.6. リスト (Section 5.2-5.4)
箇条書き: -
順序付き: 1.（最大9桁）
密なリスト（項目間に空行なし）:
- 項目1
- 項目2
- 項目3
緩いリスト（項目間に空行あり、各項目が <p> で囲まれる）:
- 項目1
- 項目2
- 項目3
順序付きリスト:
1. 項目1
2. 項目2
3. 項目3
ネストしたリスト（4スペースインデント）:
- 項目1
- サブ項目1
- サブ項目2
- 項目2
3.7. タスクリスト (GFM 拡張, Section 5.3)
- [ ] 未完了タスク
- [x] 完了タスク
- リスト項目の先頭に
[ ]（未完了）または [x]（完了）を付与
[ と ] の間はスペースまたは x のみ- 箇条書き・順序付きリストのどちらでも使用可能
- ネスト対応
ネストしたタスクリスト:
- [ ] 親タスク
- [x] サブタスク1
- [ ] サブタスク2
3.8. ブロック引用 (Section 5.1)
> 引用テキスト
> 続きの行
> 外側の引用
> > ネストした引用
> 引用の開始
続きの行（> を省略）
3.8.1 アドモニション (GitHub 拡張)
引用ブロック内で [!TYPE] を記述することで、注記・警告などのアドモニション（コールアウト）を表現する。
> [!NOTE]
> 補足情報を記載する。
>
> [!TIP]
> 効率的な操作方法を紹介する。
>
> [!IMPORTANT]
> 見落とすと問題になる重要な情報を強調する。
>
> [!WARNING]
> 注意が必要な操作や既知の制限事項を警告する。
>
> [!CAUTION]
> データ損失や不可逆な操作について注意喚起する。
対応タイプ:
| タイプ | 用途 |
|---|
NOTE | 補足情報・参考ヒント |
TIP | 効率的な操作方法・ショートカット |
IMPORTANT | 見落とすと問題になる重要情報 |
WARNING | 注意が必要な操作・既知の制限 |
CAUTION | データ損失・不可逆操作の注意喚起 |
[!TYPE] は引用ブロックの最初の行に記述する- タイプ名は大文字で記述する
[!TYPE] の行の後に本文を続ける
3.9. 強調・太字 (Section 6.4)
*強調*
**太字**
***太字強調***
3.10. 取り消し線 (GFM 拡張, Section 6.5, Example 490)
~~取り消し~~
3.11. リンク・画像 (Section 6.6-6.7)
[テキスト](URL "タイトル")
3.12. バックスラッシュエスケープ (Section 6.1, Examples 296-305)
すべての ASCII 句読文字はバックスラッシュでエスケープできる。
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
| コンテキスト | エスケープ |
|---|
| 通常テキスト | 有効 |
| コードスパン内 | 無効（リテラル扱い） |
| コードブロック内 | 無効（リテラル扱い） |
3.13. エンティティ参照 (Section 6.2, Examples 306-327)
エンティティ参照および数値文字参照は、コードブロックおよびコードスパン内では認識されない。
| 種類 | 構文 | 例 |
|---|
| HTML エンティティ | &name; | & → &, < → <, > → > |
| 10進数値参照 | &#decimal; | # → # |
| 16進数値参照 | &#xhex; | # → # |
| コンテキスト | 展開 |
|---|
| 通常テキスト | される |
| コードスパン内 | されない |
| コードブロック内 | されない |
3.14. 改行 (Section 6.12-6.13)
| 種類 | 構文 | 出力 |
|---|
| ハードブレーク | \ | <br /> |
| ソフトブレーク | 通常の改行 | スペースに変換 |
ハードブレーク:
行1\
行2
→ 行1<br />行2（同上）
ソフトブレーク:
行1
行2
→ 行1 行2（スペースで連結される）
段落区切り（空行）:
段落1
段落2
→ 別々の <p> 要素になる
3.15. 脚注
3.15.1 脚注参照
本文中に [^id] で脚注参照を挿入する。
本文中の参照箇所[^1]。別の参照[^2]。
3.15.2 脚注定義
ドキュメント末尾に [^id]: 内容 で脚注の定義を記載する。
[^1]: 脚注の内容を記載する。
[^2]: 別の脚注の内容。
- 脚注番号は 1 から順番に採番する
- 脚注定義はドキュメント末尾にまとめて配置する
- 定義行の
: の後にスペースを入れる
3.16. フロントマター
ドキュメントの先頭に --- で囲んだ YAML ブロックでメタデータを記載する。
- フロントマターはドキュメントの最初の行から開始する（前に空行を入れない）
- 開始・終了ともに
---（3個のハイフン）を使用する
- フロントマターの後に空行を1行入れてから本文を開始する
- 水平線の
--- とは用途が異なる（フロントマターは先頭行のみ有効）
3.17. マークダウン設計書: 可読性向上ガイドライン
設計書の可読性とメンテナンス性を一貫させるため、以下のルールを適用する。
3.17.1 整形・検証ルールは anytime-markdown-check に集約
可読性のための整形・記法ルールは anytime-markdown-check スキルを単一の真実とする。本仕様では重複定義しない（値の不一致を防ぐため、旧 §3.17.1〜3.17.3 の個別ルールは anytime-markdown-check へ移管した）。
- 機械的整形（見出し前後の空行 上1・下1／リスト・テーブル・引用の前後空行／連続空行の圧縮 最大2／ネストインデント 半角4スペース／行末空白除去／テーブルのパイプエスケープ）:
format_markdown(path, mode="fix")（mcp-markdown）が自動修正する。手書きで揃えない。
- 意味判断（固有名称のコードスパン化／補足の引用ブロック化／複雑ロジックの Mermaid 図化／「。」直後の改行／箇条書き3階層超の子見出し再設計）:
anytime-markdown-check スキルのチェックリストに従う。
3.17.4 ファイル粒度と部分読み最適化（AI エージェント可読性）
AI エージェント（Claude Code 等）は設計書をファイル全体ではなく、検索 → 該当セクションのみ部分読み（offset/limit）で参照する。
文脈サイズを抑え、関連箇所だけを正確に拾わせるため以下を適用する。
- 1ファイル1トピック・目安400行以下: 1 つのファイルは単一の主題に絞る。超える場合は子見出し（
##）単位で別ファイルに分割し、相互に related ／本文リンクでつなぐ。巨大ファイルは全体読み込みを誘発し、参照コストを押し上げる。
- セクションの自己完結: 各セクションは単独で読んで意味が通るように書く。「前述の通り」「上記の」等の暗黙参照を避け、対象を明示リンク（
[データモデル](04-data-model.ja.md) 等）で示す。部分読みされても文脈が壊れない。
- 既存コンセプトはインラインリンクで必ず結ぶ（必須）: 本文で他の設計書・テーブル・パッケージ等、既に文書化された概念に言及する際は、ルート相対リンク（
[customers](/tables/customers.md) 等）で必ず接続する。frontmatter の related だけに頼らず本文リンクでも結ぶことで、ドキュメント群がリンクグラフ（note-graph）を形成し、AI エージェントが関連文書を最小コストで辿れる（OKF のグラフ構造原則）。
- 行範囲付き目次: 400 行を超えるファイルは、フロントマター直後に各
## 見出しと該当行範囲を併記した目次を置く。AI が必要なセクションだけを offset/limit で読めるようにする。
- 結論ファースト: ファイル冒頭および各セクション冒頭に要点（結論・概要）を先に置く。先頭数行で主旨が掴め、詳細を読むかの判断が速くなる。
- 安定した見出し語彙:
概要 ／ 背景 ／ 設計 ／ データモデル ／ 制約 ／ リスク 等、プロジェクト共通の見出し語を用いる。検索（grep）での命中率が上がり、目的セクションへの到達が確実になる。
[!NOTE]
ドキュメント間の関係は frontmatter related（ルート相対パス）で表す。人間は note-graph ビューアで俯瞰し、AI は related を辿って関連文書のみを最小コストで参照する。型付き関連付け（{ to, type } 形式）の導入後は本節に語彙・スキーマを追記する。
4. 参考記事・出典の注釈
参考にした記事や出典がある場合は、本文中に脚注参照 [^1] を挿入し、ドキュメント末尾に脚注定義を記載する。
本文中の参照箇所[^1]。
[^1]: 著者名「記事タイトル」URL（参照日: YYYY-MM-DD）
- 外部記事・公式ドキュメントを参考にした場合は必ず注釈で出典を明示する
- 脚注番号は 1 から順番に採番する
- 参照日を記載し、情報の鮮度を明確にする
5. Mermaid 図
Mermaid 図を含む場合は anytime-mermaid スキルに従う。
6. 画像の alt テキスト
画像を挿入する場合は必ず alt テキストを記載する。
空の alt テキスト  は禁止。
<!-- NG -->
<!-- OK -->
7. 図表・データ可視化の表現原則
ドキュメントに図表（テーブル・グラフ／チャート・Mermaid 図・画像）を含める場合、デジタル庁「ダッシュボードデザイン実践ガイドブック」の図表設計原則に従い、**「知りたいことが伝わる」「誤解を生まない」**図表にする。
7.1 表現手段の使い分け
伝えたい内容に応じて手段を選ぶ。
| 伝えたいこと | 推奨手段 |
|---|
| 網羅的な一覧・正確な値の参照 | Markdown テーブル |
| 傾向・比較・構成比（量の変化） | グラフ／チャート（折れ線・棒・円。プロジェクトのチャート記法または画像） |
| 構造・関係・フロー・状態遷移 | Mermaid（anytime-mermaid スキル） |
| 実物・スクリーンショット | 画像（alt 必須・第6章） |
- 大量の数値を文章に埋め込まない。一覧性が要るならテーブル、傾向なら図にする。
7.2 知りたいことが伝わる（Do）
- 全体から詳細へ: 全体像を表す要約・指標を先に置き、詳細の表やグラフを後に続ける（結論ファースト）。
- 並び順に意味を持たせる: テーブルの行・グラフの項目は、値の大小順・時系列順・論理順など、読み手が比較しやすい順に並べる。あいうえお順など無意味な並びにしない。
- 強弱をつける: 注目させたい系列・値を強調し、それ以外は控えめ（淡色・グレー）にする。
- 不要な要素を削る: 過剰な罫線・グリッド・冗長な軸ラベル・小数の桁過多を避け、情報量を必要最小限にする。
- 装飾に頼らない: 3D・ドロップシャドウなど数値と無関係な装飾表現は使わない。
- 色数を絞る: 1 図あたり概ね 1〜5 色に抑え、注目すべき系列を明確にする。
7.3 誤解を生まない（Do）
- タイトル・ラベルを端的かつ正確に: 図表のタイトルに内容とデータ種別（例: 月次推移／累計／構成比）を明記し、何を表すか一目で分かるようにする。冗長な説明は避ける。
- 凡例を対象に隣接・順序対応: 凡例はグラフの近くに置き、並び順を系列の順序と一致させる。
- 原点を歪めない: 棒グラフの原点は原則 0 にし、量の大小を実際より誇張・矮小化しない。
- データのメタ情報を併記: 出典・対象期間・更新日・集計条件を図表の近くに記載する。出典は本文に脚注
[^n] で示す（第4章）。
7.4 色とアクセシビリティ
[!IMPORTANT]
色だけで情報を伝えない。色覚多様性に配慮し、白黒印刷でも伝わるようにする。
- 色のみで分類を識別しない: 系列の区別は色に加えて、ラベルの直接付与・線種（実線／点線）・マーカー形状・パターンでも行う。Mermaid では
classDef の色だけに頼らず、ノードラベルや形状でも区別する。
- アドモニションは色＋ラベル＋アイコンで意味を伝える（第3.8.1節。色だけに依存しない）。
- コントラスト比: テキストは背景に対して 4.5:1 以上、図表の色面は 3:1 以上を確保する。満たせない場合は数値・ラベルを直接併記する。
7.5 図表セルフチェックリスト
ドキュメントに図表を含めたら以下を確認する。
8. アカウント情報の記載禁止
ドキュメントにアカウント情報（ユーザー名、パスワード、デフォルト認証情報等）を具体的に記載しない。
環境変数の説明では、デフォルト値欄に (必須) や (省略可) と記載し、実際の値を含めない。
9. component spec（パッケージ設計書）の記載ルール
type 別の記載内容（component spec の外部仕様原則・spec/e2e 2 ファイル分離・E2E シナリオ表・見出し粒度・索引運用を含む）は anytime-doc-authoring スキルへ移管した（値の不一致を防ぐため本仕様では重複定義しない。§3.17.1 の anytime-markdown-check への集約と同じ方針）。本スキルは構文・フロントマター・整形（どう書くか）のみを扱う。
