Kuroco Spec Writer

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

概要

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

最小フロー:

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 が正。

分割の判断基準:

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

ページの粒度:

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

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. 主要章だけは掘り下げる。ツール名は接続中の一覧に実在する名前が正で、以下は典型例。一覧にない名前を推測して呼ばない

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

項目表の列と読み取りキーの対応（topics-describe の field_map / topics_group-get の formData の どちらからでも組める）は 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 の雛形に沿って各ページを書く。生成の核になる方針:

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

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

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

• 形式は 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/）からの相対で統一する——ページの階層ごとに ../ の数が変わると読み手が迷う

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

• 生成日時点のスナップショットなので、Git 管理下に置くと往復運用の3者比較（references/apply-changes.md の Step A）で機械的な差分が取れる

• zip には出力先ディレクトリごと含まれる（PDF には入らない。PDF は .md だけを結合する）

Step 5: 検品

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

1. リンク切れ — 全 .md 内の相対リンク先ファイルが存在するか
2. Mermaid 構文 — 各図が 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 への変換（任意）

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）が未使用でもその定義のページに図を置く——「機能が未使用だから図を描かない」は誤り。

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

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

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

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

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

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

重要なルール

エラーハンドリング

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

暫定回避策

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 の4項目が要らない定義は topics-describe で済ませる
• 解消条件: topics_group-get が退避されずにレスポンス本文を返すようになったら不要。呼んでみれば分かるので、退避が起きなくなっていたらこの項目を削除する

セキュリティ注意事項

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

アンチパターン

他スキルとの連携