# Spec Page

> 説明書・仕様書・設計文書・調査報告を、HTML 1枚のページとしてまとめるスキル。 「何が入っているか」の一覧ではなく、**その対象の構造と、なぜそう決めたか**を伝える形式に落とす。 リポジトリのドキュメントページ（docs/index.html を GitHub Pages で配信）と、 単発の設計文書・報告書（Artifact として私的に共有）の両方を扱う。 markdown で足りる内容を HTML にはしない — 図・構造・体裁が意味を持つときだけ使う。 仕様をまとめたい / 設計文書を書きたい / ドキュメントページを作りたい / 調査結果を人に見せる形にしたい、というときに使う。

- Skill: `macotasu/spec-page` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add macotasu/spec-page`
- Raw SKILL.md: https://api.skillmd.com/api/skills/macotasu/spec-page/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: MacoTasu (https://skillmd.com/u/macotasu)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/macotasu/spec-page

---


# spec-page — 仕様書・説明書を HTML 1枚にまとめる

## まず問う: HTML にする理由があるか

**markdown で足りるなら markdown にする。** HTML を選ぶのは次のどれかが成立するときだけ。

- **構造を図で示したい** — 依存関係・役割の分離・処理の流れなど、箇条書きでは伝わらないもの
- **一覧ではなく読み物にしたい** — 上から読んで理解が組み上がる順序が要る
- **体裁が意味を持つ** — 識別子・状態・分類を書体や色で区別したい

「見栄えを良くしたい」は理由にならない。その場合 markdown のままのほうが速く、腐りにくい。

## 書く前に1文で決める

**このページの主張は何か。** 収録物の一覧ではなく、読者に1つだけ持ち帰ってほしいことを1文にする。
それが決まらないうちは書き始めない。主張が決まると、図に描くべきものと、削るべき節が決まる。

併せて**読者**を決める。半年後の自分か、初めて触る他人か、レビューする同僚か。
これで前提の書き方（何を説明し、何を省くか）が変わる。

## 構成の型

| 節 | 役割 | 必須 |
|---|---|---|
| **マストヘッド** | 名前・主張の1文・前書き（何で、何のためか） | ✅ |
| **本体** | 対象に応じた節。一覧・手順・比較など | ✅ |
| **構造の図** | 主張を1枚で示す。HTML を選んだ理由がここに現れる | 推奨 |
| **決定の記録** | **なぜそう決めたか**。結論ではなく理由を残す | ✅ |

### 決定の記録が、この形式の核

半年後に腐るのは結論ではなく**理由**。「なぜ2つに分けたのか」「なぜこの置き場なのか」が失われると、
同じ検討をやり直すか、理由のない制約として温存される。次の条件に当てはまる決定だけを残す。

- 後から見て**不自然に見える**もの（合理的な理由があるのに、結果だけ見ると遠回りに見える）
- **一度別の結論を出してから変えた**もの。変えた理由ごと書く
- **やらないと決めた**もの。やらない理由は特に失われやすい

逆に、自明な決定は書かない。全部書くと埋もれて、結局どれも読まれない。

## 体裁の規約

- **識別子は等幅に固定する** — プラグイン名・ファイル名・コマンド・設定キー。名前が識別子であることを
  書体で示す。本文中の強調（`<strong>`）とは役割が違うので混ぜない
- **罫線と余白で律動を作る** — カードを並べない。文書は読み物であって、ダッシュボードではない
- **型の階層を決めて守る** — 見出し・本文・注記・データの4役に、それぞれ書体と級数を割り当てる
- **構造が情報を担うときだけ構造を足す** — 番号付きマーカーは、本当に順序が意味を持つときだけ。
  そうでなければただの装飾になる
- **色は意味に割り当てる** — 状態（成功・警告・失敗）に色を使うなら、アクセント色とは別系統にする

## 公開前チェック（必須）

同梱の [`reference/publish-checklist.md`](reference/publish-checklist.md) を**実行する**。
読んで想像するのではなく、実際にブラウザで開いて確かめる。

とくに `<meta charset="utf-8">` の欠落は、**プレビュー環境では露見せず配信環境で初めて文字化けとして出る**。
構造検査だけでは捕まらない。

## 配信の2経路

### A. Artifact（試作・私的共有）

設定ゼロで、既定はプライベート。**まずここで見た目を確定させる**のが安い。
単発の設計文書・調査報告は、これで完結してよい。

制約: リポジトリと紐づかない。git で版管理されない。公開ドキュメントの正式な置き場には向かない。

### B. リポジトリの `docs/` ＋ GitHub Pages（版管理・公開）

**リポジトリの説明書はこちら。** コードと同じ PR でドキュメントも直せるので、実装とページがズレない。

```bash
# public リポジトリなら無料・ビルド不要
gh api -X POST repos/<owner>/<repo>/pages \
  -f "source[branch]=main" -f "source[path]=/docs"
```

- **配信元は `/`（リポジトリルート）か `/docs` の2択**。任意のフォルダは選べない。ルートに
  `index.html` を置くのはノイズなので **`/docs` 一択**
- **`gh-pages` 別ブランチにしない** — ドキュメントの更新が別コミットになると「実装を変えたのに
  ページが古い」という腐り方を招く。同じ PR で直せることが最大の利点
- **`docs/.nojekyll` を置く** — Jekyll 処理をスキップする。`_` 始まりのファイルが無視される、
  `{{ }}` や `{% %}` が展開される、といった**原因の見えにくい壊れ方**を恒久的に塞げる
- **README の冒頭からリンクする** — リポジトリの入口は markdown しかレンダリングされないので、
  README は残る。HTML はその補助

**両方を使う場合、同じファイルを指す。** Artifact 用と Pages 用で別ファイルを持つと必ず片方が腐る。
`docs/index.html` を書いて、それを Artifact として publish し、良ければそのまま Pages に載せる。

### 閲覧を限定したいとき

個人アカウントの GitHub Pages に**閲覧制限はかけられない**（Organization ＋ Enterprise Cloud のみ）。
public リポジトリなら Pages も公開される。限定したいなら Artifact（既定プライベート）を使う。

## 作業の順序

1. 主張を1文で決める。読者を決める
2. 構成を決める（上の型）。図に描くものを決める
3. 書く。**実データ・実名で書く**（プレースホルダで組まない）
4. `reference/publish-checklist.md` を実行する
5. Artifact として publish し、実際に開いて確認する
6. リポジトリのドキュメントなら `docs/` に置き、`.nojekyll` を添えて Pages を有効化、README からリンク