# Kuroco Spec Writer

> Kurocoサイトの実設定を Admin MCP 経由で読み取り、Markdown + Mermaid の現況仕様書（as-built ドキュメント）を生成する読み取り専用スキル。設定の変更は一切行わない。コンテンツ定義（項目表・ER図）・API一覧・認証と会員グループ・承認ワークフロー・カスタム処理/バッチ・フォーム・CSVテーブル・サイト定数・メールテンプレートを1定義=1ページで出力し、OpenAPI 3.1.0 定義（api-export_openapi）とコンテンツ定義の生レスポンス（topics_group-get）を schema/ に同梱、付属スクリプトで PDF + zip にも変換する。編集済み仕様書をサイトへ反映する差分解釈ルールも定める（書き込みは他スキルに委譲）。「仕様書を作って」「設計書・引き継ぎ資料・納品ドキュメントにまとめて」「ER図を作って」「OpenAPI定義をエクスポート」「仕様書を反映して」など、既存サイトのドキュメント化と仕様書の反映依頼で使用。

- Skill: `diverta/kuroco-spec-writer` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add diverta/kuroco-spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diverta/kuroco-spec-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: diverta (https://skillmd.com/u/diverta)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/diverta/kuroco-spec-writer

---


# Kuroco 仕様書ジェネレーター（Admin MCP）

## 概要

Admin MCP の**読み取り系ツールのみ**でKurocoサイトの実設定を収集し、
[references/template.md](references/template.md) の構成で Markdown + Mermaid の仕様書一式を生成する。
実装（実設定）を一次情報にするため、手書きの仕様書と違って現物と乖離しない。

| 本スキルの範囲 | 範囲外 |
|--------------|-------|
| 実設定からの現況仕様書の生成（主要章＝コンテンツ定義・API・認証・ワークフロー・カスタム処理・フォーム＋そのサイトで使われている他モジュール） | 設定の変更（**本スキルでは行わない**。変更は `/kuroco-admin-mcp` に切り替え、ユーザー承認のうえ実施） |
| ER図・シーケンス図・状態遷移図・フローチャートによる構造の可視化 | セキュリティ観点のリスク判定（→ `/kuroco-security-audit`） |
| 機械可読な定義ファイルの同梱（API の OpenAPI 3.1.0 と、コンテンツ定義の生レスポンス。→ [機械可読な定義ファイル](#機械可読な定義ファイルの保存)） | 定義ファイルを使った他サイトへの複製・移行（読み取って保存するところまで。投入は `/kuroco-content-structure`） |
| PDF + zip への変換（[scripts/build-pdf.mjs](scripts/build-pdf.mjs)、ローカル実行環境のみ） | フロントエンド実装コードの仕様化（リポジトリがあればコードから別途起こす） |
| 編集された仕様書の解釈と差分計画の提示（→ [仕様書からの反映](#仕様書からの反映往復運用)） | 反映の書き込み実行（`/kuroco-admin-mcp` 等の規約・承認フローに従う） |

> **最小フロー:**
> 1. スコープの合意（対象サイト・読者・出力先・PDF要否）
> 2. `whoami` で接続コンテキスト確定
> 3. 使われているモジュールの判定と設定の収集（読み取り専用・並列可）
> 4. テンプレートに沿って生成 + 機械可読な定義ファイルの保存 → 検品 → （任意で）PDF化

---

## 前提: 接続

Admin MCP の接続・認証・スコープ付きURLの仕様は `/kuroco-admin-mcp` を参照。本スキルでは以下だけ守る。

- **`/readonly` 付きのスコープURLを推奨する。** 書き込み系ツールが一覧に出ないため、事故が構造的に防げる
  ```
  https://{site}.g.kuroco.app/direct/rcms_api/admin_mcp/x/all/readonly
  ```
- 仕様書は横断的にモジュールを見るため、スコープは `all` が適切なことが多い
- 接続済みサーバが書き込み可能なスコープの場合でも、**本スキル実行中は読み取り系ツールしか呼ばない**

---

## 出力構造

**1定義=1ページの分割構成**を既定とする。1ファイルに全部を入れると長くなりすぎて読めない。

```
spec/                      # 出力先ディレクトリ（Step 1 で合意する）
├── README.md              # 目次・サイト概要・全体構成図（flowchart）
├── contents/
│   ├── _index.md          # コンテンツ定義一覧表 + ER図（erDiagram）
│   └── {ページキー}.md      # 1定義 = 1ページ（概要・項目表・公開制御・関連API）
├── functions/
│   ├── _index.md          # カスタム処理・バッチ一覧表
│   └── {static_sysnm}.md  # 1処理 = 1ページ
├── api.md                 # APIエンドポイント一覧
├── auth.md                # 認証・会員グループ（sequenceDiagram）
├── workflow.md            # 承認フロー（stateDiagram-v2）※フロー未使用なら作らない
├── forms.md               # フォーム一覧 ※フォーム未使用なら作らない
├── {module}.md            # 上記以外で使われているモジュールの一覧表（Step 3 で判明した分だけ）
└── schema/                # 機械可読な定義ファイル（人間向けの章ではなく、機械可読の原本）
    ├── openapi/
    │   └── api{api_id}_{api名}.json  # api-export_openapi の OpenAPI 3.1.0
    └── contents/
        └── {ページキー}.json        # topics_group-get のレスポンス（項目定義の原本）
```

固定の章立てではない。**使われているモジュールは Step 3 の件数確認で決まる**ので、
CSVテーブル（マスタデータ）・サイト定数・メールテンプレート等があればページを足す。

各ページの雛形と記載項目は [references/template.md](references/template.md) が正。

**分割の判断基準:**

判定軸は「**使われているか**」と「**対象範囲内か**」の2つ。片方だけで決めない:

| | 対象範囲内 | 対象範囲外 |
|---|---|---|
| **使われている** | ページを作る（下の粒度表に従う） | **単独ページを作らない。** モジュール一覧に「存在するが対象外」の1行で載せる。単独ページを与えると、範囲内の要素と誤読される |
| **使われていない** | ページを作らず、目次に「未使用」と1行 | 目次に「対象範囲外（今回未収集）」と1行。**未使用とは書かない** |

ページの粒度:

| 対象 | 扱い |
|------|------|
| コンテンツ定義・カスタム処理/バッチ | **常に1件=1ページ**。ただし該当が3件以下なら `_index.md` に統合してよい（ファイルを増やすほうが読みにくい）。**統合しても、ページキーの対応表と項目表は残す**——消えると往復運用で解決先が無くなる。関係が1本も無いときだけER図を省き、省いた理由を1行書く |
| API一覧・認証・承認フロー・フォーム・その他モジュール | **常に1ファイル**（サイト全体で1つの関心事）。件数が多く定義まで要るモジュールだけ contents/ と同様に分割する |

### ページキー（ファイル名・図のノード名）の決め方

**Kuroco のコンテンツ定義に ASCII 識別子は存在しない。** 持っているのは `topics_group_id`（数値）と
`group_nm`（多くは日本語）だけで、`ext_slug` は**項目**の識別子であって定義の識別子ではない。
そのためファイル名とER図のノード名には、仕様書側で採番した**ページキー**を使う。

- **形式は `tg{topics_group_id}_{名前}` で固定する**（例: `tg12_product`）。名前部分は仕様書側で決めた便宜名で、
  実体を指せるのは `topics_group_id` だけ——**必ず含める**ことで、ファイル名・図のノード名・`schema/` の
  ファイル名のどれを見ても実定義に辿り着け、一意性も `topics_group_id` が保証する
- 名前部分は次の優先順で決める: ①その定義を返すAPIエンドポイントのパス末尾（`/rcms-api/3/requests` → `tg7_requests`）
  ②`group_nm` の英訳・ローマ字（`購買申請` → `tg7_purchase_requests`）。どちらも決まらなければ `tg{topics_group_id}` だけでよい
- ASCII 小文字 + `_` のみ。Mermaid のノードIDとファイル名で同じ文字列を使う
- **名前部分は仕様書内の便宜的な名前であり、Kuroco 側の設定ではない**（実値は先頭の `topics_group_id` だけ）。その旨を
  contents/_index.md の対応表の見出しに1文で書き、対応表には `topics_group_id` の列も置く。
  書かないと読者が実設定の識別子と誤読し、往復運用ではキー変更が「リネーム依頼」と誤解される
- **ID を含める規則は他リソースにも揃える。** `schema/openapi/` のファイル名は `api{api_id}_{api名}`。
  カスタム処理・バッチは実識別子（`static_sysnm`）があるので採番せずそのまま使う
- **採番するのはページを持つ定義だけ。** 参照先として名前を挙げるだけの定義（対象範囲外など）にはページキーを振らず、`topics_group_id` と名称で示す

---

## 手順

### Step 1: スコープの合意

実行前にユーザーへ確認する（推測で始めない）:

1. **対象サイト** — 接続済みAdmin MCPサーバが複数ある場合はどれか
2. **対象範囲** — サイト全体（既定）か、一部の機能・定義だけか。依頼文で範囲が絞られていれば従う
3. **読者と詳細度** — 開発者向け（設定値・識別子まで記載。既定）か、非エンジニア向け（業務の言葉中心、設定値は要点のみ）か
4. **出力先ディレクトリ** — 既定は作業ディレクトリ直下の `spec/`。既存ファイルがある場合は上書き前に内容を確認する
5. **PDF + zip が必要か** — 必要なら Step 6 まで実施（ローカル実行環境で Chrome が必要）

**部分スコープのときの縮退ルール**（章構成の既定はサイト全体前提なので、明示的に縮退させる）:

- `_index.md` の一覧の母集団は**対象範囲だけ**。サイト全体の一覧にしない
- 対象外の定義・処理は、参照されている場合のみ別表に分けて「対象外」と明記し、`topics_group_id` と名称だけを書く。**ページキーは振らない**（ページが無いキーは往復運用で解決先が無い）
- 対象外の章は「未使用」でも「未確認」でもなく**「対象範囲外（今回未収集）」**として README の目次に書く（下の状態区分を参照）
- 範囲を絞ってもサイト概要（README）と、対象定義が使っているAPI・認証は含める。単体では読めない文書になる

**ユーザーに聞けない場合（非対話実行等）は生成を止めない。** ただし**既定値は最下位**で、次の優先順で決める:

1. **依頼文の明示**（「引き継ぎ先は非エンジニア」→ 非エンジニア向け。既定値で上書きしない）
2. **文脈から確定できること**（接続済みAdmin MCPが1つ → 対象サイトはそれ）
3. **既定値**（対象サイトは `whoami` の `site`、詳細度は開発者向け、出力先は `spec/`、PDFなし）

採用した仮定と、それをどの根拠で決めたかを README.md の冒頭に「前提（未確認）」として列挙する。

### Step 2: `whoami` で接続コンテキストを確定する

**最初に呼ぶツールは `whoami`。** `site`（`site_key` / `env` / `site_url` / `api_url`）で対象サイトの取り違えを検出し、README のサイト概要・全体構成図の一次情報にする。`permissions` は「取得できた／できなかった」の切り分け根拠になる。

### Step 3: 収集対象の決定と収集

**章立てはツール一覧から導く。モジュールの一覧をこのスキルに持たない**——Admin MCP のツールは250超あり、
列挙した表は必ず漏れて古くなる。網羅性はツール一覧側に担保させる。

**部分スコープのときは走査も縮退させる**（Step 1 の縮退ルールと揃える）。サイト全体スコープなら下の1〜3を全モジュールに適用する。

「必要」の判定は**対象章の記述の真偽を左右するかどうか**で決める:

- **件数確認まで行う**: それが0件かどうかで対象章の書き方が変わるモジュール。例——承認フロー（「承認なし」と書けるか）、CSVテーブル（マスタ項目の参照先）、カテゴリ・タグ（分類セクションの有無）
- **叩かない**: 対象章の記述に影響しないモジュール。「対象範囲外（今回未収集）」とし、**未使用とは書かない**（叩いていないので断定できない）
- 判断に迷ったら叩く。読み取り1回のコストより、誤った「なし」の害が大きい

1. ツール一覧の `{module}-list` 系のうち**構成（定義・設定）を返すものだけ**を拾い、`cnt=1` で件数を確認する（`pageInfo.totalCnt`）。
   除外するもの: ログ・履歴・分析（`*_log-list` / `*_history-list` / `*_analytics-list` / `login_failed-list` 等）、
   実データ（`member-list` / `topics-list` / `inquiry_submission-list` 等。件数の確認以外に使わない）、
   使用量・課金（`usage-*`）。**これらは仕様書の対象ではない**（運用状況は `/kuroco-api-performance-review`、リスク判定は `/kuroco-security-audit`）
2. 1件以上あるモジュールは、既定で**一覧表1つ**を章に落とす（下の主要章に該当しないモジュールもここで拾える。
   例: `csvtable`（マスタデータ）・`site_const`・`mailtemplateedit`・`tag`・`magazine`・`comment_module`・`spider` 等）
3. 主要章だけは掘り下げる。**ツール名は接続中の一覧に実在する名前が正**で、以下は典型例。一覧にない名前を推測して呼ばない

| 章 | 典型的なツール | 掘り下げの要点 |
|----|--------------|--------------|
| README（概要・全体構成） | `whoami` / `site_setting-get` | `site`（site_key / env / site_url / api_url）・`limits` |
| contents/（コンテンツ定義） | `topics_group-list` → 各定義を `topics-describe`、足りない分だけ `topics_group-get` | **項目表は `topics-describe` で組める。** relation の参照先 `group_id`・`searchable`・項目グループの親子構造・定義レベル設定が要る定義だけ `topics_group-get` も呼ぶ（**`schema/contents/` に原本を残す方針なら全定義で必要**）。どちらのキーがどの列になるか、`topics-describe` が返さない4つの詳細は [references/field-mapping.md](references/field-mapping.md) が正。**呼んだレスポンスは項目表を書いたあとも捨てず `schema/contents/` に保存する**（→ [機械可読な定義ファイル](#機械可読な定義ファイルの保存)） |
| api.md（API一覧） | `api-list` → `api_uri-list`（`uri_data_only=true`）＋ API ごとに `api-export_openapi` | 認証方式は `config.security`、CORSは `cors`。**`model_method_params.topics_group_id` がそのエンドポイントの対象定義**（「対象」列の根拠）。`model_classpath`+`model_method` / `summary` / `cache_settings` / `open_flg`。**`api-export_openapi`（`api_id` 必須 / `format` は `json` 既定・`yaml` 可）は OpenAPI 3.1.0 をそのまま返すので、パラメータ・レスポンススキーマは一覧表に転記せず `schema/openapi/` に保存する**（→ [機械可読な定義ファイル](#機械可読な定義ファイルの保存)） |
| auth.md（認証・会員グループ） | `group-list` / `site_setting-get` | `super_flg`（1=特権）・`cnt`（所属人数）・`limited_ip`。`group_kbn` は管理権限の設定値（**妥当性判定はしない**→ security-audit） |
| functions/（カスタム処理・バッチ） | `custom_function-list`（**`columns` 指定必須**）/ `batch-list` | 識別子は `static_sysnm`、トリガーは `trigger_sysnm` |

それ以外のモジュールで一覧表以上の詳細が必要かは、読者と用途から判断してユーザーに確認する。
モジュール固有のフィールドの意味は `/kuroco-docs` と各ツールの `inputSchema`・レスポンスの
`*_vectors`（例: `api-list` の `api_config_vectors.security.options` にキー→日本語ラベルの対応が入る）が正。

項目表の列と読み取りキーの対応（`topics-describe` の `field_map` / `topics_group-get` の `formData` の
どちらからでも組める）は [references/field-mapping.md](references/field-mapping.md) が正。
**推測で埋めず必ず参照する**——キー名から意味が読み取れず、往復運用の精度が項目表に依存する。

収集時のルール:

- **読み取り系ツールのみ**を使う。`create` / `update` / `delete` / `bulk_*` は一切呼ばない
- 独立した読み取りは複数のtool callを同時に発行して並列実行してよい
- 一覧取得は `cnt` で件数を制限し、`pageInfo.totalCnt` で総数を把握してから必要分だけ取る（`totalPageCnt` が2以上ならページを送る。1ページ目だけ見て「全部」と書かない）
- **呼ぶ前に `inputSchema` で絞る引数（`columns` / `cnt` / `*_only`）を確認し、使えるものは使う。** 仕様書に要るのは定義であって本文・ソースではない。実測で大きかった例:
  - `custom_function-list`: 既定で Smarty ソース全文（`contents`）を全行分返す。`columns` で `static_id` / `subject` / `static_sysnm` / `trigger_sysnm` / `open_flg` / `static_category_id` / `memo` に絞る
  - `api_uri-list`: `uri_data_only=true` を付ける（付けないとエンドポイントごとの全パラメータ定義が付く）
  - `topics_group-get`: 絞る引数が無く、`latestRow` と `formData` が同内容の二重返却＋Smartyテンプレート（`search_template_*` / `custom_css` / `custom_js`）を含む。**絞れないツールは1件取得したらそのページを書き切ってから次を取る**（全件を溜めてから書き始めない）
- **モジュールの状態は4つに区別する。**「ページが無い」理由が読者に伝わらないと、全部「機能が無い」と読まれる
  - `list: []` + `totalCnt: 0` かつ `errors: []` → **未使用**（断定してよい。ページを作らず目次に「未使用」）
  - そのモジュールのツールが一覧に無い → **未確認（ツール不可視）**。スコープ・権限の影響を受けるため、機能の不在ではない
  - `errors` が空でない → **未確認（理由）**。0件と混同しない。成功扱いのレスポンスでも `errors` があればレコードは取れていない
  - ツールは見えているが**依頼範囲外なので呼んでいない** → **対象範囲外（今回未収集）**。「意図的に取得しなかった」ことを書く。黙って落とすと未使用と同じに見える
- **取得できなかった項目を黙って落とさない。** 権限不足・レスポンス過大など理由は何であれ、該当ページに「未確認」と理由を書く。書かないと読者には「存在しない」と伝わる
- 件数を載せる場合は `topics-list` を `cnt=1` + `columns=["topics_id"]` で呼び、`pageInfo.totalCnt` だけを読む（レコードの中身は仕様書に不要）

### Step 4: 仕様書の生成

[references/template.md](references/template.md) の雛形に沿って各ページを書く。生成の核になる方針:

- **各ページの先頭に `kuroco-spec` メタデータコメントを必ず入れる**（形式は template.md）。ユーザーが仕様書を編集してAIに反映を依頼する往復運用で、対象リソースのID解決に使う。HTMLコメントなので読者には見えない
- **そのページを書くために実際に呼んだツール名を記録する**——メタデータコメントの `tools` に必ず、開発者向け詳細度ならページ末尾の出典行にも。仕様書側に持たせるので、このスキルはモジュールの一覧を持たずに済み、サイトごとに正確な出典が残る。加えて:
  - 反映時の現況再取得で「どのツールを呼び直すか」が仕様書から分かる
  - 読者が原本（管理画面・API）を辿れる。設定値の出所が不明な仕様書はレビューできない
  - **書いていいのは実際に呼んだ読み取りツールだけ。** 呼んでいないツール名・反映用の書き込みツール名は書かない（裏取りがなく、ツール名は接続スコープで変わる）
- **設定の羅列ではなく、意図を復元する。** 設定値は根拠として括弧で併記する（開発者向け詳細度のとき）。
  コンテンツ定義の `secure_level` / `writer_groups` / `contents_type_cnt` 等を業務の言葉へ言い換える対応は
  [references/field-mapping.md](references/field-mapping.md) の第4節が正
- **ER図・図中のノード名は[ページキー](#ページキーファイル名図のノード名の決め方)、項目名は `ext_slug` をそのまま使う。** 図に日本語ラベルやコメントを混ぜない（見づらい）。ページキーと日本語名・`topics_group_id` の対応は図の直下の表で示し、その表から各ページへリンクする
- **明示的なリレーション項目が無くても、定義間の関係は復元する。** 共通のコード項目（`request_no` 等）で紐付けている設計は珍しくない。この場合は破線（`}o..o{`）で描き、「項目名の一致から推定」と図の外に明記する（実線＝リレーション項目による確定、破線＝推定）
- **選択肢は「キー: ラベル」で書く。** ラベルだけ書くと、往復運用で反映するときにキーを復元できず質問が必要になる（`status` の `draft: 下書き` のキー側がAPIに出る値）
- 図の使い分けは後述の[Mermaid の使い分け](#mermaid-の使い分け)。構文の型と落とし穴は [references/mermaid-patterns.md](references/mermaid-patterns.md) が正
- ページ間リンクはすべて相対パス（`contents/tg12_product.md`、`../api.md`）。PDF化スクリプトがページ内アンカーへ変換する
- 事実と推測を区別する。設定から確定できることは断定し、運用に依存すること（「おそらく〜用途」）は推測であることを明記するか書かない

#### 機械可読な定義ファイルの保存

Markdown の表は人が読むためのもので、**そのままでは再現・移行・差分の入力にならない**（型を日本語に訳し、
選択肢や繰り返しを要約している）。読み取った定義そのものも `schema/` に保存する。

| 保存するもの | 取得 | 保存先 |
|------------|------|-------|
| API の OpenAPI 定義 | `api-export_openapi`（`api_id` 必須。`api-list` で得た api_id ごとに1回） | `schema/openapi/api{api_id}_{api名}.json` |
| コンテンツ定義 | `topics_group-get`（定義ごと） | `schema/contents/{ページキー}.json` |

- 形式は `json`（`api-export_openapi` の既定）。`openapi_data` の中身だけをインデント付きで書き出す。ユーザーが yaml を求めたときだけ `format:"yaml"`（文字列で返る）
- **保存はページを書く代わりにならない。** raw があるからといって項目表・ER図・エンドポイント一覧を省かない。省いた時点で読める仕様書ではなくなる
- **加工しない。** キーの並べ替え・型の翻訳・不要に見えるキー（`custom_css` / `search_template_*` 等）の削除をしない。原本であることが唯一の価値で、要約は Markdown 側の仕事。取得済みのレスポンスを書き出すだけなので追加の読み取りコストは無い
- **秘密情報だけは Markdown と同じ基準で伏せる**（Step 5 の 5）。該当キーの値を `"***"` に置換し、伏せたキー名を対応ページか README の注記に書く。**黙って消さない**
- 取得できなかったものは**ファイルを作らない。** 対応するページに「未確認（理由）」と書く。空ファイル・途中までのファイルを置くと、後から原本として使われる
  - `api-export_openapi` が接続中の一覧に無い（`rcms_api` モジュールを含まないバンドル）なら「未確認（ツール不可視）」。OpenAPI 定義が存在しない証拠ではない
- **参照している側のページに1行書く。リンクではなくコードパスで書く**（`.md` 以外の相対リンクは PDF 化後に辿れない）。
  パスは出力先ディレクトリ（`spec/`）からの相対で統一する——ページの階層ごとに `../` の数が変わると読み手が迷う

  ```markdown
  > 機械可読な定義: `schema/contents/tg7_purchase_requests.json`（`topics_group-get` のレスポンス）
  ```

- 生成日時点のスナップショットなので、Git 管理下に置くと往復運用の3者比較（[references/apply-changes.md](references/apply-changes.md) の Step A）で機械的な差分が取れる
- zip には出力先ディレクトリごと含まれる（PDF には入らない。PDF は `.md` だけを結合する）

### Step 5: 検品

生成後、納品前に確認する:

1. **リンク切れ** — 全 `.md` 内の相対リンク先ファイルが存在するか
2. **Mermaid 構文** — 各図が [references/mermaid-patterns.md](references/mermaid-patterns.md) の落とし穴（日本語エンティティ名・未クォート記号）を踏んでいないか。PDF化する場合はスクリプトが実レンダリングで検証する
3. **網羅性** — Step 3 で取得した定義・処理・APIがすべてページか「未確認」記載のどちらかに落ちているか
4. **往復可能性** — 反映の依頼に耐えるか。①全ページに `kuroco-spec` コメントがあり `id` が実値か
   ②`tools` に実際に呼んだツール名が入っているか ③項目表の識別子列に空欄がないか
   ④選択肢が「キー: ラベル」形式か ⑤型が数値のまま残っていないか。
   ここを落とすと文書としては読めても反映できない
5. **秘密情報** — トークン・シークレット・APIキー・個人名・メールアドレスの実値が混じっていないか
   （設定値をそのまま転記すると `email_receive_address` や `admin_nm` の形で入り込む）。
   **`schema/` の定義ファイルも同じ基準で見る**——生レスポンスなので Markdown より混入しやすい
6. **機械可読な定義ファイル** — 取得できた API・コンテンツ定義の数だけ `schema/` にファイルがあり、
   JSON としてパースできるか。参照している側のページに保存先のパスが1行入っているか
7. **重複の集約** — 同じ未確認事項・同じ注記が複数ページに同一内容で出ていないか。
   分割の基準は「**値はページごと、判断と対処は集約ページに1回**」:
   - 各ページに書く: そのページ固有の実値（例: この定義で取得できなかった設定名とその値）と、集約先へのリンク
   - 集約ページ（README の未確認項目か関連する1ファイル）に1回書く: なぜ未確認なのか、どう確認すればよいか、影響範囲
   - 同じ説明文を各ページに複製すると、更新のたびに全ページを直すことになり必ず食い違う

### Step 6: PDF + zip への変換（任意）

```bash
node scripts/build-pdf.mjs spec/ -o dist/
```

- README.md の目次順に全ページを結合し、1ページ=1印刷ページ区切りでPDF化、Markdownソース一式と合わせて zip にする
- zip は出力先ディレクトリごと固めるので `schema/` の定義ファイルも入る。PDF に入るのは `.md` だけ
- **要件**: ローカル実行環境・Chrome/Chromium・ネットワーク接続（レンダラーをCDNから取得）・`zip` コマンド。claude.ai のコード実行コンテナでは動かないため、その場合は Markdown 納品までが本スキルの範囲
- Mermaid のレンダリング失敗は「どのファイルの何番目の図か」までエラー表示される。**エラーを残したままPDFを納品しない**
- Chrome がない環境では `--html-only` で単一HTMLまで生成できる（ブラウザで開いて手動印刷）

---

## Mermaid の使い分け

**置き場所はモジュール名ではなく「その実体がどこにあるか」で決める。** 状態遷移の実体がステータス項目なら、
承認フロー機能（approvalflow）が未使用でもその定義のページに図を置く——「機能が未使用だから図を描かない」は誤り。

**描くかどうかは「構成要素が揃って確定するか」で決める。** 状態遷移図なら状態と遷移の両方:

| 確定の度合い | 表現 |
|------------|------|
| 状態も遷移も設定・履歴定義から確定する | `stateDiagram-v2` を描く |
| 状態一覧は確定するが遷移は設定に無い（ステータス項目だけがある） | **図にしない。** 状態の一覧表＋どの操作でどう変わるかの箇条書きにし、遷移が設定から確定できないことを1行書く。推測の矢印を引くと、図は本文より「確定情報」として読まれてしまう |
| 遷移の一部だけ確定する | 確定部分のみ図にし、不明な遷移は図に描かず本文に「未確認」として列挙する |

| 図 | 使う場所 | 使いどころ |
|----|---------|-----------|
| `flowchart` | README（全体構成）、functions/ の各ページ | フロント⇄API⇄外部連携の全体像。処理の流れ。**分岐のない3ステップ程度の直列処理には使わない**（文章で足りる） |
| `erDiagram` | contents/_index.md | 定義間の関係。属性は主要項目とリレーション項目のみ（全項目は各ページの項目表が正） |
| `sequenceDiagram` | auth.md、外部連携のあるfunctionsページ | ログイン〜トークンの流れ、外部APIとのやり取り |
| `stateDiagram-v2` | 状態を保持している側。承認フロー機能を使っていれば workflow.md、ステータス項目や履歴定義でアプリ側に実装されていればその定義のページ | 下書き→申請→承認→公開の状態遷移 |

1つの図に詰め込みすぎない。目安を超えたら分割する（基準は [references/mermaid-patterns.md](references/mermaid-patterns.md)）。

---

## 仕様書からの反映（往復運用）

生成した仕様書は編集して「この仕様書どおりに変更して」と依頼できる文書として設計されている
（メタデータコメント・識別子の安定性・README の編集ルールはそのための仕掛け）。
反映を依頼されたら [references/apply-changes.md](references/apply-changes.md) のプロトコルに従う。要点:

1. **仕様書のスナップショットを現況とみなさない** — 現況を再取得し、編集後の仕様書・現況・（可能なら）生成時点の3者を比較する。仕様書生成後にサイト側で起きた変更（ドリフト）と編集が衝突していたら、反映せず先に報告する
2. **差分計画を提示して承認を得るまで書き込まない** — 行削除・型変更・識別子変更は破壊的変更として1件ずつ個別確認し、実行前に `site-backup` を取る
3. **書き込みは本スキルの範囲外** — 実行は `/kuroco-admin-mcp` / `/kuroco-content-structure` の規約に従う
4. **1件書いたら読み戻して照合する** — 成功応答は保存の証明にならない。食い違いが出たらそこで止めて報告する
5. **反映後は変更した章を再生成して同期する** — 同期しないと次回の反映で偽の差分が出る

編集の解釈ルール（行追加=新規作成、行削除=削除の**提案**、識別子変更=リネームと解釈せず確認、選択肢はキー基準、参考値=無視）の全表と、識別子からIDへの解決手順は apply-changes.md が正。**曖昧な編集は推測せず質問する。**

---

## 重要なルール

| ルール | 説明 |
|--------|------|
| **読み取り専用** | 本スキルの生成・差分計画では書き込み系ツールを呼ばない。反映の実行フェーズに入るときは `/kuroco-admin-mcp` 等に切り替え、改めて実行前確認を取る |
| **実値のみを根拠にする** | 取得できなかった設定をデフォルト値で埋めて「〜の設計」と書かない。未確認は未確認と書く |
| **秘密情報を書かない** | トークン・シークレット・パスワードの実値は仕様書に一切書かない（存在・件数・用途のみ）。仕様書は共有・納品される前提の文書であり、漏洩経路になる |
| **個人情報を取得しない** | 仕様書に必要なのは定義・設定であり、コンテンツやメンバーの実データではない。`member-list` 等の実データ取得は行わない。件数が必要なら `cnt=1` で `totalCnt` だけ見る |
| **識別子は原文どおり** | `ext_slug`・`static_sysnm`・エンドポイントパス・グループ名を勝手に英訳・リネームしない。実装と突き合わせる文書なので、識別子が1文字でも違うと価値が落ちる。**例外はコンテンツ定義の[ページキー](#ページキーファイル名図のノード名の決め方)のみ**——Kuroco 側に定義の識別子が存在しないため仕様書側で採番する。`tg{topics_group_id}_{名前}` 形式で実IDを必ず含め、採番したことを対応表に明記する |
| **課金意識** | 同じ情報を重複取得しない。ただし課金を理由に章や検品を省かない——網羅性が優先 |

---

## エラーハンドリング

接続・認証まわり（`400` / `401` / `403` / ツール拒否）の原因と対処は `/kuroco-admin-mcp` のエラーハンドリング節と同一。本スキル固有の扱いは以下。

| 症状 | 対処 |
|------|------|
| 一部モジュールのツールだけ見えない | スコープ不足の可能性。必要なモジュール名を挙げて `/x/all/readonly` での再登録を提案する。**見えない章は「未確認」として残し、生成を続行する** |
| 生成の途中で認証切れ | どの章まで収集済みかを報告して停止。再認可後は未収集の章から再開する（収集済みを取り直さない） |
| 拡張項目が1つも無い定義がある | `formData` に `ext_slug_1` 以降が現れない。基本項目（subject / slug / ymd / contents_type）だけの定義として項目表を書く。エラーと0件を混同しない |
| 収集の途中で文脈が足りなくなりそう | 定義ごとに「取得 → そのページを書き出す」を1サイクルにして進める。取得結果を溜めずに逐次書き出せば、残りの定義数に関係なく完走できる。**途中で打ち切るなら、未着手の定義名を README の「未確認の項目」に列挙する** |
| PDF化スクリプトが Mermaid エラーを報告 | 該当ファイル・図番号が表示される。[references/mermaid-patterns.md](references/mermaid-patterns.md) に照らして図を修正してから再実行。`--force` で無視して出力しない |

---

## 暫定回避策

**Kuroco 本体側の修正で解消する見込みのもの**をここに隔離する。恒久的な手順（上の各節）と混ぜない
——混ぜると、直ったあとも回避策が手順として残り続ける。**解消条件を満たしたらこの節から削除する。**

### `topics_group-get` のレスポンスがツールの出力上限を超える

- **症状**: 項目数の多い定義では `formData` と `latestRow` の二重返却＋Smartyテンプレート込みで 600KB を超え、レスポンス本文が返らずファイルに退避される
- **回避**: 退避ファイルを丸ごと読まない。`formData` から `ext_slug_N` / `type_N` / `limits_N` / `ext_group_loop_N` / `ext_parent_slug_N` / `options_N` だけを抜き出すスクリプトを書いて項目表に落とす（`options_N` は選択肢が数千件になることがあるので件数と先頭数件に切る）。退避ファイルの末尾にはツールの注意文が付くので、JSON は先頭オブジェクトだけを取り出してパースする
- **そもそも避ける**: [field-mapping.md](references/field-mapping.md) の4項目が要らない定義は `topics-describe` で済ませる
- **解消条件**: `topics_group-get` が退避されずにレスポンス本文を返すようになったら不要。**呼んでみれば分かる**ので、退避が起きなくなっていたらこの項目を削除する

---

## セキュリティ注意事項

- 仕様書はサイトの内部構造の一覧そのものであり、**閲覧範囲を意識して扱う**。出力先・共有先はユーザーの指定に従い、勝手に公開場所へ置かない
- 静的アクセストークンや外部サービスのAPIキーは、**存在と用途だけを書く**（例:「Slack通知用のincoming webhook をサイトシークレットで保持」）。実値・末尾数桁も書かない
- カスタム処理のソースコードを仕様書へ全文転載しない。処理概要・トリガー・外部連携先に要約する（全文はKuroco管理画面が正）
- 生成自体が管理操作ログに記録される。共有環境では実施をチーム内に周知するようユーザーに勧める

---

## アンチパターン

| やりがち | 問題 | 推奨 |
|---------|------|------|
| 設定値をそのまま表に並べて終える | 設定ダンプは管理画面を見れば済み、仕様書の価値がない | 業務の言葉で意図を復元し、設定値は根拠として併記する |
| ER図に日本語名・コメントで注釈する | 図が読めなくなる | 図は識別子のみ。対応表を図の直下に置く |
| 全ページを1ファイルに結合して出す | 長すぎて読めない・差分レビューできない | 分割構成が既定。PDFだけが結合形 |
| 直列3ステップの処理に flowchart を付ける | 図がノイズになり、本当に必要な図の価値も下げる | 分岐・並行・外部連携があるときだけ図にする |
| 取れなかった章を黙って省く | 読者には「その機能は存在しない」と伝わる | 「未確認」と理由を明記する |
| 全定義を取得してから書き始める | 大きい定義が数件あるだけで文脈が尽き、後半の定義が落ちる | 1定義ごとに「取得→ページ書き出し」で進める |
| `type_N` の数値（`35`）や `ext_option_N` の生文字列（`draft::default::下書き`）をそのまま表に貼る | 読者が読めず、設定ダンプ以下になる | 型名に訳し、選択肢は「キー: ラベル」に整形する |
| 出典（呼んだツール）を残さない | 設定値の出所が辿れずレビューできない。反映時も現況の取り直し経路が分からない | メタデータコメントの `tools` と出典行に、実際に呼んだツール名を残す |
| 出典に一般的なツール名を推測で並べる | ツールの可視性は接続スコープ次第で、呼んでいないツール名は嘘になる | 実際に呼んだものだけ。呼べなかったものは「未確認」側に書く |
| ページキーを実設定の識別子のように書く／ID を含めない名前だけのキーにする | 読者が実装と突き合わせようとして見つからない。往復運用ではキー変更がリネーム依頼と誤解される | `tg{topics_group_id}_{名前}` 形式で採番し、名前部分が仕様書内の便宜キーであることを対応表の見出しに明記する |
| 推測した用途を断定調で書く | 手書き仕様書と同じ「実態と乖離した文書」になる | 設定から確定できることだけ断定する |
| OpenAPI・`topics_group-get` の生レスポンスを読み捨てる | 表は要約なので、移行・再現・機械的な差分の入力にならない | `schema/openapi/` と `schema/contents/` に原本を保存する |
| 定義ファイルを添えたので項目表・エンドポイント一覧を省く | 人が読める仕様書でなくなる。JSON を読ませるなら仕様書を作る意味がない | 両方出す。要約は Markdown、原本は `schema/` |
| Mermaid エラーを残したまま納品 | 図が空白・エラー文字列になり文書全体の信頼が落ちる | Step 5 / Step 6 の検証を通してから納品する |

---

## 他スキルとの連携

| スキル | 使い分け |
|--------|----------|
| `/kuroco-admin-mcp` | 本スキルの前提（接続・認証・ツール探索）。仕様書で見つかった設定の修正、および[往復運用](#仕様書からの反映往復運用)の書き込み実行はこちらで承認を取って実施 |
| `/kuroco-security-audit` | 同じ読み取り専用型だが目的が違う。仕様書=構造の記述、監査=リスクの判定。納品前に併走させると良い |
| `/kuroco-app-builder` | 新規構築のワークフロー。構築完了後の納品ドキュメント作成に本スキルを使うと、実設定ベースの仕様書がそのまま出る |
| `/kuroco-content-structure` | 仕様書で可視化した構造を変更したくなったときの設計判断と、コンテンツ定義の作成 |
| `/kuroco-docs` | 各設定項目の公式ドキュメント。仕様書に根拠URLを添えるとき |