~/.claude/CLAUDE.md に、次の2つの記述があります。
| 出典 | 記述 |
|---|---|
| HTMLデザインルール 「クラス名」 | 章の連番は html2md が振る。HTML 側に番号を書かない（二重になる） |
| 学習資料の作成ルール 「ファイル名と番号」 | 番号体系は「資料番号.章番号」で通す。資料01の章は 01.1・01.2…、付録A1の章は A1.1… |
後者に従うと <h1>05.1 形が同じなら同じ型として通る</h1> と書くことになりますが、前者は「HTML 側に番号を書かない」と言っています。どちらかに従うと、もう一方に反します。
「二重になる」が実際に起きるかは未確認でした。
ルールの文言だけを読むと、<h1>05.1 章名</h1> が ## 1. 05.1 章名 のように出力される懸念があります。まずこれを実物で確かめました（2章）。
同じ規約で作られ、すでに Markdown 化まで済んでいる 20260822-powershell-pwsh-learn を確認しました。
<!-- docs/01-背景.html -->
<h1>01. PowerShell の生まれた経緯</h1>
<h1>01.1 Windows Command Shell の限界</h1>
<h1>01.2 なぜ PowerShell が必要だったのか</h1># docs/01-背景.md
# 01. PowerShell の生まれた経緯
## 目次
## 01.1 Windows Command Shell の限界
## 01.2 なぜ PowerShell が必要だったのか二重採番は起きていません。
HTML の h1 がそのまま Markdown の ## になっており、html2md が独自の連番を追加してはいません。見出しレベルが1つ下がっているだけです。
| 項目 | ルールの文言 | 実物 |
|---|---|---|
| 連番 | html2md が振る | 振っていない（h1 の文字列をそのまま使う） |
| HTML 側の番号 | 書かない | 書いてある（01.1 形式） |
| 出力 | 二重になる | 二重になっていない |
考えられるのは次の3つです。どれなのかを確認したいのが、この文書の第一の目的です。
学習資料は本編12章＋付録4本＋構成案の17ファイルに分かれています。各ファイルの中に3〜8個の章（h1）があり、ファイルをまたいで章を参照します。
<!-- 06-any-unknown-アサーション.html の中から -->
この扱いは <a href="08-型の絞り込み.html">08. 型の絞り込み</a> で詳しく扱います。
詳細は 08.4 を参照してください。ファイル内で閉じた連番では参照できません。
html2md が振る連番は ## 1. ## 2. のようにそのファイルの中だけで通用する番号です。「08.4 を参照」と書きたいときに、4. だけではどのファイルの4番目か分かりません。
| 場所 | 表記 | 例 |
|---|---|---|
| タイトルバーの h1 | 資料番号. タイトル | 08. 型の絞り込み |
| 章の h1 | 資料番号.章番号 タイトル | 08.4 型ガード関数 |
| 他ファイルからの参照 | 資料番号.章番号 | 「詳細は 08.4 で扱います」 |
この体系は PowerShell 学習資料でも同じです。2つの資料で共通の書き方になっています。
これが本題です。実物は既にこの動作をしているように見えますが、仕様として保証してほしいという要求です。
| h1 の内容 | 期待する Markdown |
|---|---|
08.4 型ガード関数 | ## 08.4 型ガード関数（そのまま） |
型ガード関数 | ## 4. 型ガード関数（連番を振る） |
判定は「h1 の先頭が数字・英数字の番号で始まっているか」で行えます。正規表現なら ^(?:\d+|[A-Z]\d+|ZZ)(?:\.\d+)?[ .] 程度です。
誤検出したときのために、明示的に切り替える手段があると安全です。
| 案 | 指定方法 | 評価 |
|---|---|---|
| A | コマンドライン引数（--keep-heading-number / --auto-number） | 推奨 |
| B | <section> の data 属性（data-number="keep"） | HTML が汚れる |
| C | 設定ファイル | 大げさ |
| プロジェクト | ファイル | 章 | 状態 |
|---|---|---|---|
| 20260822-powershell-pwsh-learn | 16 | 約70 | Markdown 化済み。現状で正しく出ている |
| 20260828-typescript-learn | 17 | 76 | これから変換する |
もし連番を振る実装が今後入ると、既存の資料が壊れます。
PowerShell 学習資料は既に Markdown 化が済んでおり、## 01.1 … の形で公開されています。連番を振る動作に変わると ## 1. 01.1 … になり、16ファイル・約70章すべてが影響を受けます。
要求が通らない場合、資料側で番号を外すことになります。その場合の影響です。
08.4 を外し、型ガード関数 だけにする（76箇所）この書き換えは避けたいため、要求1の確認を先にお願いします。