markdown-style

markdown-style

Markdown の作成とレビューのスキルです。2 層のルールと、その適用手順を扱います。

1. 構文規範 — 有効な Markdown の形式です。Markdown Guide の基本構文リファレンスに基づいています。規範の全文は references/syntax-canon.md にあります。
2. スタイルオーバーレイ — 有効な構文に加えて、レビュアーが適用する、独自のルールです。Google の Markdown スタイルガイドに基づいています。オーバーレイの全文は references/style-overlay.md にあります。

質問が 「このドキュメントは適切に構成されていますか？」 である場合に、このスキルを読み込みます。「このドキュメントはここに置くべきですか？」 という質問の場合は対象外です（その場合は doc-diagnostic を使用します）。スタイルレビューでは、ドキュメントを作成すべきかどうかは判断しません。そのドキュメントが掲載に値することを前提とし、文章、構成、Markdown が整っているかを確認します。

レビューの実施方法

2 回に分けて確認します。2 つを混在させないでください。構文違反とスタイル違反では、アーキテクトが異なる見方をするため、混同すると回答が分かりにくくなります。

パス 1 — 構文（必須修正）

ファイルを先頭から末尾まで確認します。構文規範に違反する構成（ATX 形式が求められる場所での setext 形式の見出し、フェンスで囲まれていないコードブロック、ブロック要素の前後に空行がない、番号付きリストで . ではなく ) を使用している、など）を見つけたら、指摘を 1 件ずつ出します。

Line N:
  Original: <verbatim line(s)>
  Layer:    syntax
  Rule:     <one-line rule from references/syntax-canon.md>
  Rewrite:  <corrected line(s)>
  Apply?    yes / no / adjust

次の指摘を出す前に、アーキテクトの返答を待ちます。まとめて修正してはいけません。構文の指摘は、必ずスタイルの指摘より先に行います。

パス 2 — スタイル（修正を推奨）

ファイルを再度確認します。スタイルオーバーレイに違反する項目（ドキュメントのタイトルに H2 より上位の見出しを使用している、長いドキュメントに [TOC] ディレクティブがない、例外に該当しない箇所で文章の行が 80 文字を超えている、「こちら」のように内容が分かりにくいリンクテキスト、参照リンクの定義が使用箇所から遠く離れている、複数の親見出しの下に「概要」のような汎用的な小見出しが繰り返し使われている、など）があれば、Layer: style を付けて同じ形式で指摘します。

スタイルの確認は提案であり、強制ではありません。アーキテクトは、理由を示さずにどの指摘も却下できます。このルールは独自の見解に基づくものであり、規範ではありません。合理的な意見の相違は認められます。指摘したら次に進みます。

承認された指摘の適用

2 回の確認が終わったら、承認された書き換えのみを 1 回の編集パスで適用します。ファイルに監査用マーカーを残してはいけません。[reviewed] のスタンプも付けません。差分が監査記録になります。

2 つの層 — クイックリファレンス

詳細なルールは references/ にあります。以下の概要では、指摘の大半を占める違反を取り上げます。

構文（必須修正）—クイックリファレンス

構成要素	ルール
見出し	ATX（#～######）を使用し、# の後にスペースを入れ、前後に空行を置きます。
段落	空行で区切ります。インデントは付けません。
改行	行末の半角スペース2つは「議論の余地あり」です（スタイルオーバーレイを参照）。段落を分けることを推奨します。
強調	**太字**、*斜体*、***両方***。単語の途中ではアスタリスクを使います（アンダースコアでは正しく機能しません）。
引用ブロック	行頭に > を付けます。段落間の空行にも > を付けます。>> でネストします。
順序付きリスト	1. 2. 3. を使用します（) ではなくピリオド）。1から始めます。番号は省略してもかまいません。
順序なしリスト	- / * / + のいずれかを選び、リスト内では混在させません。
ネストされたリストの内容	4つのスペース（タブ1つ）分インデントします。リスト項目内のコードは8つのスペース（タブ2つ）分インデントします。
インラインコード	バッククォートを1つ使います。コードにバッククォートが含まれる場合は、2つ使います。
コードブロック	言語タグ付きのフェンス（```）を使います。インデント形式も有効ですが、推奨されません。
水平線	--- / *** / ___ を3つ以上、前後に空行を置いて単独行に記述します。
リンク	[テキスト](url)。オートリンクには <https://…> を使います。参照リンクのリンク先は別の場所で定義します。
画像	。代替テキストを必ず含めます。
エスケープ	次の文字の前に \ を付けます：`` \ ` * _ { } [ ] < > ( ) # + - . !
インラインHTML	使用できます。ブロックレベルのHTMLは空行で区切ります。タグにインデントは付けません。

