# AI レビューハブ サンプル(架空の EC システムの要件定義成果物) > AIDD の要件定義で使う AI レビューハブの見本です。正本(SSOT)の Markdown から生成した成果物を、状態・合意レベル・レビューのお願いつきで並べてお客様と合意をとります。各案件はこのファイルの URL を AI に渡して、ハブの構成・語彙・作り方を取り込んでください。ハブの入口は [お客様向けのハブ](https://showcase.gaipack.ai/ai-review-hub?view=external) です。(2026-10-13 時点・成果物 48 件) ## 読み方の注意 - 掲載している会社名・システム名・数値・人物はすべて架空です。ハブの構成と書き方の見本として読んでください。 - 成果物のリンクはブラウザで開くハブの画面です(ハッシュで画面を切り替える 1 ページのアプリなので、URL を取得しても中身は返りません)。AI が読むための要点はこのファイルに書いてあります。 - ID で引いてください。主な ID: 画面 SCR-<業務フェーズ>-NN/外部 IF IF-<連携先>-NNN/機能 FN-/業務ルール BR-/処理 PRC-/エンティティ ENT-NNN/未決事項 TBD-NNN/確認事項 CQ-NNN/ユースケース UC-<接点>-NN/業務フロー SCN-NN(段は SCN-NN-NN)/現行の業務フローの段 ASIS-NN-NN/システムの外の段 OFF-NN。ID はそれぞれ 1 か所だけで定義し、ほかの文書からは ID で参照します。 - 状態を見てください。お客様と合意をとる対象は「レビュー可能」か「確定」のものだけです。 - 未着手: まだ作っていない - 仮作成済: AI の初版。未検証 - 内部レビュー待ち: 社内のレビュー待ち - 対応中: 直している最中 - レビュー可能: お客様に内容を確認していただく下限 - 確定: お客様と合意済み - 参照資料: 参照用 - 合意レベルは成果物ごとに決めます。 - チェック: 載せて合意をとる。合意は文書ごとに 1 回 - チェック(形式のみ): 仕様書から自動で作る一覧・対応表。中身は元の仕様書で合意するので、形と載せ方だけ合意する - 参照: 載せるが合意はとらない - 載せない: 定例・メール・タスク管理ツールで扱う - 成果物には、作成の進みを表す状態と、何を合意するかを表す合意レベルとは別に、いまどの程度見ていただきたいかを表す 3 段のラベルを付けています。レビューの必要性が高いものほど、はっきりした色にしています。合意レベルが「参照」のものと、状態が「参照資料」のものは、参照用です。 - レビュー対象: 内容のレビューをお願いしたいものです(画面遷移図から開く画面モックを含みます) - 一部レビュー対象: 全体ではなく、成果物の下に添えた「ここだけ」の部分について、レビューをお願いしたいものです - 参照用: 気になったときに開くものです(レビューの対象ではありません)。成果物の下にレビューの場所を添えているものは、その内容のレビューをそちらでお願いします - 成果物の行の末尾の括弧に、状態・合意レベル・レビューのお願いを、その後に「ひとこと」(どこを見ていただくか・レビューの場所)を書いています。 - API 仕様書は要件定義の間はサンプルで、全行が仮置きです。電文・型・桁は基本設計で確定します。 - このサンプルは見せ方を伝えるデモで、画面を切り替える Web アプリとして作っています。案件で配信するハブは作りが違い、サードパーティのコードを含まない静的な HTML にします(下の「ハブの仕組み」の「動かすのに要るもの」と「セキュリティ」)。デモの作りを案件に持ち込まないでください。 - カードの説明の頭に「作成中」とあるものは、一部だけを書き方の見本として公開しているカードです。ほかの部分は作成中で、このファイルにも載っていません。 ## 自分の案件に取り込む 案件のリポジトリで作業している AI に、このファイルの URL を渡して次の順で進めてください。ハブは道具として配るものではなく、このサンプルを取り込み元にして案件ごとに作ります。 1. 正本を確かめる: 要件定義書・仕様書がリポジトリの Markdown にあることを確かめる。これが SSOT になる。文書を共有ドライブで管理する案件はハブの対象外。 2. 成果物一覧の表を作る: 列はグループ・カード・成果物名・状態・合意レベル・レビューのお願い・ひとこと・公開区分・形式・パス。下の「標準」10 枚のカードを起点にし、付録は案件で要るものだけ足す。状態・合意レベル・レビューのお願いは上の語彙だけを使う。 3. 生成と検査を作る: 下の「ハブの仕組み」に沿って、正本 → 生成 → 検査 → 配信の 4 段を案件のリポジトリに作る。どの正本からどの HTML を作るかの対応表は 1 か所に置き、生成物は直接編集しない。 4. 外部用は足し算で作る: 公開区分が「外部」の成果物と、そこから辿れるページだけを集めて配信用にコピーし、編集者向けの注記と社内向けの表記を落とす。 5. 案件の llms.txt を書く: 外部用のビルドで、このファイルと同じ形(見出し・引用の説明・読み方の注意・成果物の種類ごとの節)の llms.txt を配信のルートに書き、ハブの見出しから開けるようにする。リンク先は Markdown ではなく外部用の HTML にする。 6. スキルを作る: 下の「ハブの仕組み」の「スキル」に沿って、取り込み・反映、お客様に出す前の点検、プルリクエストの品質、生成・進捗のスキルを案件のリポジトリに作る。資料の取り込みは入口のスキルを 1 つにし、プルリクエストを作った直後のセルフチェックと独立レビューはフックで起動を促す。 7. 案件に合わせて置き換える: ID 体系・業務フェーズ・連携先・ロールは案件のものに置き換える。このサンプルの架空の名前や数値は持ち込まない。構成・見せ方・成果物も、お客様の要件やレビューの進め方に合わせて調整する。 ## 標準 1 プロジェクト計画書・WBS プロジェクトの進め方(プロジェクト計画書)と、作業の予定と状態(WBS)。計画書はご判断に要る点をまとめたエグゼクティブサマリーから読めます。(3 件) - [プロジェクト計画書・WBS — プロジェクト計画書(エグゼクティブサマリー)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/plan-summary): プロジェクト計画書のうち、ご判断に要る点(要点・スコープ・発注単位・マイルストーン・リスク・お願いしたいこと)をまとめた版。合意は詳細版でいただきます。(仮作成済・参照・参照用) ひとこと: 内容のレビューは、詳細版でお願いします(レビューの場所: プロジェクト計画書・WBS — プロジェクト計画書(詳細版)) - [プロジェクト計画書・WBS — プロジェクト計画書(詳細版)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/plan): プロジェクトの進め方(目的・範囲・日程と発注単位・体制・品質とテストの方針・レビューの進め方・リスク)。作業の予定と状態は WBS で見ます。(仮作成済・チェック・レビュー対象) - [プロジェクト計画書・WBS — WBS(要件定義〜基本設計)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/wbs): 作業の分解(WBS)と、期間・担当ロール・状態・依存。表とガントチャートの 2 通りで見られます。(仮作成済・チェック・レビュー対象) ## 標準 2 画面遷移図 要件定義の軸。ここから辿ります。画面の箱を押すと画面モックへ、モックから未決事項・外部連携へ移れます。(3 件) - [画面遷移図 — 商品管理](https://showcase.gaipack.ai/ai-review-hub?view=external#d/prd-sf): 商品管理の画面遷移(13 画面)。画面を箱、遷移を矢印で描き、箱を押すとその画面のモックへ移ります。(仮作成済・チェック(形式のみ)・レビュー対象) - [画面遷移図 — 受注・決済](https://showcase.gaipack.ai/ai-review-hub?view=external#d/ord-sf): 受注・決済の画面遷移(14 画面)。画面を箱、遷移を矢印で描き、箱を押すとその画面のモックへ移ります。(仮作成済・チェック(形式のみ)・レビュー対象) - [画面遷移図 — 出荷・配送](https://showcase.gaipack.ai/ai-review-hub?view=external#d/shp-sf): 出荷・配送の画面遷移(13 画面)。画面を箱、遷移を矢印で描き、箱を押すとその画面のモックへ移ります。(仮作成済・チェック(形式のみ)・レビュー対象) ## 標準 3 画面モック 画面仕様。画面イメージ・決まっている仕様・確認中の事項・使う外部連携を、画面ごとに確認できます。(5 件) - [画面モック — 商品管理](https://showcase.gaipack.ai/ai-review-hub?view=external#d/prd-sd): 商品管理の画面(13 画面)。画面ごとに、画面イメージ・決まっている仕様・確認中の事項・使う外部連携をモックで確認できます。(仮作成済・チェック・レビュー対象) - [画面モック — 受注・決済](https://showcase.gaipack.ai/ai-review-hub?view=external#d/ord-sd): 受注・決済の画面(14 画面)。画面ごとに、画面イメージ・決まっている仕様・確認中の事項・使う外部連携をモックで確認できます。(仮作成済・チェック・レビュー対象) - [画面モック — 出荷・配送](https://showcase.gaipack.ai/ai-review-hub?view=external#d/shp-sd): 出荷・配送の画面(13 画面)。画面ごとに、画面イメージ・決まっている仕様・確認中の事項・使う外部連携をモックで確認できます。(仮作成済・チェック・レビュー対象) - [画面モック — 主要画面一覧(選んだ理由・網羅の確認)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/major): 先にご確認いただく主要画面と、選んだ理由。観点ごとの理由と、連携先・ロール・業務フェーズを覆えているかを示します。(仮作成済・チェック・レビュー対象) - [画面モック — 画面の変更履歴](https://showcase.gaipack.ai/ai-review-hub?view=external#d/screen-history): 画面の仕様が変わった記録(日付・変わったこと・きっかけ・根拠)。各画面モックの「変更履歴」から、全画面の履歴として開けます。(仮作成済・参照・参照用) ひとこと: 変わった仕様は、各画面モックでレビューをお願いします ## 標準 4 業務仕様書 機能(FN)と業務ルール(BR)。判定条件・数値・閾値・異常系まで書きます。(3 件) - [業務仕様書 — 商品管理](https://showcase.gaipack.ai/ai-review-hub?view=external#d/prd-fn): 商品管理の機能(FN)と、判定条件・数値・閾値・異常系の業務ルール(BR)。(仮作成済・チェック・レビュー対象) - [業務仕様書 — 受注・決済](https://showcase.gaipack.ai/ai-review-hub?view=external#d/ord-fn): 受注・決済の機能(FN)と、判定条件・数値・閾値・異常系の業務ルール(BR)。(仮作成済・チェック・レビュー対象) - [業務仕様書 — 出荷・配送](https://showcase.gaipack.ai/ai-review-hub?view=external#d/shp-fn): 出荷・配送の機能(FN)と、判定条件・数値・閾値・異常系の業務ルール(BR)。(仮作成済・チェック・レビュー対象) ## 標準 5 処理仕様書 機能ごとの処理(PRC)と関与システム。シーケンス図は処理の表から作ります(タブで切り替え)。(3 件) - [処理仕様書 — 商品管理](https://showcase.gaipack.ai/ai-review-hub?view=external#d/prd-prc): 商品管理の機能ごとの処理(PRC)・関与システム・IF・画面・業務ルール。シーケンス図はこの表から作ります。(仮作成済・チェック(形式のみ)・レビュー対象) - [処理仕様書 — 受注・決済](https://showcase.gaipack.ai/ai-review-hub?view=external#d/ord-prc): 受注・決済の機能ごとの処理(PRC)・関与システム・IF・画面・業務ルール。シーケンス図はこの表から作ります。(レビュー可能・チェック(形式のみ)・レビュー対象) - [処理仕様書 — 出荷・配送](https://showcase.gaipack.ai/ai-review-hub?view=external#d/shp-prc): 出荷・配送の機能ごとの処理(PRC)・関与システム・IF・画面・業務ルール。シーケンス図はこの表から作ります。(仮作成済・チェック(形式のみ)・レビュー対象) ## 標準 6 データモデル エンティティ(ENT)・ER 図・属性・コード値。(1 件) - [データモデル — 論理 ER 図](https://showcase.gaipack.ai/ai-review-hub?view=external#d/dm-er): EC 基盤のエンティティ(商品・注文・顧客・在庫など)の主キー・外部キー・リレーションを示した論理 ER 図。属性定義とコード値、どの業務フェーズの処理・画面が何のデータを使うか(業務からの使われ方)もここから開けます。(レビュー可能・チェック・レビュー対象) ## 標準 7 外部 IF 一覧 IF の一覧と連携先システム、連携先ごとの連携データ項目。(7 件) - [外部 IF 一覧 — IF 一覧](https://showcase.gaipack.ai/ai-review-hub?view=external#d/if-list): IF(30 本)の一覧。方向・方式・区分・使う画面を示します。連携先システムとシステム構成図もここにあります。(仮作成済・チェック・レビュー対象) - [外部 IF 一覧 — 決済ゲートウェイ](https://showcase.gaipack.ai/ai-review-hub?view=external#d/dd-pay): 決済ゲートウェイとの連携データ項目(IF 8 本分)。項目名・型・方向・使う IF を一覧にしています。(仮作成済・チェック(形式のみ)・レビュー対象) - [外部 IF 一覧 — 配送業者 API](https://showcase.gaipack.ai/ai-review-hub?view=external#d/dd-dlv): 配送業者 APIとの連携データ項目(IF 6 本分)。項目名・型・方向・使う IF を一覧にしています。(仮作成済・チェック(形式のみ)・レビュー対象) - [外部 IF 一覧 — 倉庫管理システム](https://showcase.gaipack.ai/ai-review-hub?view=external#d/dd-wms): 倉庫管理システムとの連携データ項目(IF 6 本分)。項目名・型・方向・使う IF を一覧にしています。(仮作成済・チェック(形式のみ)・レビュー対象) - [外部 IF 一覧 — 基幹システム(商品マスタ)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/dd-mdm): 基幹システム(商品マスタ)との連携データ項目(IF 4 本分)。項目名・型・方向・使う IF を一覧にしています。(仮作成済・チェック(形式のみ)・レビュー対象) - [外部 IF 一覧 — メール配信サービス](https://showcase.gaipack.ai/ai-review-hub?view=external#d/dd-mal): メール配信サービスとの連携データ項目(IF 3 本分)。項目名・型・方向・使う IF を一覧にしています。(仮作成済・チェック(形式のみ)・レビュー対象) - [外部 IF 一覧 — チケット管理サービス(連携先未定)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/dd-tkt): チケット管理サービス(連携先未定)との連携データ項目(IF 3 本分)。項目名・型・方向・使う IF を一覧にしています。(仮作成済・チェック(形式のみ)・レビュー対象) ## 標準 8 API 仕様書 IF ごとの方式・認証・電文の項目・エラーと再送のサンプル。全値仮置きで、基本設計で確定します。(1 件) - [API 仕様書 — サンプル(30 本)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/api): IF(30 本)の API 仕様書のサンプル。Swagger 風に、メソッドとパス・認証・項目・エラーと再送を見られます。要件定義の間は全値が仮置きです。(仮作成済・参照・参照用) ひとこと: 全値が仮置きです。連携の中身は、外部 IF 一覧でレビューをお願いします(レビューの場所: 外部 IF 一覧 — IF 一覧) ## 標準 9 未決事項台帳 まだ決まっていないこと(TBD)。共通と業務フェーズごとの台帳です。画面モックの「確認中」から飛べます。(4 件) - [未決事項台帳 — 共通](https://showcase.gaipack.ai/ai-review-hub?view=external#d/tbd-cmn): 共通の未決事項(TBD)の問い・確定時期・影響する ID・確認事項との対応。TBD はここで定義します。(仮作成済・チェック(形式のみ)・参照用) ひとこと: 問いへのご回答は、確認事項リストでお願いします(レビューの場所: 確認事項リスト — 提出用) - [未決事項台帳 — 商品管理](https://showcase.gaipack.ai/ai-review-hub?view=external#d/tbd-prd): 商品管理の未決事項(TBD)の問い・確定時期・影響する ID・確認事項との対応。TBD はここで定義します。(仮作成済・チェック(形式のみ)・参照用) ひとこと: 問いへのご回答は、確認事項リストでお願いします(レビューの場所: 確認事項リスト — 提出用) - [未決事項台帳 — 受注・決済](https://showcase.gaipack.ai/ai-review-hub?view=external#d/tbd-ord): 受注・決済の未決事項(TBD)の問い・確定時期・影響する ID・確認事項との対応。TBD はここで定義します。(仮作成済・チェック(形式のみ)・参照用) ひとこと: 問いへのご回答は、確認事項リストでお願いします(レビューの場所: 確認事項リスト — 提出用) - [未決事項台帳 — 出荷・配送](https://showcase.gaipack.ai/ai-review-hub?view=external#d/tbd-shp): 出荷・配送の未決事項(TBD)の問い・確定時期・影響する ID・確認事項との対応。TBD はここで定義します。(仮作成済・チェック(形式のみ)・参照用) ひとこと: 問いへのご回答は、確認事項リストでお願いします(レビューの場所: 確認事項リスト — 提出用) ## 標準 10 確認事項リスト お客様にお尋ねしたいこと。未決事項台帳の TBD と対応します。指摘や回答は、チケットか Excel で受けます。(1 件) - [確認事項リスト — 提出用](https://showcase.gaipack.ai/ai-review-hub?view=external#d/cq): お尋ねしたいこと(CQ)と回答期限、対応する未決事項の一覧。提出用の版です。(仮作成済・チェック(形式のみ)・レビュー対象) ## 付録 一覧・索引 成果物の一覧と、成果物どうしの関連図、要件の対応表。(4 件) - [一覧・索引 — 成果物マトリクス](https://showcase.gaipack.ai/ai-review-hub?view=external#d/matrix): どの成果物を、どの合意レベルで確認いただくかの一覧。標準 10 種と付録の区分も示します。このハブの表から自動で作ります。(レビュー可能・チェック(形式のみ)・レビュー対象) - [一覧・索引 — 成果物関連図](https://showcase.gaipack.ai/ai-review-hub?view=external#d/deliv-map): 旧システムからのモダナイズで、どの成果物を何から作るかを段に並べた図。左の列は最初にいただくもの(現行システムの資料を含む)で、箱を押すと作るもとと使い先の線だけを強く出します。(仮作成済・参照・参照用) ひとこと: どの成果物をレビューしていただくかは、成果物マトリクスでご確認ください(レビューの場所: 一覧・索引 — 成果物マトリクス) - [一覧・索引 — 要件トレーサビリティ](https://showcase.gaipack.ai/ai-review-hub?view=external#d/trace): 要件から、機能・業務ルール・画面・IF までの対応と、進み具合。(仮作成済・チェック(形式のみ)・一部レビュー対象) ひとこと: 要件ごとの機能・業務ルール・画面・IF の列に抜けが無いかをご確認ください。「状態」の列はレビューの対象外です - [一覧・索引 — 機能一覧(全フェーズ)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/fn-all): 全業務フェーズの機能(FN)の一覧。定義は各フェーズの業務仕様書にあります。(仮作成済・チェック(形式のみ)・参照用) ひとこと: 機能の中身は、業務フェーズごとの業務仕様書でレビューをお願いします(レビューの場所: 業務仕様書 — 受注・決済) ## 付録 ワークフロー 業務フェーズごとの要件(業務フロー)。スイムレーン図へ移れます。(1 件) - [ワークフロー — ワークフロー(要件一覧)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/wf): 業務フェーズごとの要件(業務フロー)の一覧。担当ロールごとのスイムレーン図で、手順とシステム連携を確認できます。(レビュー可能・チェック・レビュー対象) ## 付録 ユースケースと業務フロー (作成中: お客様向けには、ユースケースは「EC サイト(購入者)」の接点だけを、書き方の見本として公開しています)接点(人が EC と関わる窓口)ごとのユースケースと、業務の成果が出るまでの時間に沿って接点・人・システムをまたぐ業務フローの 2 層。ユースケースの流れはシーケンス図で、業務フローは人ごとの列で見られます。(1 件) - [ユースケースと業務フロー — ユースケース・業務フロー一覧](https://showcase.gaipack.ai/ai-review-hub?view=external#d/scn): 接点ごとのユースケース(アクター・きっかけと前提・流れ・入力と出力)と、接点をまたぐ業務フロー。ユースケースの流れはシーケンス図で、図の上下にほかのユースケースからの入口と出口を、渡るデータと一緒に出します。業務フローは人(ロール)ごとの列に、やることを 1 段ずつ並べ、ユースケースが変わるところに区切りの行を入れます。(仮作成済・チェック・一部レビュー対象) ひとこと: ユースケースは「EC サイト(購入者)」の接点を、書き方の見本としてご確認ください(ほかの接点は作成中) ## 付録 横断の取り決め ロールごとの権限、全体にかかる前提・制約、用語、帳票・CSV、全画面に共通の画面の骨格。(6 件) - [横断の取り決め — 権限一覧](https://showcase.gaipack.ai/ai-review-hub?view=external#d/perm): ロール × エンティティ × 操作(CRUD)の権限定義。(仮作成済・チェック・レビュー対象) - [横断の取り決め — 共通前提制約](https://showcase.gaipack.ai/ai-review-hub?view=external#d/cn): 全業務にかかる前提・制約(CN-CMN)。(仮作成済・チェック・レビュー対象) - [横断の取り決め — 用語集](https://showcase.gaipack.ai/ai-review-hub?view=external#d/glossary): 業務用語・略語・英語対訳の定義。(仮作成済・参照・参照用) - [横断の取り決め — 帳票・CSV 一覧](https://showcase.gaipack.ai/ai-review-hub?view=external#d/reports): 出力・取込する帳票と CSV の一覧(種別・用途・主な項目・画面)。画面設計書の「帳票・CSV」の欄から作ります。(仮作成済・チェック(形式のみ)・レビュー対象) - [横断の取り決め — UI ガイドラインの画面骨格サンプル](https://showcase.gaipack.ai/ai-review-hub?view=external#d/ui-skeleton): 全画面に共通の骨格(ナビ・メニュー・一覧・操作)を、番号つきの吹き出しで示す見本。各画面のモックはこの骨格を省いて描いています。(レビュー可能・参照・参照用) - 横断の取り決め — メッセージ一覧(基本設計で作成。いまは各業務ルールの「条件 → 扱い」でご確認ください): 画面に出すメッセージの一覧。基本設計で作ります。(未着手・チェック) ## 付録 非機能要求・システム化方針 非機能の要求レベルと、システム化の方針。要件定義のうちに作ります(未作成のものは灰色で表示しています)。(3 件) - [非機能要求・システム化方針 — 非機能要求(当社のたたき案)](https://showcase.gaipack.ai/ai-review-hub?view=external#d/nfr): 可用性・性能・運用・セキュリティなどの当社のたたき案。合意したものではありません。直すときは打ち消し線で残し、「修正後」に書きます。(仮作成済・チェック・レビュー対象) - 非機能要求・システム化方針 — システム化方針書: アーキテクチャと製品利用の方針。要件定義のうちに作ります。(未着手・チェック) - 非機能要求・システム化方針 — AI 活用要件: 業務で AI を使う範囲と、人が確かめる箇所。要件定義のうちに作ります。(未着手・チェック) ## 付録 受領資料 お客様から受領した資料の要点。参照用で、合意の対象ではありません。(1 件) - [受領資料 — 現行業務フローの受領資料](https://showcase.gaipack.ai/ai-review-hub?view=external#d/ref-asis): 現行の業務フローについて受領した資料の要点と、現行業務と新システムの差分(AsIs / ToBe)。現行の業務フローは、新しい業務フローの段と見比べられます。(参照資料・参照・参照用) ## 付録 このハブについて このハブの作り方。正本からの生成・検査・配信の仕組みと、運用の手順。(1 件) - [このハブについて — このハブの作り方](https://showcase.gaipack.ai/ai-review-hub?view=external#d/how-it-works): 正本(SSOT)の Markdown から HTML を生成し、検査して配信する仕組みの要点。社内用・お客様向けのどちらでも読めます。(レビュー可能・参照・参照用) ## ハブの仕組み 付録「このハブの作り方」と同じ内容です。 ### 全体の流れ 1. 正本の Markdown(SSOT) — 唯一の真実の源。ここだけを直す 2. 生成 — スクリプトで HTML を作る 3. 検査 — プルリクエストごとに CI が回す 4. 配信 — main へのマージで公開 - 正本の Markdown が SSOT で、HTML はそこから生成する派生物。直接編集せず、正本を直して作り直す。 - どの段階でも検査に落ちたら配信せず、前の版が出たままになる。 - 生成物への直接の書き込みは、エディタやコーディングエージェントのフックで止める。 ### 正本と生成物 #### 対応表 | 生成物 | 正本 | 作るもの | | --- | --- | --- | | トップページ | 成果物一覧(Markdown の表) | ハブ生成スクリプト | | レビューのお願いの札と凡例 | 成果物一覧の「レビュー」「ひとこと」の列+ラベルの名前と説明(1 か所の定義) | ハブ生成スクリプト(成果物マトリクス・AI に読ませる目次も同じ定義から作る) | | 作成中の断り書き | 成果物一覧のカードの補足(お客様向けにだけ出す文) | お客様向けのビルド(カードの説明の頭に足す) | | 閲覧ページ | 各仕様書の Markdown | Markdown → HTML 変換スクリプト | | 画面モック | 画面設計書(1 画面 1 ファイル) | モック生成スクリプト | | 画面遷移図 | 画面設計書の流入・流出導線 | 遷移図生成スクリプト | | API 仕様書サンプル | 外部 IF 一覧と項目の辞書 | サンプル生成スクリプト | | 索引・要件番号逆引き | 仕様書全体の ID | ID 検査スクリプト(索引モード) | | 機能一覧(全フェーズ) | 業務仕様書の機能(FN) | ID 検査スクリプト(索引モード) | | 主要画面一覧 | 選んだ画面と理由(人が書く)+画面設計書から数えた数 | 主要画面の生成スクリプト | | 画面の変更履歴 | 業務フェーズごとの変更履歴 | モック生成スクリプト(画面ごとの行) | | 帳票・CSV 一覧 | 画面設計書の「帳票・CSV」の欄 | 帳票一覧の生成スクリプト | | テーブル一覧・データディクショナリ | エンティティ一覧と属性定義 | データモデルの生成スクリプト | | ユースケースと業務フロー | シナリオ定義(接点・ユースケース・つながり・システムの外の段・業務フロー)と処理仕様書の流れ | シナリオの生成スクリプト(ユースケースの流れはシーケンス図、業務フローは人ごとの列の図) | | 現行(As-Is)と新しい(To-Be)業務フローの見比べ | 受領資料の要点(現行の流れ)と、現行の段ごとの対応(同じ業務の段か、廃止とその理由) | シナリオの生成スクリプト(対応表と印を作る。新しく増える段は、どの現行の段からも指されない段として数える) | | 業務からの使われ方(データモデルのタブ) | 処理仕様書の処理の表の「データ」の列と、画面設計書の「データ」の行 | データモデルの生成スクリプト | | AI に読ませる目次(llms.txt) | お客様向けに出す成果物の一覧 | お客様向けのビルド(配信のルートに書く) | #### ルール - 対応表は 1 か所で管理する: 「どの正本から、どの生成物を、どのスクリプトで作るか」は 1 つの表だけに書く。 - 再生成もガードもその表を読む: 再生成のスクリプトも、直接編集を止めるフックも、同じ表を参照するので食い違わない。 - 生成物は直接編集しない: 直したいときは正本を直して再生成する。手動で対にするものは、相方を直し忘れないよう警告する。 ### 1 つの正本から 2 つの見せ方 #### 前提 - 文書は作り分けない: 画面遷移図や仕様書を、社内用とお客様向けで別々に作ることはしない。文書は 1 つの正本だけ。 - 同じページを集め分ける: 同じ正本から生成したページを、社内用はすべて、お客様向けは「外部」の印が付いたものだけを集めて配信する。 - 違うのは見せる範囲だけ: 差は、載せる成果物の範囲と、編集者向けの注記などの有無。 - 2 つとも配信する: 社内用もお客様向けも実際にデプロイする。お客様向けは社内用とは別のサイトとして配り、お客様には社内用の URL を渡さない。 #### 違い | 項目 | 作業ハブ(社内用) | AI レビューハブ(お客様向け) | | --- | --- | --- | | 中身 | すべての成果物 | 「外部」の印が付いた成果物と、そこから辿れる仕様書・画面モック | | 見た目 | 名前に「社内用」と入り、帯と配色が違う | 社内向けの印や注記が出ない | | 作り方 | 全体をそのまま配信用に写す | 印の付いたものだけを集める(足し算) | | 見る人 | 作業者 | お客様のレビュアー | | 配信先 | 社内用のサイト(社内のネットワークと認証の内側) | 社内用とは別のサイト(お客様に発行したアカウントだけが入れる) | | 配信のきっかけ | main へのマージで作り直して配信する | 同じマージで作り直して配信する。検査に落ちたら前の版のまま | #### 書き換え | 対象 | お客様向けの配信用コピーでの扱い | | --- | --- | | 編集者向けの注記 | 取り除く | | 社内のページへのリンク | 文字だけにする | | 画面設計書へのリンク | 同じ画面のモックへ張り替える | | 決定の記録への言及 | 「○月○日の打合せで決定」の形に言い換える | | 社内向けの語 | 機械で検出したら止める | ### 検査 | 検査 | 何を落とすか | | --- | --- | | 生成物のズレ | 正本と生成物が一致しない(一時領域で作り直し、バイト単位で比べる) | | 本文の集計値のズレ | 文書に書いた件数・合計と、実際の件数が合わない | | ID の重複・未定義参照・リンク切れ | 同じ ID の二重定義、定義の無い ID の参照、存在しないページへのリンク | | お客様向けへの社内表記の混入 | 編集者向けの注記・社内のパス・作業記録への言及など | | 生成時の表記崩れ | 見出しの重複、閉じていない強調、タグが文字のまま出ている、など | | 外部の読み込み・通信 | リンク以外のタグや CSS が外部を指している(スクリプト・スタイルシート・フォント・画像)、スクリプトが外部へ通信する | | スクリプトの混入 | テンプレートに無いスクリプトやイベント属性(onerror など)が、文書や図の取り込みで紛れ込んでいる | | 人が書いたものと数えた結果の食い違い | 主要画面の理由に書いた IF・覆えない連携先が、仕様書から数えた結果と合わない | | 書き方の決まりの違反 | 変更履歴の日付・画面 ID・きっかけ、帳票の種別が画面設計書の欄と合わない、シナリオの担当が決まらない段 | | ユースケースと業務フローの食い違い | ユースケースの流れに定義の無い処理がある、業務フローの段の処理がそのユースケースの流れに無い、ユースケースの並びの順が合わない、隣り合うユースケースをつなぐ渡るデータが無い | | 現行と新しい流れの対応の崩れ | 対応先の段が新しい業務フローに無い、廃止の段に理由が無い、差分表に無い業務領域を段に書いている、現行の業務フローが無い新しい業務フローがある | | 使われ方の読み落とし | 処理の表のデータの列や画面のデータの行に、データモデルに無いエンティティがある。使われ方の 3 つの区分の件数の和が、エンティティの数と合わない | | レビューのお願いの抜け・食い違い | お客様向けで未着手でない成果物にラベルが無い、一部レビュー対象に「どこを見ていただくか」が無い、合意レベルが参照なのにレビュー対象になっている、案内したレビューの場所がお客様向けに無い | | AI に読ませる目次の崩れ | 目次のリンク先が配信の範囲の外にある・切れている、社内向けの表記が混ざっている | ### 動かすのに要るもの | 観点 | 要件 | | --- | --- | | 生成物 | 外部ライブラリ・CDN を使わない単一ファイルの HTML。ファイルを直接開いても、静的ホスティングでも動く | | 生成スクリプト | 言語の標準ライブラリだけで動く。追加のインストールは不要 | | CI | プルリクエストごとに、配信と同じビルドを回して検査する | | 静的ホスティング | 社内用とお客様向けを別のサイトとして置き、それぞれに認証をかける。社内用は接続元を社内に限る | | 図 | ローカルで描画し、図の元データを外部サービスへ送らない | ### セキュリティ #### 考え方 - サードパーティのコードを配信物に含めない: 外部から読み込むコードが無ければ、そのコードが乗っ取られても閲覧者には届かない。閲覧者に届く経路から、修正を追い続ける必要のあるコードを外し、依存に由来する攻撃の経路を減らす。 - 「入口が無い」とは言わない: お客様には「サードパーティのコードに由来する攻撃の経路を持たない」と説明し、残るリスクとその抑え方を分けて示す。自前のコードと取り込む中身には別のリスクが残る。 #### 構成で防げるもの | 対象 | 作り | 構成で防げるもの | | --- | --- | --- | | 配信する HTML | CSS・スクリプトを HTML の中に書く。お客様向けは図も埋め込んだ単一ファイル。外部のスクリプト・スタイルシート・フォント・画像・解析タグを読み込まず、閲覧中に外部へ通信しない。フォントは閲覧者の端末のものを使う | 配信網や埋め込みスクリプトの改ざんによる、閲覧者のブラウザでの不正なコードの実行 | | 配信の仕組み | 静的ホスティングに置くだけ。アプリケーションサーバ・データベース・サーバ側のフレームワークを持たない | フレームワークやランタイムの脆弱性を突いた、サーバでの不正なコードの実行 | | 生成スクリプト | HTML を組み立てる部分は言語の標準ライブラリだけで書く(Markdown の変換も自前)。図の描画や原本の取り込みに外部ツールを使うときは、出力をリポジトリに入れ、差分のレビューと検査を通してから配信する | 依存パッケージの乗っ取りによる、生成物への不正なコードの混入 | | アクセス | 社内用とお客様向けを別のサイトに置き、どちらも認証をかける。社内用は接続元を社内に限る | 関係者以外の閲覧 | #### 残るものと抑え方 | 残るもの | 抑え方 | | --- | --- | | 自前のコードと取り込む中身(スクリプトの混入) | 文書の文字列は記法を処理する前に HTML としてエスケープし、生の HTML を通さない。リンク先は http・https・mailto・相対パスだけにする。取り込む図からスクリプト・イベント属性・外部参照を取り除く。配信前の検査で確かめる | | ホスティング・CI・配信に使う資格情報 | 資格情報は最小権限にし、できれば短命の認証にする。CI で使う外部のアクションはコミットのハッシュで固定する。検査に落ちたら配信しない | | 開発者の端末と開発ツール | 配信物は検査を通ったものだけにし、生成物は直接編集しない(手元で混ざったものがそのまま出ない) | | ブラウザ側での歯止め(推奨) | レスポンスヘッダの CSP で、外部からの読み込みとスクリプトからの通信をブラウザでも禁止する(例: default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none')。ページの移動とインラインのスクリプトの混入は CSP では止まらないので、生成側の検査で防ぐ | ### スキル #### 考え方 - 繰り返す作業はスキルにする: 資料の取り込み、反映の検査、お客様に出す前の点検、プルリクエストの確認は毎回同じ手順を踏む。そのたびに指示を書かず、コーディングエージェントのスキル(手順と約束を書いたファイル)にして、名前で呼べるようにする。 - 入口を 1 つにする: 資料や議事録の取り込みは入口のスキルから始め、Markdown 化・整理・反映・起票の下位のスキルはそこから順に呼ぶ。下位のスキルを単独で呼んだときはフックで止め、反映や起票の抜けを防ぐ。 - 決まった時点でフックが起動を促す: プルリクエストを作った直後にセルフチェックと独立レビューを、正本を直した直後に波及範囲の提案を促す。人が呼び忘れても回る。 - 点検する役と直す役を分ける: 点検のスキルは読むだけのサブエージェントに任せ、指摘を重さ順に返させる。直すのは別の手順にする。自分の書いたものを自分で合格にしない。 - 見つかった型を規則に足す: 検査や点検で新しい誤りの型が見つかったら、同じ型が何度か出た時点で規則や検査に足す。スキルは使うほど育てる。 #### 作っておくスキル | 系統 | スキル | 何をするか | いつ呼ぶ | | --- | --- | --- | --- | | 取り込み・反映 | 資料の取り込みの入口 | 受け取った資料や議事録を Markdown にし、仕様書(業務・処理・画面・データモデル・外部 IF・未決事項)へ反映し、こちらの宿題を起票し、やったことを 1 枚にまとめて社内に共有する | 資料・議事録を受け取ったとき | | 取り込み・反映 | 文書の Markdown 化 | 表計算・文書・スライド・PDF を Markdown にし、欠落と意味の変化を元の資料と比べて確かめる | 取り込みの入口から | | 取り込み・反映 | 議事録の整理 | 論点がどの業務フェーズ・要件番号の話かを割り出し、確認事項・反映漏れ・矛盾を出す。音声の書き起こしの崩れは辞書で補い、新しい崩れを辞書に足す | 取り込みの入口から | | 取り込み・反映 | 反映の検査 | 反映した結果に矛盾・漏れ・件数のずれ・お客様に出せない表現が無いかを検査し、新しい型を規則に足す | 反映の終わり | | 取り込み・反映 | 波及範囲の提案 | 正本の変更が波及する資料(台帳・仕様書・図・画面モック・見積)を洗い出し、直す範囲をまとめて提案して可否を 1 回だけ聞く | 正本を直した直後(フックが促す) | | 取り込み・反映 | 回答の取り込み | お客様からの回答を確認事項・未決事項台帳・仕様書に反映し、対応する課題を閉じる | 回答をいただいたとき | | お客様に出す前の点検 | 業務側のレビュアー | お客様の業務の責任者の目で成果物(シナリオ・画面・外部 IF・データモデル・問い)を厳しく点検し、出そうな指摘を重さ順に返す。結果は社内でだけ使う | 成果物をお出しする前 | | お客様に出す前の点検 | 共有の場の見直し | お客様も読めるタスク管理ツールや Wiki(編集履歴の古い版・添付を含む)から、社内の事情にとどまる話・他社への評価・認証情報を全件洗い出し、対処の一覧を作る | 定期的に | | お客様に出す前の点検 | 問いの点検 | 足した確認事項を過去の指摘の型で見返す。未回答の問いを既出の回答・決定・台帳と照らし、重複や答えの出ている問いを週に 1 回洗い出す | 問いを足したとき・週 1 回 | | プルリクエストの品質 | セルフチェック | 巻き込み・認証情報・生成物が作れるか・お客様向けの HTML への社内情報の混入・ID の検査・課題の完了条件を、実際にコマンドを回して判定し、結果をプルリクエストの本文に書き戻す | プルリクエストを作った直後(フックが促す) | | プルリクエストの品質 | 独立レビュー | 差分を読むだけのサブエージェントに検査させ、見つかった問題を重大度順に受け取って直す | プルリクエストを作った直後(フックが促す) | | プルリクエストの品質 | 自動レビューへの対応 | 自動のコードレビューの未解決の指摘を直し、検査を通してから解決済みにする。一定の時間だけ巡回し、新しい指摘と基のブランチとの競合も見る | レビューが付いたとき | | 生成・進捗 | ハブの生成 | 成果物一覧の表から、ハブのトップページを単一ファイルの HTML で作り、状態を更新する | 成果物を足した・状態が変わったとき | | 生成・進捗 | 図の生成 | 処理仕様書の処理の表からシーケンス図を、要件の一覧から業務フェーズごとのワークフローを作る | 正本が変わったとき | | 生成・進捗 | WBS の分解と集計 | WBS をタスク管理ツールの親子の課題に分け、担当とボールの所在を日ごとに、確認事項・仕様書の件数とあわせて週ごとに集計する | 工程の始め・週 1 回 | | 生成・進捗 | 課題の起票と状態合わせ | 宿題を起票する前に候補を一覧で見せ、起票後は担当・状態を実態に合わせる。課題を扱うときの約束(コメントまで読む・着手したら処理中にする・期日の出どころを確かめる)もここに書く | 宿題が出たとき・着手したとき | | 生成・進捗 | 日次の状況まとめ | 前の営業日の課題の動きとチャットのやり取りから、メンバーごとの状況を 1 枚にまとめて共有する | 毎朝(定期実行) | #### 書き方 - 呼ばれる言い回しを説明に並べる: スキルの説明(description)に、何をするかと、呼ばれるときの言い回し(「反映チェックして」「波及先を見て」など)を書く。似たスキルとの境界(「〜なら別のスキル」)も書く。 - 約束は 1 か所に書く: 課題の扱い方や書き方の決まりは 1 つのスキルか規則のファイルを正本にし、ほかからはリンクで参照する。書き写すとずれる。 - 結果を出す先を決める: 点検の結果を社内だけで使うのか、お客様向けに出すのかをスキルに書く。社内向けの結果がお客様の見る場所に出ないようにする。 - 案件ごとに作る: スキルは配られた道具を使い回すのではなく、案件のリポジトリに置き、案件の正本・ID 体系・規則に合わせて書く。 ### 運用の手順 #### 成果物を足す 1. 正本を作る: 対になる Markdown を先に作る(正本の無い HTML は増やさない)。 2. 対応表に 1 行足す: 生成スクリプトが要るなら作り、対応表に登録する。 3. 成果物一覧に行を足す: グループ・カード・名前・状態・公開区分を書く。パスは未作成なら空欄。 4. 再生成する: スクリプトで HTML を作り直す(フックが自動で回すこともある)。 5. プルリクエストを出す: CI が通ることを確かめてからマージする。 #### お客様に出す 1. 合意レベルを決める: チェック/チェック(形式のみ)/参照のどれにするかを成果物マトリクスで決める。 2. 「外部」の印を付ける: 成果物一覧の公開区分を「外部」にする。カード補足はお客様に見せてよい文で書く。 3. レビューのお願いを付ける: レビュー対象/一部レビュー対象/参照用のどれかを、状態とは別に付ける。一部だけ見ていただくものには、どこを見ていただくかを「ひとこと」に書く。同じ内容の入口が重なるときは主な入口を 1 つに決め、ほかは参照用にして「ひとこと」から案内する。 4. 作成中の断り書きを書く: 一部だけを書き方の見本として公開するカードには、ほかが作成中であることをお客様向けにだけ書く。 5. 社内向けの表記を言い換える: 正本で言い換えるか、編集者向けの注記にして配信用から落とす。 6. 手元で確かめる: お客様向けを作って検査にかけ、見た目を確認する。