例と、既知の未対応エッジケースを含む正式な仕様：references/syntax-canon.md。

スタイル（要修正）— クイックリファレンス

項目	ルール
H1	H1 は文書タイトルとして、ちょうど 1 つだけ使用します。以降の見出しは H2 から始めます。
見出しのスタイル	ATX 形式のみを使用します。setext 形式の下線は使用しません。
見出しの一意性	複数の親見出しの下で、単独の小見出し（「概要」「例」）を繰り返さないようにします。接頭辞を付けてください。
文書の骨組み	タイトル -> 任意の著者名 -> 1～3 文の導入 -> [TOC] -> ## トピック セクション -> ## 関連項目。
目次	ノート PC の画面 1 枚に収まらない文書には [TOC] を使用します。導入と最初の H2 の間に配置します。
行の長さ	80 文字。例外：リンク、表、見出し、コードブロック。長いリンクの前後のテキストも折り返します。
末尾の空白	付けません。2 つのスペースによる改行より、段落を分ける方法を優先します。
リスト	長い番号付きリストでは、簡易番号付け（1. を繰り返す形式）を使用します。短く順序が固定されたリストでは、通常の番号付けを使用します。データが一次元の場合は、表よりリストを優先します。
コードフェンス	必ずフェンスで囲み（```）、インデントは使用しません。言語を必ず指定します。シェルの改行は \ でエスケープします。
リンク	リポジトリ内のリンクには https://… より、リポジトリルートからの明示的なパス（/path/to/page.md）を使用します。../ による相対パスの遡りは避けます。
リンクテキスト	内容が分かるテキストにします。「ここ」「リンク」や URL の直接記載は避けます。
参照リンク	表で使用する場合、URL によって読みやすさが損なわれる場合、または同じリンク先が複数回登場する場合に使用します。定義は次の見出しの直前に記述します。
表	ひと目で確認できる二次元データにのみ使用します。文章をセルに入れないでください。セル内での折り返しはできません。
画像	必要最小限にします。必ず代替テキストを含めます。
大文字・小文字	製品、ツール、バイナリの表記を維持します（markdown ではなく Markdown）。
Markdown 内の HTML	使用を避けます。大きな表は一般的な例外です。

根拠を含む完全なガイドライン：references/style-overlay.md。

振り分け — このスキルの対象外

• 「この文書は必要ですか？」 -> doc-diagnostic（4 つの質問による診断）。
• 「この ADR は誠実に書かれていますか？」 -> adr-critique（「ADR ではないもの」チェックリストに照らした行ごとの監査。これは内容の監査であり、形式の監査ではありません）。スタイルチェックと ADR 批評は同じファイルに対して実行できますが、前提が覆るとスタイルの作業が無効になる可能性があるため、先に ADR 批評を実行してください。
• 「この文書はどこに置くべきですか？」 -> doc-diagnostic の代替案カタログ。
• 「文章は理解しやすいですか？」 -> 対象外です。このスキルが扱うのは Markdown の形式であり、文章の明瞭さではありません。想定読者にとって文章が不適切な場合は、doc-diagnostic の「読者」チェックを提案してください。

このスキルの対象外

このスキルが扱うのはMarkdown形式のみです。見出しのスタイル、リストのインデント、コードフェンスの言語タグ、リンク構文、行の長さ、その他のMarkdown-Guide／Google-style-overlayのルールセットを対象とします。以下は対象外です。

• 文章レベルのチェック — 用語の一貫性、インクルーシブな表現への置き換え、禁止表現、文体／時制／語調のルールは対象外です。こうした作業には、次のレイヤーとなる**Vale**（Markdown、AsciiDoc、reST、HTMLなどに設定可能なスタイルパックを適用する文章校正フレームワーク）を使用してください。Valeはこのスキルと相性よく併用できます。doc-masterはMarkdown形式を修正し、Valeは文章の用語をチェックします。doc-masterにはValeやそのルールパックは含まれていません。
• AsciiDoc／reStructuredText／org-mode／MDX — このスキルが対応するのはMarkdownのみです。ほかの軽量マークアップ言語にはそれぞれ独自の標準ルールがあるため、対応するツール（例：asciidoctor --safe-mode）を使用してください。
• スペルと文法 — 対象外です。このスキルに加えて、スペルチェッカー（codespell、hunspell、LanguageTool）を使用してください。代わりに使うのではありません。

厳守事項

• このスキルは指摘を提示しますが、まとめて書き換えることはありません。adr-critiqueと同様に、1回につき1件ずつ、行ごとに承認を得ます。
• 構文に関する指摘（「必須修正」）は、スタイルに関する指摘（「推奨修正」）より優先されます。順序を入れ替えないでください。
• このスキルが新しいルールを作ることはありません。すべての指摘で、references/syntax-canon.mdまたはreferences/style-overlay.mdに記載されたルールを引用する必要があります。ユーザーがスタイルに関する指摘に異議を唱えた場合は、ユーザーの判断を優先してください。このオーバーレイは独自の見解を含みます。
• 正準ルールと相反するプロジェクト固有の規約（例：プロジェクトで_underscore_による強調が標準化されている場合）は尊重します。相違点を指摘し、プロジェクトの規約に従ってください。

例

このREADMEをLintしてください。書式が乱れているように思います。 markdown-styleスキルを読み込みます。2段階でレビューします。まず構文に関する指摘（必須修正）、次にスタイルに関する指摘（推奨修正）を、行ごとの承認を得ながら1件ずつ提示します。

構文チェックを始めるため、ファイルパスを送るか、内容を貼り付けてください。

見出し行の下にある `===` は有効なMarkdownですか？ はい。これはsetext形式のH1で、有効なMarkdownです。ただし、スタイルオーバーレイ（およびGoogleのものを含む多くの最新スタイルガイド）では、ATX形式（`# Heading`）が推奨されています。setext形式の下線は「保守が面倒」で、H2より下のレベルには対応できず、ファイルをざっと確認した際に見出しレベルがわかりにくくなるためです。

推奨事項：===を単一の#に置き換えてください。ファイルを指定していただければ、（意味を変えずに）構文上同等の書き換えを行えます。

ドキュメントの見出しスタイルはどうなっていますか？ このスキルのデフォルトはATX形式（`#`、`##`、…、`######`）です。文書タイトルとしてH1を1つ使用し、それ以降の見出しはH2から始めます。見出しは文頭のみ大文字にし、その前後には空行を入れます。これはGoogleのMarkdownスタイルガイドに準拠しています。

プロジェクトにすでに別の規約（例：すべての見出しをH1から始める、または最上位タイトルにsetext形式を使う）がある場合はお知らせください。プロジェクトの規約を優先します。このスキルには独自の見解がありますが、プロジェクト固有のルールに従います。相違点を記録して、そのまま進めてください。

帰属表示

このスキルの2つのレイヤーは、一般公開されている次のスタイル資料をもとにしています。

• 構文の正準ルール — Markdown Guideの基本構文リファレンス（https://www.markdownguide.org/basic-syntax/）から要点をまとめたものです。ライセンスはCC BY-SA 4.0です。プラグインのルートにあるNOTICES.mdを参照してください。
• スタイルオーバーレイ — Googleの開発者向けドキュメントのMarkdownスタイルガイド（https://google.github.io/styleguide/docguide/style.html）から要点をまとめたものです。`google/styleguide`の一部で、ライセンスはApache License 2.0です。NOTICES.mdを参照してください。

このスキルでは、それぞれの資料から重要なルールを抽出しています。どちらの文書も原文のまま転載しているわけではありません。ユーザーが原文を必要とする場合は、リンクを案内してください。このスキルに長い抜粋を貼り付けないでください。