diff --git a/docs/glossary.md b/docs/glossary.md index ef1a034d3..e3d9c0d83 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -400,6 +400,11 @@ NDF が提供する工程・承認ゲート・モード・ステップの語。d | プランのハッシュ | — | プランの型で読んだ中身を、キーを並べ替えた JSON にして取った sha256。完了したプランが変わったかを測る（#2344） | — | — | — | | 呼び手 | — | 関数かエントリポイントを呼ぶ、テストの外のファイル（Skill の本文・雛形・hook・CI・ほかのスクリプト）。テストだけが呼ぶものは呼び手 0 と数える | — | — | — | | 残す関数の一覧 | — | 関数の棚卸し（uvx vulture）が呼び手 0 と見るが、vulture に見えない呼ばれ方などで残す関数を、理由の種類と理由と定義のあるファイルを 1 行ずつ添えて持つ一覧。置き場は scripts/ndf-vulture-keep.txt。構造チェックの例外リストとは別のもの | — | — | — | +| 外部の調査 | — | 設計の判断の前に、業界の事実上の標準・仕様、主要な製品の解き方、使える既存のライブラリとマネージドサービスを一次情報で調べ、設計文書に残す手順（#2519）。棚卸しのシーズの調査とは別のもの | — | — | — | +| 自前で作る決定 | — | 既存のライブラリ・サービス・標準の実装を使わず、プロジェクトの中で作ると決めた決定の記録。決定の作り方の行に「自前で作る」を含むもので見分ける（#2519） | — | — | — | +| 確かめられなかったこと | — | 外部の調査で、公開の資料が無い・取得できなかった・上限で止めた対象と、試した手段（URL か検索の語）と理由を並べた設計文書の欄（#2519） | — | — | — | +| 作り方 | — | 設計文書の決定の記録の中の 1 行。その決定が機能をどう得るか（自前で作る / ライブラリやサービスを使う / 標準に倣う、またはその組み合わせ）を書く（#2519） | — | — | — | +| 比べた候補 | — | 設計文書の決定の記録の中の 1 行。外部の調査の表で比べた行の番号（STD<数> / PRD<数> / LIB<数>）を並べる（#2519） | — | — | — | | プランの進行の記録 | — | supervise のプランのステップごとの終了コード・秒・ドルを 1 行ずつ残す記録（`<状態のディレクトリ>/progress.jsonl`）。開発ループのまとめのプランでは `.ndf/loop/<名>/lap-<番号>/close*/` の下にある（#2315） | — | — | — | | 承認した先端 | — | 設計の承認を問うた時点の設計 Pull Request の先頭のコミット。承認した設計のマージはこの先端のときだけ行う | — | — | — | | マージの結果 | — | 承認した設計 Pull Request を宛先へマージする 1 回の試みの結果。マージした・マージ済み・先端が動いた・印が無い・検査が緑でない・衝突・宛先が本番・失敗のどれか | — | — | — | diff --git a/docs/glossary/glossary.json b/docs/glossary/glossary.json index 67d9c507c..1a05d9924 100644 --- a/docs/glossary/glossary.json +++ b/docs/glossary/glossary.json @@ -5487,6 +5487,36 @@ "meaning": "関数の棚卸し（uvx vulture）が呼び手 0 と見るが、vulture に見えない呼ばれ方などで残す関数を、理由の種類と理由と定義のあるファイルを 1 行ずつ添えて持つ一覧。置き場は scripts/ndf-vulture-keep.txt。構造チェックの例外リストとは別のもの", "pending_source": "issues/issue-2369-design.md" }, + { + "term": "外部の調査", + "context": "ndf-workflow", + "meaning": "設計の判断の前に、業界の事実上の標準・仕様、主要な製品の解き方、使える既存のライブラリとマネージドサービスを一次情報で調べ、設計文書に残す手順（#2519）。棚卸しのシーズの調査とは別のもの", + "pending_source": "issues/issue-2519-requirements.md" + }, + { + "term": "自前で作る決定", + "context": "ndf-workflow", + "meaning": "既存のライブラリ・サービス・標準の実装を使わず、プロジェクトの中で作ると決めた決定の記録。決定の作り方の行に「自前で作る」を含むもので見分ける（#2519）", + "pending_source": "issues/issue-2519-design.md" + }, + { + "term": "確かめられなかったこと", + "context": "ndf-workflow", + "meaning": "外部の調査で、公開の資料が無い・取得できなかった・上限で止めた対象と、試した手段（URL か検索の語）と理由を並べた設計文書の欄（#2519）", + "pending_source": "issues/issue-2519-design.md" + }, + { + "term": "作り方", + "context": "ndf-workflow", + "meaning": "設計文書の決定の記録の中の 1 行。その決定が機能をどう得るか（自前で作る / ライブラリやサービスを使う / 標準に倣う、またはその組み合わせ）を書く（#2519）", + "pending_source": "issues/issue-2519-design.md" + }, + { + "term": "比べた候補", + "context": "ndf-workflow", + "meaning": "設計文書の決定の記録の中の 1 行。外部の調査の表で比べた行の番号（STD<数> / PRD<数> / LIB<数>）を並べる（#2519）", + "pending_source": "issues/issue-2519-design.md" + }, { "term": "深さの記録", "context": "ndf-issue-upkeep", diff --git a/issues/issue-2519-design.md b/issues/issue-2519-design.md new file mode 100644 index 000000000..711164b97 --- /dev/null +++ b/issues/issue-2519-design.md @@ -0,0 +1,489 @@ +# design: 設計の判断の前に外部の標準・主要な製品・既存のライブラリを調べ、自前で作る決定に比べた候補を残す（#2519） + +## 目的 + +- **今どうなっているか**: `design` には、設計の前に業界の標準・主要な製品の解き方・使える既存のライブラリとサービスを調べる手順が無い。設計は手元のコードと要求の文だけから組み立てられる。そのため、比べないまま「自前で作る」「古い形に寄せる」と決まる（carul #102・#117 で、利用者が後から気づいて設計をやり直した） +- **誰に効くか**: `design` を通すすべてのプロジェクトの設計者と、承認ゲート 1 で設計を承認する人 +- **変えると何が成り立つか**: 設計文書に、何と比べてこの形にしたかが出典つきで残る。自前で作る決定に比べた候補が無ければ、承認ゲート 1 の前に機械の検査が止める。設計 PR と実装 PR のレビュー（`pr-review` と `cross-review` の担当）も、比べた候補の欠け・出典の欠けと古さ・設計の作り方との食い違いを指摘する。担当は自分で外部を調べ、より良い標準やライブラリの見落としを出典つきで指摘できる。プロジェクトの MVV に調査の項目が無くても同じに働く + +## 適用範囲 + +- **働く範囲**: NDF を使うすべてのリポジトリ。手順は `design` の Skill が持つ。検査は、スプリントの設計のプランと `design` の手順から打つスクリプトで、このリポジトリの継続的統合に依らない。レビューの観点は `pr-review` と `cross-review` が PR ごとに渡す +- **プロジェクトごとに違うもの**: 無し（調べる対象は触る領域から設計者が決め、領域ごとの標準の一覧を持たない。上限の値は NDF の参照の 1 か所に置く） +- **当たるモード**: `design` を通すすべてのモード（`standard`・`legacy-refactor`・`documentation`、領域に当たった `light`・`operation`） + +## あるべき姿の根拠 + +| 根拠 | 種類 | 何を示すか | +| --- | --- | --- | +| MADR 4.0.0 のテンプレート（ https://adr.github.io/madr/ 、2026-11-05 取得） | 外部の一次情報 | 決定の記録の事実上の標準は、比べた選択肢（Considered Options）と選んだ選択肢（Decision Outcome: `Chosen option: …, because …`）を別の欄に持つ。比べた候補を決定に並べる形はこれに倣う | +| OpenSSF Scorecard の Maintained の検査（ https://github.com/ossf/scorecard/blob/main/docs/checks.md 、2026-11-05 取得） | 外部の一次情報 | 保守の状態は直近 90 日の活動で見て、アーカイブしたリポジトリを最低の評価にする。ライブラリの表の「最後のリリースの日付」と「終了のアナウンス」の 2 列はこの見方に合わせる | +| Olaf Zimmermann「How to review Architectural Decision Records (ADRs) — and how not to」（ https://ozimmer.ch/practices/2023/04/05/ADRReview.html 、2026-11-05 取得） | 外部の一次情報 | 決定の記録のレビューの観点に「妥当な選択肢が欠けていないか（Are valid options missing?）」と「有効期間か見直しの日を定めているか」がある。レビューの側で比べた候補の欠けと出典の古さを見る形はこれに倣う | +| 設計の承認ゲート 1 での利用者の指摘（2026-11-05、課題の本文の末尾の節） | 利用者の指示の原文 | 外部の調査の確認を `pr-review` と `cross-review` の工程にも入れる。design の手順・テンプレート・検査は設計のまま残し、実装の PR を分ける | +| carul #102・#117（課題の本文の具体例） | 実測 | 比べないまま自前で作ると決めた設計を、利用者の指示で作り直した。2 回目の #102 の設計は、ライブラリの候補 6 つと競合 6 製品を出典つきで比べた | +| マイルストーン「35 開発フローの見直しと大整理」の説明（2026-11-05） | 利用者の指示の原文 | 「設計で問題が出ることが多いため、できるだけ早く着手する」 | + +要求と受け入れ条件は #2519 の本文にある（コピーは `issues/issue-2519-requirements.md`）。この文書は「どう作るか」だけを扱う。 + +## ドメインモデル + +### コンテキスト + +| コンテキスト | 何の語が 1 つの意味に決まるか | +| --- | --- | +| NDF の工程（`ndf-workflow`） | 設計文書・決定の記録・外部の調査・自前で作る決定・作り方・比べた候補・確かめられなかったこと・レビューの観点 | + +変更は 1 つのコンテキストに収まる。棚卸しのシーズの調査は同じコンテキストの別の手順で、記録を共有しない（決定 8）。`pr-review` と `cross-review` は同じコンテキストの別の工程で、設計文書を読むだけで書き換えない。 + +### 集約 + +| 集約 | 持ち主（書き換えてよいもの） | 根 | エンティティ | 値オブジェクト | +| --- | --- | --- | --- | --- | +| 設計文書 | 設計を書く担い手（`design` の手順を通す worker か利用者）と、指摘を直す修正担当 | 設計文書（同じ課題の `issue-<番号>-design*.md`。`light` は受け入れ条件のファイルの設計の節） | 決定・外部の調査の節 | 作り方・比べた候補・調べた行の出典・確かめられなかったことの行・調べた量 | +| 外部の調査の確認の観点 | NDF の保守者（PR を通して直す） | `pr-review` の SKILL.md の節 `### 外部の調査の確認`（決定 10） | 設計 PR の観点・実装 PR の観点・担当が外部を調べるときの規則 | 古さの基準（90 日）・担当の取得の試みの上限（10 回） | + +検査のスクリプトとレビュー担当は設計文書を読むだけで、書き換えない。`cross-review` は観点の節を読むだけで、コピーを持たない。 + +### 不変条件 + +| # | 集約 | 条件 | 破れたときの扱い | +| --- | --- | --- | --- | +| I1 | 設計文書 | 外部の調査の節は 1 つで、「省く」の 1 行か、調べる対象の表（3 種類の行）のどちらか一方を持つ | 設計 PR のレビューで指摘する | +| I2 | 設計文書 | 調べる対象の表で「調べない」とした種類は、理由を 1 行持つ | 設計 PR のレビューで指摘する | +| I3 | 設計文書 | 調べた結果の行は、出典（URL・パス・コマンドのどれかと取得日）を持つ。出典を持てない対象は確かめられなかったことの行へ移り、推定で埋めない | 設計 PR のレビューで指摘する | +| I4 | 設計文書 | 種類ごとの候補は上限（6 件）以下。上限で止めた対象は、確かめられなかったことへ理由「上限」で載る | 設計 PR のレビューで指摘する | +| I5 | 設計文書 | 作り方に「自前で作る」を含む決定は、比べた候補を 1 つ以上持つ。ただし、同じまとまり（課題の番号の共有をたどって閉じた文書の集まり。分けたファイルと、`issue-7-8-design.md` のように番号を 2 つ以上含む名前の文書を介してつながる文書を含む。入出力の契約の「課題ごとのまとまり」）のどれかの文書で外部の調査を「省く」としたときは、そのまとまりの決定すべてを除く | 検査が終了コード 1 で指摘し、スプリントの設計のプランが承認ゲート 1 の前で止まる | +| I6 | 設計文書 | 比べた候補の番号は、決定の属するまとまり（I5 と同じ範囲）にある外部の調査の表の行の番号のどれかである。例: `issue-7-design.md`・`issue-7-8-design.md`・`issue-8-design.md` は 1 つのまとまりで、7 の決定は 8 の表にだけある番号でも解決する。ほかのまとまりの表では解決しない | I5 と同じ | +| I7 | 設計文書 | 作り方の値は「自前で作る」「ライブラリやサービスを使う」「標準に倣う」のどれか、またはその組み合わせである | I5 と同じ | +| I8 | 外部の調査の確認の観点 | 観点の正本は 1 か所で、`pr-review` と `cross-review` の担当は同じ文を受け取る | `cross-review` の起動の観点を組む処理が、節を読めなければ止まる（決定 10） | +| I9 | 外部の調査の確認の観点 | 観点は、設計文書か実装のコードを変える PR（分類 `design` か `code`）に載り、ドキュメントだけの PR には載らない。設計 PR では詳細レビューにだけ載る | `review_focus.py` の単体テストで落ちる（決定 11） | +| I10 | 外部の調査の確認の観点 | 担当が「より良い候補がある」「出典が古い」と指摘するときは、自分で取得した出典（URL と取得日）を添える。取得できなかったときは推定で指摘せず、試した URL か検索の語と理由を書く | 観点の文が持つ規則。担当の振る舞いは機械で縛らない。出典の無い「より良い候補」の指摘は、修正担当が直す前に出典を取り直す | +| I11 | 外部の調査の確認の観点 | 担当の外部の取得の試みは、1 ラウンドに 10 回以下である。上限に当たったら止め、残りを確かめられなかったこととして総評に書く | 観点の文が持つ規則。担当の振る舞いは機械で縛らない（決定 13） | + +### ドメインイベント + +| # | イベント | 発生元 | 受け手 | +| --- | --- | --- | --- | +| E1 | 設計で触る領域を決めた | `design` の手順 1 | `design` の手順 2（外部の調査） | +| E2 | 外部の調査を通すか省くかを決めた | `design` の手順 2 | 通すなら手順 2 の続き。省くなら設計文書の外部の調査の節（「省く」の 1 行） | +| E3 | 調べる対象を決めた | `design` の手順 2 | 一次情報の取得 | +| E4 | 一次情報を取得した | 設計を書く担い手（Web 検索・URL の取得・`gh`） | 外部の調査の節の表の行。取得できなければ確かめられなかったことの行 | +| E5 | 調べる量の上限に当たって調査を止めた | `design` の手順 2 | 確かめられなかったことの行（理由「上限」） | +| E6 | 調べた結果を外部の調査の節に残した | 設計を書く担い手 | 決定の記録（`design` の手順 4）・あるべき姿の根拠 | +| E7 | 決定の記録に作り方と比べた候補を書いた | `design` の手順 4 | 検査のスクリプトと設計 PR のレビュー | +| E8 | 自前で作る決定に比べた候補が無い設計文書を指摘した | 検査のスクリプト（`design-survey.py check`）と設計 PR のレビュー | 修正担当（スプリントの設計のプランの `fix-survey`）。直らなければプランが止まり、conductor が人へ戻す | +| E9 | レビューが外部の調査の観点を受け取った | `pr-review` の開始（SKILL.md の観点を読む・委譲のプロンプトへ写す）、`cross-review` の担当の起動（`review_focus.py` が観点を組む） | レビューの担当（claude・codex・kiro・agy） | +| E10 | レビューの担当が外部の一次情報を取得した | レビューの担当（担当のランタイムがすでに持つ取得の手段） | 指摘の本文の出典。取得できなければ指摘の本文か総評の確かめられなかったこと | +| E11 | 比べた候補の欠け・出典の欠けと古さ・設計の作り方との食い違い・より良い候補の見落としを、レビューの指摘にした | レビューの担当 | 既存のレビューの流れ（`/ndf:fix`・`cross-review` の修正担当） | + +### 用語 + +| 用語 | 意味 | 用語集への反映 | +| --- | --- | --- | +| 外部の調査 | 設計の判断の前に、業界の事実上の標準・仕様、主要な製品の解き方、使える既存のライブラリとマネージドサービスを一次情報で調べ、設計文書に残す手順 | 追加（要求の変更で足した語。意味は変えない） | +| 自前で作る決定 | 既存のライブラリ・サービス・標準の実装を使わず、プロジェクトの中で作ると決めた決定の記録。作り方の行に「自前で作る」を含む決定 | 意味の変更（作り方の行で見分けることを足す） | +| 確かめられなかったこと | 外部の調査で、公開の資料が無い・取得できなかった・上限で止めた対象と、試した手段と理由を並べた欄 | 意味の変更（試した手段の列を足す） | +| 作り方 | 決定の記録の中の 1 行。その決定が機能をどう得るか（自前で作る / ライブラリやサービスを使う / 標準に倣う）を書く | 追加 | +| 比べた候補 | 決定の記録の中の 1 行。外部の調査の表で比べた行の番号（`STD<数>` / `PRD<数>` / `LIB<数>`）を並べる | 追加 | + +## 外部の調査 + +| 種類 | 調べるか | 理由 | +| --- | --- | --- | +| 標準・仕様 | 調べる | 決定の記録の書式と、ライブラリの保守の状態の判定と、決定の記録のレビューの観点に事実上の標準がある | +| 主要な製品 | 調べない | 変えるのは NDF の手順の文・文書の検査・レビューの観点の文で、利用者に見える製品の機能に当たる形が無い | +| ライブラリとサービス | 調べる | 検査は Markdown の見出しと表を読む。読み方を自前で書くか既存の部品を使うかを決める | + +### 標準・仕様 + +| # | 標準・仕様 | 何を定めているか | 設計への反映 | 出典 | +| --- | --- | --- | --- | --- | +| STD1 | MADR 4.0.0 | 決定の記録に Considered Options（比べた選択肢）と Decision Outcome（`Chosen option: …, because …`）を別の欄で持つ | 作り方と比べた候補を決定の中の別の行にする（決定 4） | https://adr.github.io/madr/ （2026-11-05 取得） | +| STD2 | OpenSSF Scorecard の Maintained | 直近 90 日の活動で保守を見る。アーカイブしたリポジトリは最低の評価 | ライブラリの表に最後のリリースの日付と終了のアナウンスの列を置き、アーカイブを終了のアナウンスとして扱う。レビューで出典を古いと見る基準を 90 日にする（決定 12） | https://github.com/ossf/scorecard/blob/main/docs/checks.md （2026-11-05 取得） | +| STD3 | Zimmermann の ADR のレビューの観点（2023-04-05 公開、2026-08-28 更新） | 7 つの問いのうち、妥当な選択肢が欠けていないか（Are valid options missing?）と、有効期間か見直しの日を定めているか | レビューの観点に「比べた候補の見落とし」と「出典の古さ」を置く（決定 10・12） | https://ozimmer.ch/practices/2023/04/05/ADRReview.html （2026-11-05 取得） | + +### ライブラリとサービス + +| # | 候補 | 版 | ライセンス | 最後のリリースの日付 | 終了のアナウンス | 要件を満たすか | 出典 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| LIB1 | markdown-it-py（`lib/md.py` が包む） | 4.2.0 | MIT | 2026-05-07 | 無し（アーカイブされていない。最後の push 2026-11-02） | 満たす（見出しの階層・表・コードブロックの判定を既に持つ） | https://pypi.org/pypi/markdown-it-py/json と https://api.github.com/repos/executablebooks/markdown-it-py （2026-11-05 取得）、`uv.lock` | + +### 確かめられなかったこと + +| 対象 | 試した手段 | 結果と理由 | +| --- | --- | --- | +| 決定の記録に比べた候補があるかを確かめる既存の検査の Tool | 試していない | 上限の前に止めた。比べる候補を探す検索をしていないため、既存の Tool が無いとは言えない。検査は LIB1 の上に数十行で書ける規模で、Tool を入れる費用（依存の追加・設定の書式）に見合うかは未確認 | + +調べた量: 候補 4 件・取得の試み 5 回。 + +## 機能一覧 + +| # | 機能 | 誰が使うか | +| --- | --- | --- | +| F1 | 触る領域から、3 種類の調べる対象ごとに調べるか省くかを決め、理由を残す | 設計を書く担い手 | +| F2 | 標準・仕様、主要な製品、ライブラリとサービスを出典つきの表に残し、取得できなかった対象を確かめられなかったことへ残す | 設計を書く担い手、承認する人 | +| F3 | 調べる量の上限に当たったら調査を止める | 設計を書く担い手 | +| F4 | 決定に作り方と比べた候補を書く | 設計を書く担い手 | +| F5 | 自前で作る決定に比べた候補が無い設計文書を、機械の検査で指摘する | スプリントの設計のプラン、設計を書く担い手 | +| F6 | 設計 PR のレビューで、外部の調査の節の欠け・省いた理由の欠け・比べた候補の欠け・出典の欠けと古さを指摘する | `pr-review`、`cross-review` の担当 | +| F7 | 実装 PR のレビューで、差分が同じ課題の設計の作り方と比べた候補に沿っているかを見て、食い違いを指摘する | `pr-review`、`cross-review` の担当 | +| F8 | レビューの担当が自分で外部の一次情報を調べ、より良い標準・ライブラリ・主要な製品の形の見落としを出典つきで指摘する。取得できなければ推定で指摘しない | `pr-review`、`cross-review` の担当 | +| F9 | 設計 PR と実装 PR の担当の起動の観点に、F6〜F8 の観点を載せる | `cross-review` の起動の観点を組む処理 | + +## 構成要素 + +### 要素ごとの責務 + +列「PR」は、実装の 2 つの PR のどちらで触るかを示す（決定 15）。1 は `design` の手順と検査、2 はレビューと `cross-review` の観点である。 + +| 要素 | PR | 責務 | +| --- | --- | --- | +| `plugins/ndf/skills/design/SKILL.md` | 1 | 手順 2「外部の調査を通す」を足し、以後の手順の番号を 1 つずつ繰り下げる（決定 1）。「すべての変更」の行に `external-survey.md` を足す。手順 5（突き合わせ）で検査のコマンドを打つ | +| `plugins/ndf/skills/design/references/external-survey.md`（新規） | 1 | 外部の調査の手順の正本。3 種類の対象の決め方・省ける条件・上限と「調べた量」の行・取得できないときの書き方（`investigation-rules` の否定的な結論の規則に合わせ、試した URL か検索の語と結果を書く）・決定へのつなぎ方・シーズの調査の記録の引き方 | +| `plugins/ndf/skills/design/references/design-template.md` | 1 | テンプレートに `## 外部の調査` の節を「機能一覧」の前に足す。「あるべき姿の根拠」の外部の一次情報は、外部の調査の行の番号を指してよいと書く。「各節が実装計画のどこへつながるか」に行を足す。「`legacy-refactor` の書き方」を 4 節にする（決定 9） | +| `plugins/ndf/skills/design/references/decisions.md` | 1 | 決定の書き方に、作り方と比べた候補の 2 行を足す（決定 4） | +| `plugins/ndf/skills/design/references/deliverables.md` | 1 | 要否表に「外部の調査」の行（全モード必須）を足す。「成果物ごとの中身」に行を足す。`legacy-refactor` の無条件の成果物の段落を 4 節に合わせる | +| `plugins/ndf/scripts/design-survey.py`（新規） | 1 | 検査のエントリポイント。I5〜I7 を読むだけで判定する（決定 6） | +| `plugins/ndf/scripts/lib/design_docs.py`（新規） | 1 | 設計文書の名前の規則と、課題の番号から HEAD の文書を読む処理。`design-match.py` から移し、2 つのエントリポイントで共有する | +| `plugins/ndf/scripts/design-match.py` | 1 | 設計文書の探し方を `lib/design_docs.py` から読む（振る舞いは変えない） | +| `plugins/ndf/scripts/supervise_lib/paths.py` | 1 | 検査のコマンドの定数（`DESIGN_SURVEY_PY`） | +| `plugins/ndf/scripts/supervise_lib/sprint_waves.py` | 1 | 設計のプランに `survey-check` / `fix-survey` / `survey-recheck` の 3 ステップを足す（決定 7） | +| `plugins/ndf/contracts/entrypoints/plugins__ndf__scripts__design-survey.py.json`（新規）と `plugins/ndf/contracts/index.md` | 1 | エントリポイントの契約（`check-ndf-contracts.py --draft` で起こし、`--render` で逆引きを作り直す） | +| `plugins/ndf/scripts/tests/test_design_survey.py`（新規） | 1 | 検査の振る舞いのテスト | +| `plugins/ndf/scripts/tests/fixtures/supervise-contract/plans/sprint/1-design-16.json` | 1 | 設計のプランの期待値に 3 ステップを足す | +| `docs/glossary/glossary.json` / `docs/glossary.md` | 1 | 用語の表の 5 語を反映する | +| `plugins/ndf/skills/pr-review/SKILL.md` | 2 | `## 観点` の中に `### 外部の調査の確認` の節を足す。観点の正本（決定 10）。中身は入出力の契約の「外部の調査の確認の観点」 | +| `plugins/ndf/skills/cross-review/scripts/review_lib/review_focus.py` | 2 | `pr-review` の SKILL.md の節を読み、分類 `design` か `code` を持つ PR の自動レビュー観点の後ろに足す（決定 5・10・11）。設計 PR のモデルレビューには足さない | +| `plugins/ndf/skills/cross-review/docs/04-contracts.md` | 2 | 自動レビュー観点の `design` と `code` の要約に、外部の調査の確認を載せることを書く。行は足さず、既存の要約の行を直す（ファイルが 500 行に達している） | +| `plugins/ndf/skills/cross-review/tests/test_review_focus_external_survey.py`（新規） | 2 | 観点を載せる PR の種類の振る舞いのテスト（I9） | + +### 呼び出しと参照の関係 + +```mermaid +graph TD + subgraph 手順とテンプレート + SK[design の SKILL.md] + ES[external-survey.md] + TP[design-template.md
decisions.md] + end + subgraph 検査 + DS[design-survey.py] + DD[lib/design_docs.py] + DM[design-match.py] + end + subgraph 設計のプラン + SW[sprint_waves.py] + end + subgraph レビュー + PR[pr-review の SKILL.md
外部の調査の確認] + RF[review_focus.py] + end + SK --> ES + SK --> TP + SK -->|手順 5 で打つ| DS + SW -->|survey-check| DS + DS --> DD + DM --> DD + RF -->|節を読む| PR + PR -->|作り方・比べた候補の形| TP +``` + +図には、呼び出しと参照の関係を持つ要素だけを描く。`deliverables.md`・`paths.py`・`04-contracts.md`・エントリポイントの契約・テストと期待値・用語集は描かない。これらは図の要素の定数・説明・記録で、呼び出しの辺を持たない。`pr-review` の委譲のプロンプトを組む処理（`pr-review-steps.py`）は `## 観点` の節を丸ごと写す既存の処理である。変えないため描かない。 + +## 入出力の契約 + +### `design-survey.py check` + +| 項目 | 書くこと | +| --- | --- | +| 名前 | `python3 design-survey.py check (--issue N... \| --file PATH...) [--root DIR]` | +| 入力 | `--issue`: 課題の番号（1 つ以上）。HEAD の `issues/` から、名前の番号の並びにその番号を含む `issue-<番号>-design*.md` と `issue-<番号>-requirements.md` を読む。読んだ文書の名前がほかの番号を含むときは、その番号を名前に含む文書も読み足し、新しい番号が出なくなるまで繰り返す（`--issue 8` でも `issue-8-design.md`・`issue-7-8-design.md`・`issue-7-design.md` の 3 ファイルを読む）。`--file`: 読む文書のパス（worktree から読む。`light` の受け入れ条件のファイルや `operation` の実行の記録を渡す）。`--root`: リポジトリの根（既定はカレントの git の根） | +| 出力 | `lib/step_result.py` の形の 1 行の JSON（`tool: "design-survey"`）。`items[]` は 1 指摘 1 件で、`name` は `<パス>:<行> 決定 `、`rule` は `no_candidates` / `unknown_candidate` / `unknown_method`、`text` は当たった行。`metrics` は読んだ文書の数・決定の数・作り方の行を持つ決定の数・自前で作る決定の数・外部の調査を省いた課題の数 | +| 失敗の形 | 0 = 指摘なし（作り方の行が 0 件の文書を含む）/ 1 = 指摘あり / 2 = 文書か git を読めない / 3 = `--issue` で文書が 1 つも見つからない | +| 互換性 | 新しいエントリポイントで、既存の呼び出し側は無い。作り方の行を持たない既存の設計文書は 0 になる（受け入れ条件 10） | + +**判定の規則**（コードブロックの中は読まない）: + +| 規則 | 読む場所 | 当たる条件 | +| --- | --- | --- | +| 課題ごとのまとまり | 読んだ文書を、ファイル名の番号の並びに含む課題の番号でつなぎ、番号を 1 つでも共有する文書どうしを 1 つのまとまりにする（つながりをたどって閉じる）。1 つの文書は 1 つのまとまりにだけ属する。例: `issue-7-design.md`・`issue-7-8-design.md`・`issue-8-design.md` を読むと、3 ファイルで 1 つのまとまりになる。`--issue` は読む文書をつながりで閉じるため、`--issue 7`・`--issue 8`・`--issue 7 8` のどれでも、この 3 ファイルを読んで同じ 1 つのまとまりになり、判定は渡す番号で変わらない。名前に課題の番号を持たない文書（`--file` で渡す受け入れ条件のファイルや実行の記録）は、1 ファイルで 1 つのまとまりにする。以下の規則は、まとまりごとに閉じて判定する | — | +| 決定 | 見出しの文が `決定 <数字>` で始まる見出しから、同じか上の階層の次の見出しまで | — | +| 外部の調査の節 | 見出しの文が `外部の調査` の見出しから、同じか上の階層の次の見出しまで（小見出しを含む）。同じまとまりの文書の節を合わせ、ほかのまとまりの節とは合わせない | — | +| 省いた課題 | まとまりの外部の調査の節のどれかに `省く:` で始まる行がある | — | +| 候補の番号 | 同じまとまりの外部の調査の節の表の 1 列目が `STD<数>` / `PRD<数>` / `LIB<数>` の行 | — | +| `unknown_method` | 決定の中の `作り方:` の行 | 値を `・` か `/` で分けた語のどれかが 3 つの語に無い | +| `no_candidates` | 作り方に `自前で作る` を含む決定 | `比べた候補:` の行に候補の番号が 1 つも無く、決定の属するまとまりが省いた課題でもない | +| `unknown_candidate` | 決定の中の `比べた候補:` の行 | 並べた番号が、決定の属するまとまりの候補の番号のどれにも無い | + +行の頭の `- ` と、`:` の代わりの全角の `：` も受ける。MVV の宣言と本文は読まない（受け入れ条件 9）。 + +### 設計のプランのステップ + +`requirements-recheck` の次、`glossary-check` の前に置く。 + +| ステップ | 種類 | 中身 | 失敗したとき | +| --- | --- | --- | --- | +| `survey-check` | run | `design-survey.py check --issue <番号>` | `fix-survey` へ | +| `fix-survey` | work（修正） | 指摘の行に作り方・比べた候補を直すか、外部の調査の表へ候補の行を足してコミットする（push しない）。比べずに直せない指摘は直さずに「判断が要る」と報告する | — | +| `survey-recheck` | run | `survey-check` と同じコマンド | 次へ進まずプランが止まる（`on_fail` を置かない） | + +push は後の `push-glossary` が行う。 + +### 外部の調査の確認の観点 + +`pr-review` の SKILL.md の `## 観点` の中に置く節である。`pr-review`（Claude 自身のレビューと、委譲のプロンプト）と `cross-review` の担当が、同じ文を受け取る。 + +| 項目 | 書くこと | +| --- | --- | +| 名前 | 見出し `### 外部の調査の確認`（`## 観点` の中。第 1 段（仕様適合）の表の後、第 2 段（コード品質）の前） | +| 読み手 | `pr-review`: Claude 自身が SKILL.md を読む。委譲は `pr-review-steps.py` が `## 観点` を丸ごと写す（既存の処理のまま）。`cross-review`: `review_focus.py` が `gh_sections.get_section` で節を読み、分類 `design` か `code` を持つ PR の自動レビュー観点の後ろに `## 自動追加レビュー観点: 外部の調査の確認` の見出しで足す | +| 失敗の形 | `review_focus.py` が節を読めない（ファイルが無い・見出しが無い）ときは、`review_lib.die` で `init` を止める。観点の無いまま担当を起動しない | +| 互換性 | 設計文書に作り方の行が無い既存の課題の実装 PR では、「設計に作り方の行が無い」こと自体を指摘にしない（前提 5） | + +節の中身（実装はこの項目を文にする。重要度は `pr-review` の「重要度」の語）: + +| 区分 | 見ること | 指摘にする条件 | 重要度 | +| --- | --- | --- | --- | +| 設計 PR | 外部の調査の節 | 節が無い。通したのに 3 種類の採否か調べない理由が無い。省いたのに理由の 1 行が無い | `major` | +| 設計 PR | 自前で作る決定 | 作り方に「自前で作る」を含む決定に比べた候補が無い。ただし I5 と同じく、決定の属するまとまり（入出力の契約の「課題ごとのまとまり」。分けたファイルと、番号を 2 つ以上含む名前の文書を介してつながる文書を含む）のどれかの文書で外部の調査を理由付きの `省く:` で省いたときは、指摘にしない。機能をどう得るかを決めた決定に作り方の行が無い | `major` | +| 設計 PR | 調べた行の出典 | 出典（URL・パス・コマンドのどれかと取得日）が無い。取得日が設計 PR を出した日より 90 日以上前（決定 12） | `major` | +| 設計 PR | 確かめられなかったこと | 取得できなかった対象を推定で埋めている | `major` | +| 実装 PR | 同じ課題の設計文書（決定 14） | 設計で「ライブラリやサービスを使う」とした機能を自前で作った（仕様適合の指摘。`stage: "spec"`）。設計に作り方の行が無い自前の部品を足した。新しく足した依存（ライブラリ・サービス）が設計の比べた候補に無い | `major` | +| 両方 | 担当が自分で調べた結果 | 表に無い標準・ライブラリ・主要な製品の形で、要求を満たすと出典で示せるもの（比べた候補の見落とし）。表の行の版より新しい版、か終了のアナウンスが取得日の後に出ている | `major` | + +外部を調べるときの規則（同じ節に書く）: + +- 調べてよいのは、担当のランタイムがすでに持つ取得の手段（Web 検索・URL の取得・`gh` など）だけである。手段の設定は変えない +- 調べる対象は、自前で作る決定・新しく足した依存・出典の古い行に絞る。設計の外部の調査を最初からやり直さない +- 取得の試み（検索 1 回・URL の取得 1 回をそれぞれ 1 と数える）は 1 ラウンドに 10 回までにする（決定 13）。上限に当たったら止める +- 指摘には、取得した出典（URL と取得日）を添える。取得できなかったときは推定で指摘しない。試した URL か検索の語と理由（拒否・HTTP の状態・ネットワークの誤り・上限）を総評に書く + +## 処理の流れ + +### 設計の手順 + +```mermaid +graph TD + A[手順 1
触る領域を決める] --> B{省ける条件に
当たるか} + B -->|当たる| C[外部の調査の節に
省く: 理由] + B -->|当たらない・
決められない| D[3 種類ごとに
調べるかを決める] + D --> E[一次情報を取得し
出典つきで表に残す] + E --> F{取得できたか
上限の内か} + F -->|できない・上限| G[確かめられなかった
ことへ書く] + F -->|できた| H[手順 3・4
設計を書き、決定に
作り方と比べた候補] + G --> H + C --> H + H --> I[手順 5
design-survey.py check] + I -->|0| J[手順 6
設計 PR] + I -->|1| H +``` + +### スプリントの設計のプラン + +スプリントの設計のプランでは、レビューの後にもう一度検査を通す。 + +```mermaid +graph TD + R[review
sync-review
requirements-recheck] --> S{survey-check} + S -->|0| G[glossary-check 以降] + S -->|0 以外| F[fix-survey] + F --> T{survey-recheck} + T -->|0| G + T -->|0 以外| X[プランが止まり
conductor が人へ戻す] +``` + +### レビュー + +レビューでは、PR の分類で観点を載せるかが決まる。担当は観点に沿って見て、要るときだけ外部を調べる。 + +```mermaid +graph TD + A[PR の変更ファイルを分類] --> B{design か code
を持つか} + B -->|持たない| N[観点を載せない] + B -->|持つ| C[pr-review の節を
観点に足す] + C --> D[担当が設計文書と
差分を観点で見る] + D --> E{自前の決定・新しい依存・
古い出典があるか} + E -->|無い| F[指摘の有無を
結果に書く] + E -->|ある| G[外部を調べる
1 ラウンド 10 回まで] + G -->|取得できた| H[出典つきで指摘] + G -->|できない・上限| I[試した URL と理由を
総評に書く] + H --> F + I --> F +``` + +## 決定の記録 + +### 決定 1: 調べた結果を設計の判断より先に持つため、外部の調査を `design` の手順 2 に置き、以後の手順を繰り下げる + +外部の調査は触る領域（手順 1）から対象を決め、その結果が設計文書の中身（手順 3）と決定（手順 4）の材料になる。独立した手順にすると、省くか通すかの判断と上限を 1 か所で読める。手順の番号を参照しているのは `design` の SKILL.md の中の 4 か所だけである。`plugins/` と `docs/specifications/` を「design の手順 + 数字」の正規表現で検索した。ほかの文書からの参照は 1 件（`docs/specifications/ndf-ubiquitous-language.md`）だけで、手順 0 を指す。 + +手順 1 の中へ足す形は採らない。手順 1 は「どの参照を読むか」を決める手順で、一次情報の取得と表の作成は性質が違う。`1a` の番号で足す形も採らない。番号の参照が SKILL.md の中に閉じているため、繰り下げの費用が小さい。 + +根拠: Value 7 / Value 8（MVV 版 5） + +### 決定 2: 調査が設計の所要を際限なく延ばさないよう、上限を種類ごとの候補 6 件と取得の試み 30 回にし、`external-survey.md` の 1 か所に置く + +候補の数は、carul #102 の 2 回目の設計が出典つきで比べ切った量（ライブラリ 6・製品 6）に合わせる。取得の試みは、検索 1 回・URL の取得 1 回をそれぞれ 1 と数える。試みの上限は、3 種類 × 6 件の候補にそれぞれ 1 回余りの取得を足した量である。この量は、設計のステップの時間の上限（3,600 秒）の内に収まる。外部の調査の節の最後に「調べた量」の 1 行を残し、設計文書を数えれば上限が足りたかを実測できるようにする。値の見直しはこの参照の 1 か所を直す。 + +時間を上限にする形は採らない。担い手が経過の秒を測る手段がランタイムごとに違い、Claude Code と Codex で同じに働かない。プロジェクトの設定で上限を変える形も採らない。プロジェクトごとに変える理由がまだ実測で示されていない。 + +根拠: Value 3 / Value 4 / Value 6（MVV 版 5） + +### 決定 3: 通したか省いたかを 1 か所で読めるよう、外部の調査の節は通しても省いても必ず作り、省くときは `省く: <理由>` の 1 行だけを置く + +省いた理由を仕様の「対象範囲（含まない）」に書く既存の形（`deliverables.md` の「省いた理由の書き先」）は、成果物を書かない理由の置き場である。外部の調査は成果物ではなく手順で、省く判断は設計者が設計の書き先で行う（受け入れ条件 6）。節を必ず作れば、レビューと検査は節を見るだけで、通したか省いたかが分かる。要否表では全モード「必須」とし、省いたときも節が残る。 + +根拠: Value 2 / Value 8（MVV 版 5） + +### 決定 4: 自前で作る決定を機械が見分けられるよう、決定の中に `作り方:` と `比べた候補:` の 2 行を置き、候補を外部の調査の表の番号で指す + +2 行は箇条書き（`- 作り方: …` / `- 比べた候補: …`）で、決定の理由の段落の後に置く。`作り方:` の値は「自前で作る」「ライブラリやサービスを使う」「標準に倣う」の 3 語とその組み合わせ（`・` で並べる）に限る。標準を自前で実装する決定は「自前で作る・標準に倣う」と書き、検査の対象になる。比べた候補は `STD<数>` / `PRD<数>` / `LIB<数>` の番号で書き、表の行へ解決できることを検査が確かめる。番号の頭を種類ごとに分けるのは、要求の起票者の推定（`S1`…）・不変条件（`I1`…）・イベント（`E1`…）と取り違えないためである。2 つの欄を分ける形は STD1（MADR）に倣う。 + +決定の本文の語（「自前で」「独自に」など）から機械で推定する形は採らない。語の揺れで漏れと誤検知が両方出て、既存の設計文書でも当たる（受け入れ条件 10 を満たせない）。作り方の行はすべての決定に求めず、機能をどう得るかを選んだ決定にだけ書く。設計や手順の選び方の決定（この文書の決定 1 など）に書くと、意味の無い行が増える。 + +根拠: Value 5 / Value 8（MVV 版 5） + +### 決定 5: 受け入れ条件 8 の指摘は、機械の検査と設計 PR のレビューの観点の両方で行う + +機械の検査は、作り方の行を持つ決定に対して I5〜I7 を確実に見る。作り方の行を書かずに自前で作ると決めた設計と、外部の調査の節の欠け・出典の欠け（I1〜I4）は、文の意味を読まないと分からない。そのため、設計 PR の詳細レビューの観点にも載せる。機械の検査だけにすると、行を書かなければ通る。レビューだけにすると、ラウンドの上限（設計は 3）で指摘が残ったまま承認ゲート 1 へ渡りうる。 + +レビューの観点は、決定 10 の節（入出力の契約の「外部の調査の確認の観点」の設計 PR の行）が持つ。`review_focus.py` の `DESIGN_REVIEW_TEMPLATE` へ項目を直に足さない。足すと、`pr-review` と `cross-review` で同じ観点の文が 2 か所になる。観点は 2 つ目の PR で入る（決定 15）。 + +根拠: Value 5 / Value 1（MVV 版 5） + +### 決定 6: 検査は新しいエントリポイント `design-survey.py` にし、設計文書の探し方を `design-match.py` と `lib/design_docs.py` で共有する + +`design-match.py` は、完了判定で設計と実装を突き合わせる検査である。打つ時期（実装の後）と読み手（`quality-gates`）が違う。副命令として足すと、1 つのエントリポイントが 2 つの工程の契約を持つ。一方、課題の番号から HEAD の設計文書を探す処理は同じ役割なので、`lib/design_docs.py` へ移して 2 つから読む。Markdown の読み方は LIB1 を包む `lib/md.py` を使い、自前で書かない。 + +- 作り方: ライブラリやサービスを使う +- 比べた候補: LIB1 + +`glossary.py` や `pr-body-decisions.sh` へ足す形は採らない。前者は語の検査、後者は PR の本文と見出しの突き合わせで、責務が違う。 + +根拠: Value 7 / Value 5（MVV 版 5） + +### 決定 7: 検査はスプリントの設計のプランと `design` の手順 5 から打ち、継続的統合には置かない + +設計のプランのステップと Skill の手順は、NDF を使うすべてのリポジトリで同じに通る。継続的統合のワークフローはこのリポジトリにしか効かず、ほかのリポジトリには届かない。このリポジトリの設計 PR も設計のプランを通るため、継続的統合に重ねても新しく捕まえるものが無い。プランでは、レビューの直しで決定が変わった後に確かめるため、`requirements-recheck` の後に置く。直しは 1 回だけ試み（`fix-survey`）、残れば止める。同じ指摘のラウンドを重ねない。 + +継続的統合の必須のチェックにする形は採らない。ruleset の変更が要り、ほかのリポジトリでは働かない。 + +根拠: Value 6 / Value 3（MVV 版 5） + +### 決定 8: 調査の結果の形は、棚卸しのシーズの調査と出典の項目だけ揃え、記録の置き場と形式は揃えない + +揃えるのは、出典を URL・パス・コマンドのどれかと取得日で書くことである（シーズの調査の記録は `url` / `path` / `command` と調べた日時を持つ）。外部の調査はシーズの調査の記録（`.ndf/backlog/research/`）に同じ対象があれば、その記録のパスと調べた日時を出典として引いてよい。設計文書は承認する人が読む Markdown で、シーズの調査は機械が積む JSON であり、読み手が違う。置き場と形式を揃えると、設計の工程が棚卸しの記録の形に縛られる。 + +根拠: Value 7 / Value 8（MVV 版 5） + +### 決定 9: `legacy-refactor` でも外部の調査を通すため、このモードの設計文書を 4 節（現状の構造・変更後の構造・外部の調査・決定の記録）にする + +自前の実装をライブラリへ置き換えるリファクタリングは、外部の調査が最も効く変更の 1 つである。`deliverables.md` は「`legacy-refactor` の無条件の成果物は 3 節に収まるものに限る」としている。節を足すと、要否表とテンプレートが食い違う。テンプレートと段落の両方を 4 節に直す。振る舞いを変えないリファクタリングの多くは「既存の形の延長」として省け、そのときの費用は 1 行である。 + +根拠: Value 6 / Value 7（MVV 版 5） + +### 決定 10: 2 つのレビューの担当が同じ観点を受け取るよう、観点の正本を `pr-review` の SKILL.md の節に置き、`cross-review` はその節を読む + +`pr-review` は `## 観点` の節を正本にしている。委譲のプロンプトもこの節を丸ごと写す（`pr-review-steps.py` の `perspectives`）。節の中に小見出しを足せば、Claude 自身のレビューと委譲の両方に、コードを変えずに届く。`cross-review` の観点は `review_focus.py` の文字列の定数で、`pr-review` の観点とは別に持っている。同じ文を定数にも写すと、2 か所を揃えて直す手間と食い違いが生まれる。`review_focus.py` は `gh_sections.get_section` で節を読む。`gh_sections` は、`review_lib` が `sys.path` に足すライブラリ（`plugins/ndf/scripts/lib/`）にある。新しい依存は増えない。`pr-review` と `cross-review` は、Claude Code と Codex の両方の manifests に載っている。そのため、`cross-review` を配る先には必ず `pr-review` の SKILL.md がある。 + +`design` の参照（`external-survey.md`）に観点を置く形は採らない。`pr-review` の委譲のプロンプトは `## 観点` の節だけをコピーし、ほかのファイルを担当へ渡さない。参照を読ませる手順を足すと、委譲の処理を変えることになる。観点の文を Python の定数に置き、`pr-review` の SKILL.md から指す形も採らない。Claude 自身のレビューは SKILL.md を読んで進むため、文が SKILL.md に無ければ届かない。 + +観点の中身（比べた候補の見落とし・出典の古さ）は STD3 に倣う。 + +根拠: Value 8 / Value 7（MVV 版 5） + +### 決定 11: 観点は分類 `design` か `code` を持つ PR に載せ、プロファイルが既定の分類を外しても載せる + +`cross-review` の分類（`categories.py`）では、設計 PR は `issues/` の設計文書の名前から `design` になる。実装 PR はコードの拡張子から `code` になる。ドキュメントだけの PR（`docs_only` だけで `design` を持たない）には載らない。設計 PR の 1 ラウンド目のモデルレビューは、ドメインモデルの節の外への指摘を書かせないため、観点を足さない。詳細レビューの観点（`review_instructions_by_stage.detail`）は `review_instructions` と同じ文である。そのため、`_auto_review` で足せば両方に入る。 + +プロジェクトのプロファイルが `replace_auto_categories` で既定の分類を外しても、この観点は外さない。外部の調査の確認は、プロジェクトの MVV やレビューの宣言に依らず働く（受け入れ条件 9）。分類 `design` / `code` の判定は、プロファイルの前の既定の分類（`_classify_changed_files` の結果）で行う。 + +`.md` だけを変える NDF の Skill の実装 PR は `docs_only` になり、観点が載らない。Skill の手順の文の変更でライブラリを足すことはないため、受け入れる。 + +根拠: Value 6 / Value 2（MVV 版 5） + +### 決定 12: 出典を古いと見る基準は、取得日が設計 PR を出した日より 90 日以上前、または取得日の後に新しい版か終了のアナウンスが出ていること、にする + +90 日は STD2（OpenSSF Scorecard の Maintained）が保守の活動を見る期間である。ライブラリの保守の状態の判定と同じ物差しになる。STD3 は決定の記録に見直しの日を持つよう求めており、取得日をその目印に使う。2 つ目の条件は、担当が自分で取得して新しい版か終了のアナウンスを確かめたときだけ当たる。取得日の古さは表の行を読むだけで判定でき、外部の取得を要しない。 + +日数をプロジェクトの設定で変える形は採らない。決定 2 と同じく、変える理由がまだ実測で示されていない。 + +根拠: Value 4 / Value 6（MVV 版 5） + +### 決定 13: レビューの担当の取得の試みは 1 ラウンドに 10 回までにし、`design` の上限（30 回）とは別の値にする + +担当がするのは、設計が出した表の確認と、自前で作る決定・新しい依存・古い出典の行に絞った調べで、設計の外部の調査のやり直しではない。`cross-review` は 1 ラウンドに 2 つの担当を並べて起動する。1 担当 10 回なら 1 ラウンド 20 回で、設計の上限 30 回を下回る。担当の起動には時間の上限があり、外部の取得でラウンドの所要を延ばしすぎない（非機能の条件）。値は観点の節の 1 か所に置き、`design` の上限（`external-survey.md`）と共有しない。2 つの値は数える対象が違い、片方を直すときにもう片方を直す理由が無い。 + +担当の取得の回数を機械で数えて止める形は採らない。担当のランタイムごとに取得の手段と記録が違い、数える場所が無い（受け入れ条件 16 は観点に書くことを求める）。 + +根拠: Value 3 / Value 6（MVV 版 5） + +### 決定 14: 実装 PR の担当は、設計文書のパスを渡されず、PR の題と本文とブランチ名の課題の番号から worktree の設計文書を探す + +`cross-review` の状態ファイルは課題の番号を持たない。担当へ渡す材料に設計文書のパスを足すには、`init` で課題の番号を解く処理が要る。NDF の Pull Request は、題か本文に課題の番号を持つ。設計文書は、`issues/issue-<番号>-design*.md` の名前の規則で worktree にある。担当は worktree を読めるため、探す手順を観点に書けば足りる。見つからないときは、設計が無いことを指摘にせず、見つからなかったことを総評に書く。設計を通さないモード（`light`・`operation`）の実装 PR があるためである。 + +`design-survey.py check --issue` を担当に打たせる形は採らない。NDF の外のリポジトリの worktree には NDF のスクリプトが無く、担当が導入先のパスを知る手段も無い。 + +根拠: Value 5 / Value 6（MVV 版 5） + +### 決定 15: 実装を 2 つの PR に分け、1 つ目に `design` の手順と検査、2 つ目にレビューと `cross-review` の観点を置く + +MVV 版 5 の Value 2 は、一度に作る量の上限を「人が 1 回の承認で読み切れる量」で決め、数値を実測から決めるとしている。数値はまだ決まっていない。そのため、分け方は利用者の指摘の例に合わせ、読み手が 1 つの主題で読み切れる単位にする。1 つ目は構成要素の表の PR 1 の 14 行（新しいスクリプト 2 本・テスト・設計のプランの期待値を含む）、2 つ目は PR 2 の 4 行である。2 つ目の観点は、1 つ目が決める節の名前と行の形（外部の調査・作り方・比べた候補）を見るため、1 つ目を先にマージする。 + +受け入れ条件 8 の「設計 PR のレビューの観点」の側は、2 つ目の PR が持つ。観点の文は受け入れ条件 12 と同じで、1 つ目に入れると決定 10 の正本が 2 つ目まで置けず、文が 2 か所になる。1 つ目の時点では、受け入れ条件 8 の指摘を機械の検査が持つ。版はスプリント単位で上げるため、2 つの PR は同じスプリントで出し、その間にリリースを挟まない。 + +根拠: Value 2 / Value 8（MVV 版 5） + +## テスト設計 + +| 受け入れ条件・不変条件 | どの振る舞いで縛るか | どう壊したら落ちるべきか | +| --- | --- | --- | +| I5・受け入れ条件 8（指摘する例） | 外部の調査の表を持ち、作り方が「自前で作る」で比べた候補の行が無い決定を持つ文書に、`check` が 1 と `no_candidates` を返す | 作り方の行を読まないように壊すと 0 になり落ちる | +| I5・受け入れ条件 8（指摘しない例） | 比べた候補に表の番号を並べた決定と、`省く:` の行を持つ課題の自前で作る決定に、`check` が 0 を返す。`省く:` の行が `-design.md` にあり自前で作る決定が `-design-decisions.md` にある分けた文書でも 0 を返す。`省く:` の行が `issue-7-design.md` にあり自前で作る決定が `issue-7-8-design.md` にあるときも、`--issue 7`・`--issue 8`・`--issue 7 8` のどれでも 0 を返し、同じ決定の指摘を重ねない | 省いた課題の判定を外すか、ファイルごとに閉じて判定するか、番号を 2 つ含む文書を番号ごとのまとまりへ重ねて入れるか、`--issue 8` で読む文書をつながりで閉じずに `issue-7-design.md` を読まないと 1 になり落ちる | +| I6 | 表に無い番号を並べた決定に `unknown_candidate` を返す。番号が `-design-decisions.md` にあり表が `-design.md` にある分けた文書でも解決する。`--issue A B` で、課題 A の決定が課題 B の表にだけある番号を並べると `unknown_candidate` を返す。`issue-7-8-design.md` の決定が `issue-7-design.md` の表にだけある番号を並べたときと、`issue-7-design.md` の決定が `issue-8-design.md` の表にだけある番号を並べたときは、`--issue 7`・`--issue 8`・`--issue 7 8` のどれでも `unknown_candidate` を返さず、指摘も 1 件も出さない | 節を文書ごとに閉じて読むと分けた文書で当たり、読んだ文書すべての節を合わせるとほかの課題の表で解決して当たらず、番号を 2 つ含む文書を番号ごとのまとまりへ重ねて入れると 8 のまとまりで当たり、`--issue 8` で読む文書をつながりで閉じないと `issue-7-design.md` の表を読まずに当たり、いずれも落ちる | +| I7 | 3 語に無い値（「自前でつくる」）に `unknown_method` を返す。「自前で作る・標準に倣う」は自前で作る決定として扱う | 値を分けずに完全一致で比べると、組み合わせで落ちる | +| コードブロックの扱い | コードブロックの中の `作り方: 自前で作る` には当たらない | コードブロックを読むと、テンプレートの例を含む文書で落ちる | +| 受け入れ条件 10 | このリポジトリの `issues/` にある既存の設計文書と受け入れ条件のファイルすべてに、`check --file` が 0 を返す | 作り方の行が無い文書を違反にすると落ちる | +| 受け入れ条件 9 | `.ndf/` を持たないリポジトリで `check` が同じ結果を返す | MVV の宣言を読むようにすると、宣言の無い場で 2 になり落ちる | +| 終了コード 3 | `--issue` に文書の無い番号を渡すと 3 を返す | 0 を返すと、設計のプランが文書の無いまま通り落ちる | +| `lib/design_docs.py` への移動 | 既存の `design-match.py` のテストが変えずに通る | 探し方の規則を変えると既存のテストが落ちる | +| 設計のプラン（決定 7） | 設計のプランの期待値（`1-design-16.json`）に、3 ステップが `requirements-recheck` と `glossary-check` の間にあり、`survey-recheck` が `on_fail` を持たない | 順序か `on_fail` を変えると契約のテストが落ちる | +| I1〜I4・受け入れ条件 1〜7 | 手順とテンプレートの文。文言のテストは書かない（`AGENTS.md` の DON'T）。設計 PR のレビューの観点（決定 5）と、リリース後の手動確認で見る | — | +| I9・受け入れ条件 14（載る例） | 変更ファイルが `issues/issue-1-design.md` だけの PR と、`.py` を含む PR の自動レビュー観点に、`pr-review` の SKILL.md の節 `### 外部の調査の確認` を `get_section` で読んだ文がそのまま含まれる。`replace_auto_categories` のプロファイルを当てても含まれる。設計 PR の詳細レビュー（`detail`）の観点にも含まれる | 分類で絞らずに足すか、プロファイルの後の分類で判定するか、`detail` へ入れないと落ちる。期待値は SKILL.md から読んだ文で、文言を固定しない | +| I9・受け入れ条件 14（載らない例） | 変更ファイルが `docs/a.md` だけの PR の観点に節の文が含まれない。設計 PR のモデルレビュー（`model`）の観点に含まれない | 分類を見ずに常に足すと落ちる | +| I8 | 節を持たない SKILL.md を読ませると、観点を組む処理が 1 で終わる | 節が無いまま空の観点で続けると落ちる | +| 受け入れ条件 12・13・15・16 | 節の文。文言のテストは書かない。リリース後の手動確認（`cross-review` を設計 PR か実装 PR で 1 回通す）で、指摘が出るか、出ないときに担当が観点を見た跡があるかを見る | — | +| 受け入れ条件 11 | `python3 scripts/check-skill-frontmatter.py`・`claude plugin validate .`・全体テスト・`python3 scripts/check-ndf-contracts.py` が通り、`design-template.md` が 500 行以内 | — | +| 受け入れ条件 17 | 2 つの PR のそれぞれで全体テストが通る。2 つ目の PR を 1 つ目のマージの後の `develop` から作る | — | + +## 設計の結果 + +| 課題 | 扱い | 取り込み先 | 触るファイル | +| --- | --- | --- | --- | +| #2519（1 つ目の PR） | 実装する | — | `plugins/ndf/skills/design/`、`plugins/ndf/scripts/design-survey.py`、`plugins/ndf/scripts/lib/design_docs.py`、`plugins/ndf/scripts/design-match.py`、`plugins/ndf/scripts/supervise_lib/paths.py`、`plugins/ndf/scripts/supervise_lib/sprint_waves.py`、`plugins/ndf/scripts/tests/`、`plugins/ndf/contracts/`、`docs/glossary/glossary.json`、`docs/glossary.md` | +| #2519（2 つ目の PR） | 実装する | — | `plugins/ndf/skills/pr-review/SKILL.md`、`plugins/ndf/skills/cross-review/scripts/review_lib/review_focus.py`、`plugins/ndf/skills/cross-review/docs/04-contracts.md`、`plugins/ndf/skills/cross-review/tests/` | + +## 未確認のまま残ること + +| 項目 | 内容 | +| --- | --- | +| 上限の値が足りるか | 候補 6 件・取得の試み 30 回は carul の 1 例から決めた。リリース後に NDF の外のプロジェクトで `design` を通し、設計文書の「調べた量」の行を数えて見直す | +| 作り方の行の書き漏れ | 作り方の行を書かずに自前で作る決定は、検査に掛からずレビューだけが拾う。漏れの件数はリリース後の設計 PR のレビューの指摘で数える | +| 検査の既存の Tool | 外部の調査の「確かめられなかったこと」の 1 行。実装で `lib/md.py` の上に書く規模が数十行を大きく超えるなら、既存の Tool を探し直す | +| 取得の手段がランタイムで違うこと | 手順は Web 検索・URL の取得・`gh` のどれかを使うとだけ書く。Codex で `design` を通したときに取得できる範囲は未確認で、リリース後の手動確認で見る | +| レビューの担当が外部を取得できるか | 担当の起動は codex が `--dangerously-bypass-approvals-and-sandbox`、kiro が `--trust-all-tools` で（`external-ai` の `references/cli-codex.md`・`cli-kiro.md`）、シェルからの取得はできる。codex の Web 検索の機能を起動の引数で有効にしているかは確かめていない。この変更では起動の引数を変えない（要求の前提 9）。リリース後の手動確認で、担当が出典つきの指摘を出せたかを見る | +| 担当の上限 10 回が足りるか | 決定 13 の値は、設計の上限 30 回を 2 担当で下回る量として決めた。実測は無い。リリース後に担当の結果の総評で上限に当たった件数を数えて見直す | +| PR の量の上限 | MVV 版 5 の Value 2 の数値は未定で、決定 15 の分け方は利用者の指摘の例に合わせた。数値が決まったら、1 つ目の PR（構成要素 14 行）がそれに収まるかを見直す | +| 実装 PR で設計文書が見つかるか | 決定 14 は、PR の題か本文かブランチ名に課題の番号があることを前提にする。番号を持たない PR の割合は数えていない | + +## 指摘への対応 + +設計の承認ゲート 1 での利用者の指摘（2026-11-05、直して出し直す）への対応。PR の本文の材料にする。 + +| 指摘 | 直した箇所 | 直せない理由 | +| --- | --- | --- | +| 外部の調査の確認を、design の工程だけでなく、レビューの工程（pr-review）と cross-review の工程にも入れる | 目的・適用範囲、集約「外部の調査の確認の観点」と不変条件 I8〜I11、イベント E9〜E11、機能 F6〜F9、構成要素の PR 2 の行、決定 10・11 | — | +| 設計 PR・実装 PR のレビューで、外部の調査の節と決定ごとの作り方・比べた候補を観点として見る。自前で作るのに比べた候補が無い、出典が無い・古い点を指摘にする | 入出力の契約「外部の調査の確認の観点」の表（設計 PR 4 行・実装 PR 1 行）、決定 12（古さの基準 90 日）、決定 14（実装 PR の担当が設計文書を探す）、テスト設計の I9 の行 | — | +| cross-review の担当（codex・kiro・claude など）への起動指示にも同じ観点を載せ、担当が自分で外部を調べて、より良い標準やライブラリがあれば指摘できるようにする | 決定 10（正本を 1 つにし、`review_focus.py` が読む）、入出力の契約の「外部を調べるときの規則」、決定 13（担当の上限 10 回）、処理の流れのレビューの図 | 担当の取得の手段（codex の Web 検索の有効化など）は広げない。要求の前提 9 で取得の権限を変えないとしたためで、取得できない担当は推定で指摘せず、取得できなかったことを書く（未確認のまま残ることの 1 行目） | +| design の手順・テンプレート・design-survey.py の検査はこの設計のまま残す | 決定 1〜4・6〜9、入出力の契約の `design-survey.py check` と設計のプランのステップ、テスト設計の検査の行は変えていない。決定 5 は、設計 PR のレビューの観点の置き場を決定 10 の節へ移した（観点の中身は同じ） | — | +| 量が増えるので、MVV 版 5 の量の上限に照らして実装の PR を分ける（例: design の手順と検査 / レビューと cross-review の観点） | 決定 15、構成要素の表の列「PR」、設計の結果の 2 行 | 量の上限の数値は MVV 版 5 でまだ決まっていないため、数値に照らした判定はできない。分け方は指摘の例に合わせた（未確認のまま残ることの「PR の量の上限」） | diff --git a/issues/issue-2519-requirements.md b/issues/issue-2519-requirements.md new file mode 100644 index 000000000..70d26ced3 --- /dev/null +++ b/issues/issue-2519-requirements.md @@ -0,0 +1,231 @@ +# #2519: design: 設計の前に外部の最新動向・事実上の標準・既存のライブラリを調べ、判断に反映する手順を足す + +正は課題の本文（#2519）で、この文書はその写しである。`spec-copy.py write` で作り直す。手で直さない。 + +## 何が困っているか + +`design` など設計の Skill には、設計の前に外部の最新動向・事実上の標準（デファクトスタンダード）・使える既存のライブラリやサービスを調べ、その結果を設計の判断に反映する手順が無い。設計の雛形には「あるべき姿の根拠」の表（種類に「外部の一次情報」がある）はある。しかし「何を調べるか」「いつ調べるか」「調べた結果で何を決めるか」は決まっていない。 + +そのため設計は、手元のコードと要求の文だけから組み立てられる。業界の標準の形や枯れたライブラリがあっても、自前で作る設計になったり、古い形のまま決まったりする。利用者が後から気づいて指示し、設計をやり直すことになる。 + +## 具体例: carul（volareinc/carul、2026-11） + +| 課題 | 起きたこと | 利用者が後から指示したこと | +| --- | --- | --- | +| 権限のモデル（carul #102） | 最初の設計は、所属に役職を持たせ「管理者の役職なら全店舗」という固定の規則で判定する形だった。IAM の利用者・ロール・ポリシーの形や、Cedar・Amazon Verified Permissions などの既存の選択肢を比べていなかった | 権限を全面的に設計し直す。IAM に倣い、AVP・Cedar・自前の 3 案をフラットに比べる。エージェントは人と別の主体にし、最新の権限付与（委任・短期のトークン）に準拠する | +| CRM・顧客の ID の形 | 顧客の管理と認証を、乗り換え元（JOCAR）のデータの形に寄せて設計していた | JOCAR に寄せない。データモデルは RDBMS の理想の形で設計し、取り込みで変換する。認証・CRM・商品・UX は最新の動向に合わせる | +| 自前で作る判断（carul #117） | UI の部品・データの読み込み・表・オフラインの同期・TOTP・認可を、既存のライブラリ（shadcn/ui・TanStack Query・PowerSync など）と比べないまま自前で作ると決め、確定仕様にした | 自前で作ると決めた確定仕様を、ライブラリを使う案と比べて見直す | + +carul ではこの後、プロジェクトの MVV に Value 10（使える既存のものを先に調べる）と Value 11（世界の主要な製品の良さを取り込む）を足した。2 回目の #102 の設計は、9 つの観点で 3 方式を比べ、ライブラリの候補 6 つの保守の状態と採否、競合 6 製品の権限の形を、出典つきで載せた。プロジェクトの MVV で補うと、ここまでの調査ができた。ただ、この手順は本来 `design` の側が持つべきものである。MVV を持たないプロジェクトや、MVV にこの Value が無いプロジェクトでは、同じことが起きる。 + +## 依頼（原文） + +課題の題と、上の「何が困っているか」「具体例」、下の 2 つの節は、起票者が書いた本文である（書き手: 起票者、日付: 2026-11-05）。 + +> design: 設計の前に外部の最新動向・事実上の標準・既存のライブラリを調べ、判断に反映する手順を足す + +> ## 直し方の案 +> +> `design`（と、設計の材料を作る `requirements-design`）に、設計の判断の前に通す「外部の調査」の手順を足す。 +> +> 1. **調べる対象を決める。** 触る領域ごとに、次を調べるかを決める。 +> - 業界の事実上の標準・仕様（例: 認可なら IAM・Cedar・OAuth 2.1・RFC 8693・MCP の認可の仕様。認証なら NIST SP 800-63B） +> - 主要な製品・競合の形（同じ問題を世界の主要な製品がどう解いているか） +> - 使える既存のライブラリ・マネージドサービス（自前で作る前に） +> 2. **調べた結果を表に残す。** 一次情報の出典（URL と取得日）を付ける。ライブラリは、バージョン・ライセンス・保守の状態（最後のリリース・終了のアナウンス）・要件を満たすかを並べる。 +> 3. **判断へつなぐ。** 「自前で作る」「ライブラリを使う」「標準に倣う」のどれを採ったかを決定の記録に書き、採らない案とその理由を残す。自前で作る決定には、比べた候補を必ず並べる。 +> 4. **調べられなかったことを書く。** 公開の資料が無い・取得できなかった対象は、「確かめられなかったこと」として残す（`investigation-rules` に合わせる）。 +> 5. **省ける条件を決める。** 文言の修正や既存の形の延長など、外部の判断が要らない変更は省けるようにする。省いた理由は 1 行で残す。 +> +> 検査の案: 設計文書の決定の記録に「自前で作る」とあるのに、比べた候補（ライブラリ・サービス・標準）の行が無ければ、設計のレビューか `requirements-recheck` に相当する機械の確かめで指摘する。 +> +> ## 受け入れ条件（起票時） +> +> 1. `design` の SKILL.md（または references）に、上の 1〜5 の手順と、手順を省ける条件がある +> 2. 設計の雛形に、外部の調査の節（標準・製品・ライブラリの比較と出典）と、「確かめられなかったこと」の欄がある +> 3. 「自前で作る」決定に比べた候補が無い設計文書を、設計のレビューの観点か機械の検査が指摘する +> 4. プロジェクトの MVV に調査の Value が無くても、この手順が働く + +利用者の文として確かめられたのは、マイルストーン「35 開発フローの見直しと大整理」の説明に起票者が引いた次の 1 文だけである（書き手: 起票者が利用者の指示を引用、日付: 2026-11-05）。 + +> #2519 は利用者の指示で 1 位に置いた（2026-11-05。設計で問題が出ることが多いため、できるだけ早く着手する）。 + +この要求を書く工程の起動指示（書き手: AI の起動指示、日付: 2026-11-05）: 「人へ問わずに進め、決められない点は前提か未決として課題の本文へ書く」。 + +設計の承認ゲート 1 で利用者は「直して出し直す」と答え、次の指摘を書いた（書き手: 利用者。オーガナイザーが本文の末尾の節「設計の承認ゲート 1 での利用者の指摘（直して出し直す）」へ写した文を引く、日付: 2026-11-05）。この要求の受け入れ条件 12〜17 と前提 7〜10 は、この指摘から導いた。 + +> 直して出し直す。外部の調査の確認を、design の工程だけでなく、レビューの工程（pr-review）と cross-review の工程にも入れる。 +> - レビューの側の確認: 設計 PR・実装 PR のレビューで、触る領域の標準・主要な製品・既存のライブラリと比べたか（「外部の調査」の節と、決定ごとの「作り方」「比べた候補」）を観点として見る。自前で作るのに比べた候補が無い、出典が無い・古い、といった点を指摘にする +> - cross-review の担当（codex・kiro・claude など）への起動指示にも同じ観点を載せる。担当が自分で外部を調べて、より良い標準やライブラリがあれば指摘できるようにする +> - design の手順・雛形・design-survey.py の検査はこの設計のまま残す +> - 量が増えるので、MVV 版 5 の量の上限に照らして実装の PR を分ける（例: design の手順と検査 / レビューと cross-review の観点） + +出し直しの要求を書く工程の起動指示（書き手: AI の起動指示、日付: 2026-11-05）: 「課題の本文の要求と受け入れ条件を指摘に合わせる（レビューの工程 pr-review と cross-review の起動指示にも外部の調査の観点を入れる受け入れ条件を足し、実装の PR を分ける方針を書く）」「人へ問わずに進め、決められない点は前提か未決として本文へ書く」。 + +具体例の carul #102（権限のモデルを全面的に設計し直す、IAM に倣う）と carul #117（自前で作ると決めた確定仕様を見直す）は、2026-11-05 に `gh issue view <番号> -R volareinc/carul` で題と作成日（いずれも 2026-11-04）を確かめた。本文の「利用者が後から指示したこと」の列は起票者による要約で、carul の利用者の原文とは突き合わせていない。 + +## 起票者の推定 + +| # | 条件 | 推した出所 | この要求での扱い | +| --- | --- | --- | --- | +| S1 | 手順を「調べる対象を決める・表に残す・判断へつなぐ・確かめられなかったことを書く・省ける条件」の 5 つで組む | 本文「直し方の案」1〜5 | 受け入れ条件 1〜7 | +| S2 | `requirements-design` にも外部の調査の手順を足す | 本文「直し方の案」の冒頭の括弧書き | 含まない（前提 1） | +| S3 | 例に挙げた標準（IAM・Cedar・OAuth 2.1・RFC 8693・MCP の認可・NIST SP 800-63B）を手順に載せる | 本文「直し方の案」1 | 含まない。手順は例として示してよいが、領域ごとの標準の一覧を Skill に持たない（前提 2） | +| S4 | ライブラリは版・ライセンス・保守の状態（最後のリリース・終了のアナウンス）・要件を満たすかを並べ、出典は URL と取得日 | 本文「直し方の案」2 | 受け入れ条件 2・3 | +| S5 | 「自前で作る」決定に候補が無いものを、設計のレビューか機械の検査が指摘する | 本文「検査の案」・受け入れ条件 3 | 受け入れ条件 8。機械の検査と設計 PR のレビューの観点の両方で指摘する（設計で決め、利用者が承認ゲート 1 で設計のまま残すと答えた。未決の項目 1） | +| S6 | プロジェクトの MVV に調査の Value が無くても働く | 本文「受け入れ条件」4 | 受け入れ条件 9 | +| S7 | 調べられなかったことの書き方を `investigation-rules` に合わせる | 本文「直し方の案」4 | 受け入れ条件 5 | + + +## 目的 + +- 設計が手元のコードと要求の文だけから組み立てられ、業界の標準の形・枯れたライブラリ・主要な製品の解き方を比べないまま「自前で作る」「古い形に寄せる」と決まる状態をなくす +- 設計の承認（承認ゲート 1）の時点で、承認する人が「何と比べてこの形にしたか」を出典つきで読めるようにし、利用者が後から気づいて設計をやり直す手戻りを減らす +- 設計を書く側だけに頼らず、設計 PR・実装 PR のレビューでも「標準・主要な製品・既存のライブラリと比べたか」を確かめる。比べた候補の欠け・出典の欠けと古さ、より良い標準やライブラリの見落としを、レビューの指摘として承認の前に拾う +- プロジェクトの MVV に調査の Value を足さなくても、`design` とレビューの工程を通すだけでこの調査と確認が行われるようにする + +## 前提 + +- 前提 1: 外部の調査は `design` の手順に置き、`requirements-design` には足さない。要求は「何を満たすか」を決め、標準・製品・ライブラリとの比較は「どう作るか」の判断の材料だからである。調べる対象は、`design` の手順 1 で決める触る領域から決める +- 前提 2: 領域ごとに調べるべき標準・製品・ライブラリの一覧を Skill に持たない。一覧は古くなり、プロジェクトごとに領域が違う（Value 6）。手順は「何の種類を調べるか」と「調べた結果の形」だけを決め、例は読み手の理解のために示すにとどめる +- 前提 3: 外部の調査は、`design` を通すすべてのモードで「通すか省くか」を決める。省ける条件に当たる変更（文言・書式の修正、既存の形の延長、外部の判断が要らない変更）は、省いた理由を 1 行残して省く。`light` / `operation` で `design` を通さない変更には掛からない +- 前提 4: 一次情報の取得は、設計を書くエージェントが手元の取得の手段（Web 検索・URL の取得・`gh` など）で行う。取得できなかったものを推定で埋めない +- 前提 5: 既存の設計文書（`issues/` の過去の設計、`docs/specifications/` の確定仕様）を遡って直さない。手順と検査は、この変更の後に書く設計文書に効く +- 前提 6: 棚卸しの見直しで行う「シーズの調査」（ライブラリの競合・周辺環境の変化を調べて起票する。#2315）とは時期と目的が別である。結果の形は出典の項目だけ揃える（設計で決めた。未決の項目 2） +- 前提 7: `design` の手順・設計文書の雛形・検査のスクリプト（`design-survey.py`）は、承認ゲート 1 に出した設計（設計 PR #2523 の `issues/issue-2519-design.md`）の形のまま残す（利用者の指摘）。設計へ新たに足すのは、レビューの側の確認（受け入れ条件 12〜16）と、実装の PR の分け方（受け入れ条件 17）である +- 前提 8: レビューの側の確認は、レビューの工程の 2 つの経路に載せる。1 つは `pr-review` の観点（単独のレビュー）で、もう 1 つは `cross-review` が担当（codex・kiro・claude など）を起動するときに渡す観点である。設計 PR と実装 PR の両方に載せる。設計 PR では設計文書の外部の調査の節と決定の作り方・比べた候補を見る。実装 PR では、差分が同じ課題の設計の作り方と比べた候補に沿っているかを見る +- 前提 9: レビューの担当が自分で外部を調べる取得の手段は、担当のランタイムがすでに持つもの（Web 検索・URL の取得など）に限る。この変更で担当の取得の権限やサンドボックスの設定を広げない。取得できない担当は、推定で「より良いものがある」と指摘せず、取得できなかったことを指摘の本文に書く（前提 4 と同じ規則） +- 前提 10: 実装は 2 つの PR に分ける。1 つ目は `design` の手順・雛形・検査のスクリプトと用語集、2 つ目は `pr-review` の観点と `cross-review` の起動指示の観点である。MVV 版 5 の Value 2 は量の上限の数値を実測から決めるとしており、この要求の時点で数値は決まっていない。そのため、分け方は利用者の指摘の例に合わせる。2 つ目の観点は 1 つ目が決める節の名前と行の形（外部の調査・作り方・比べた候補）を参照するため、1 つ目を先にマージする。版はスプリント単位で上げるため、2 つの PR は同じスプリントで出す + +## 対象範囲 + +含む: +- `design` の手順に、外部の調査（調べる対象の決定・結果の表・決定への反映・確かめられなかったことの記録・省ける条件・調べる量の上限）を足す +- 設計文書の雛形に、外部の調査の節を足す +- 「自前で作る」と決めた決定に比べた候補が無い設計文書を指摘する仕組み（機械の検査 `design-survey.py` と、設計 PR のレビューの観点） +- `pr-review` の観点に、外部の調査の確認（設計 PR・実装 PR）を足す +- `cross-review` の担当への起動指示に、同じ観点と、担当が自分で外部を調べて指摘してよいことを足す（設計 PR・実装 PR） +- 用語集へ新しい語を足す +- 実装を 2 つの PR に分ける + +含まない: +- `requirements-design` の手順の変更（前提 1） +- 領域ごとの標準・製品・ライブラリの一覧（前提 2） +- 既存の設計文書・確定仕様の遡った修正（前提 5）。carul #117 のような既存の決定の見直しは、各プロジェクトの課題で行う +- 棚卸しのシーズの調査（#2315）の変更 +- 外部の調査を行う新しい Skill・エージェントの追加 +- レビューの担当の取得の権限・サンドボックスの設定の変更（前提 9） +- `cross-refactoring` の提案の担当への観点の追加（利用者の指摘はレビューの工程を挙げており、リファクタリングの提案は挙げていない） + +## ドメインイベント + +| # | イベント | 引き金 | 失敗したとき | 順序の前提 | +| --- | --- | --- | --- | --- | +| E1 | 設計で触る領域を決めた | `design` の手順 1 | 既存のとおり（受け入れ条件が無ければ要求へ戻る） | — | +| E2 | 外部の調査を通すか省くかを決めた | E1 | 省ける条件に当たるか決められないときは、通す側に倒す（受け入れ条件 6） | E1 | +| E3 | 調べる対象（標準・仕様 / 主要な製品 / 既存のライブラリとサービス）を決めた | E2 で通すと決めた | 3 種類のどれも当たらないと判断したら、種類ごとに理由を 1 行残す（受け入れ条件 1） | E2 | +| E4 | 一次情報を取得した | E3 | 取得できない・公開の資料が無い対象は、確かめられなかったことへ移す（受け入れ条件 5） | E3 | +| E5 | 調べる量の上限に当たって調査を止めた | 上限（候補の数か時間） | 残りの対象を確かめられなかったことへ移す（受け入れ条件 4） | E3 | +| E6 | 調べた結果を設計文書の外部の調査の節に残した | E4 または E5 | — | E4 | +| E7 | 決定の記録に、自前で作る・ライブラリやサービスを使う・標準に倣うのどれを採ったかと、比べた候補を書いた | E6 | 候補が無いまま自前で作ると書いた設計は、E8 で指摘される | E6 | +| E8 | 自前で作る決定に比べた候補が無い設計文書を指摘した | 機械の検査と設計 PR のレビュー | 指摘を直すまで承認ゲート 1 へ渡らない（既存の設計 PR の流れのとおり） | E7 | +| E9 | レビューが外部の調査の観点を受け取った | `pr-review` の開始、`cross-review` の担当の起動（設計 PR・実装 PR） | 観点が渡らなければ受け入れ条件 12・13 の確かめで落ちる | 設計 PR は E7、実装 PR は設計の承認の後 | +| E10 | レビューの担当が外部の一次情報を取得した | E9 で、より良い標準・ライブラリ・製品の形がありうると担当が判断した | 取得できなければ推定で指摘せず、取得できなかったことを書く（受け入れ条件 14）。上限に当たったら止める（受け入れ条件 15） | E9 | +| E11 | 比べた候補の欠け・出典の欠けと古さ・設計の作り方との食い違い・より良い候補の見落としを、レビューの指摘にした | E9 または E10 | 既存のレビューの流れのとおり（指摘を直すか、ラウンドの上限で止まる） | E9 | + +## 用語 + +| 用語 | 意味 | +| --- | --- | +| 外部の調査 | 設計の判断の前に、業界の事実上の標準・仕様、主要な製品の解き方、使える既存のライブラリとマネージドサービスを一次情報で調べ、設計文書に残す手順 | +| 自前で作る決定 | 既存のライブラリ・サービス・標準の実装を使わず、プロジェクトの中で作ると決めた決定の記録 | +| 確かめられなかったこと | 外部の調査で、公開の資料が無い・取得できなかった・上限で止めた対象と、その理由（取得の拒否・HTTP の状態・ネットワークの誤り・上限）を並べた欄 | +| 作り方 | 決定の記録の中の 1 行。その決定が機能をどう得るか（自前で作る / ライブラリやサービスを使う / 標準に倣う）を書く | +| 比べた候補 | 決定の記録の中の 1 行。外部の調査の表で比べた行の番号を並べる | + +## 受け入れ条件 + +`design` の手順・雛形・検査（承認ゲート 1 に出した設計のまま残す。前提 7）: + +- [ ] 1. `design` の手順に、外部の調査の手順がある。調べる対象の 3 種類（業界の事実上の標準・仕様 / 主要な製品の解き方 / 使える既存のライブラリとマネージドサービス）ごとに調べるかを決め、調べない種類には理由を 1 行残すと書かれている +- [ ] 2. 設計文書の雛形に外部の調査の節があり、標準・仕様、主要な製品、ライブラリとサービスの比較の表と、確かめられなかったことの欄を持つ。どの表の行も出典（URL と取得日）の列を持つ +- [ ] 3. 雛形のライブラリとサービスの表は、版・ライセンス・保守の状態（最後のリリースの日付・終了のアナウンスの有無）・要件を満たすかの列を持つ +- [ ] 4. 手順に調べる量の上限（候補の数か時間）があり、上限に当たったら調査を止め、残りの対象を確かめられなかったことへ書くと書かれている +- [ ] 5. 手順に、取得できなかった対象・公開の資料が無い対象を推定で埋めず、URL か検索の語と理由を確かめられなかったことへ書くと書かれている。書き方は `investigation-rules` の否定的な結論のエビデンスの規則と食い違わない +- [ ] 6. 手順に省ける条件があり、省いたときは理由を 1 行、設計の書き先（`deliverables.md` の「設計の書き先」）に残すと書かれている。省けるか決められないときは通す +- [ ] 7. 決定の記録の書き方（`decisions.md`）に、自前で作る・ライブラリやサービスを使う・標準に倣うのどれを採ったかと、自前で作る決定には外部の調査の節で比べた候補を並べることが書かれている +- [ ] 8. 自前で作る決定に比べた候補が無い設計文書を、機械の検査と設計 PR のレビューの観点が指摘する。指摘の例（候補が無い決定を持つ設計文書）と、指摘されない例（候補を並べた決定・外部の調査を理由つきで省いた設計文書）で確かめられる +- [ ] 9. 手順・検査・レビューの観点は、プロジェクトの MVV が無いプロジェクト・MVV に調査の項目が無いプロジェクトでも働く。手順の文・検査の条件・観点の文が MVV の項目を参照しない +- [ ] 10. 既存の設計文書（`issues/` の過去の設計）があっても、機械の検査がその文書で落ちない（前提 5） +- [ ] 11. 退行しない: `python3 scripts/check-skill-frontmatter.py`・`claude plugin validate .`・全体テストが通る。設計文書の雛形は 500 行以内に収まる + +レビューの側の確認（`pr-review` と `cross-review`）: + +- [ ] 12. `pr-review` の観点に、外部の調査の確認がある。設計 PR では、設計文書の外部の調査の節と決定ごとの作り方・比べた候補を見て、次を指摘にすると書かれている: 自前で作る決定に比べた候補が無い / 調べた行に出典（URL と取得日）が無い / 出典の取得日が古い（古さの基準は未決の項目 4。設計で決まった） / 外部の調査の節が無い、または省いた理由が無い +- [ ] 13. `pr-review` の観点の実装 PR の側に、差分が同じ課題の設計の作り方・比べた候補に沿っているかを見ることが書かれている。指摘にする例: 設計で「ライブラリやサービスを使う」とした機能を自前で作った / 設計に作り方の行が無い自前の部品を足した / 新しく足した依存（ライブラリ・サービス）が設計の比べた候補に無い +- [ ] 14. `cross-review` が担当（codex・kiro・claude など、選ばれたすべての担当）を起動するときに渡す観点に、受け入れ条件 12（設計 PR）と 13（実装 PR）と同じ観点が載る。観点が載ることを、起動の観点を組む処理（`review_focus.py`）の単体テストで、設計 PR と実装 PR の両方について確かめる。ドキュメントだけの PR には載らない +- [ ] 15. `cross-review` の担当へ渡す観点に、担当が自分で外部の一次情報を調べ、より良い標準・ライブラリ・主要な製品の形があれば出典（URL と取得日）を添えて指摘してよいと書かれている。取得できないときは推定で指摘せず、取得できなかったこと（URL か検索の語と理由）を書くと書かれている（前提 9） +- [ ] 16. 担当が外部を調べる量に上限があり、観点に書かれている。上限の値は設計で決め、`design` の手順の上限と同じ置き場から読むか、違う値にする理由を設計に書く（未決の項目 5。設計で決まった） + +実装の進め方: + +- [ ] 17. 実装は 2 つの PR に分かれる。1 つ目は受け入れ条件 1〜11（`design` の手順・雛形・検査のスクリプト・用語集。受け入れ条件 8 のうち設計 PR のレビューの観点の側は除く）、2 つ目は受け入れ条件 12〜16 と、受け入れ条件 8 の設計 PR のレビューの観点の側（`pr-review` の観点と `cross-review` の起動の観点）を持つ。どちらの PR も単独で全体テストが通り、1 つ目を先にマージする（前提 10） + +## 非機能の条件 + +| 大項目 | 条件 | +| --- | --- | +| 運用・保守性 | 外部の調査が設計の所要を際限なく延ばさない。上限（受け入れ条件 4）の値は設計で決め、実測から見直せる場所に置く。レビューの担当の外部の調べも、レビューのラウンドの所要を際限なく延ばさない（受け入れ条件 16） | +| システム環境 | 手順と観点は Claude Code と Codex のどちらをホストにしても同じに働く。レビューの担当（codex・kiro・claude）ごとに取得の手段が違っても、観点の文は特定のランタイムだけの取得の手段を前提にしない | + +## 影響 + +| 対象 | 影響 | +| --- | --- | +| 公開インタフェース | 変わる（`design` の手順と設計文書の雛形に節が増える。`pr-review` の観点と `cross-review` の担当へ渡す観点に項目が増える）。既存の設計文書は遡って直さず、互換を保つ | +| データ | 無し（用語集に語が増える） | +| 既存の振る舞い | `design` を通す変更で、外部の調査を通すか省くかの判断と、その記録が増える。設計 PR・実装 PR のレビューで、外部の調査の確認の指摘が出うる。担当が外部を調べる分、レビューの 1 ラウンドの所要が延びうる（上限で抑える） | + +## 検証手段 + +| 項目 | 手段 | +| --- | --- | +| テスト | `uv run --frozen --project . --all-extras pytest . -q -n 4`。受け入れ条件 8 の指摘の例・指摘されない例と、受け入れ条件 10 の既存の文書を機械の検査のテストで確かめる。受け入れ条件 14 は、起動の観点を組む処理が設計 PR・実装 PR で観点を含み、ドキュメントだけの PR で含まないことをテストで確かめる | +| 静的解析 | `python3 scripts/check-skill-frontmatter.py` / `claude plugin validate .` / `python3 plugins/ndf/scripts/glossary.py check --file <設計文書>` | +| 手動確認 | リリース後に、NDF の外のプロジェクトで `design` を 1 回通し、外部の調査の節が出典つきで埋まること・自前で作る決定に候補が並ぶこと・取得できなかった対象が確かめられなかったことへ載ることを見る。同じプロジェクトの設計 PR か実装 PR で `cross-review` を 1 回通し、外部の調査の観点の指摘が出るか、出ないときに担当が観点を見た跡（指摘 0 件の理由）があるかを見る | + +## 前提とする取り決め + +| 項目 | 参照先 / 決めたこと | +| --- | --- | +| プロジェクト構造 | Skill の実体は `plugins/ndf/skills/` の 1 か所（`AGENTS.md`「NDFプラグインについて」）。配る Skill は `plugins/ndf/manifests/` が決め、この変更で Skill を増やさない | +| コーディング規約 | Skill の書き方は `plugins/ndf/skills/AUTHORING.md`、文書は `document-style`。`.md` の文言を照合するテストを書かない（`AGENTS.md`「DON'T」） | +| テスト戦略 | 機械の検査の振る舞い（指摘する / しない / 既存の文書で落ちない）と、起動の観点を組む処理の振る舞い（PR の種類ごとに観点を含むか）を単体テストで縛る。Skill の手順の文は文言のテストで縛らない | + +## 境界 + +| 区分 | 内容 | +| --- | --- | +| 常に行う | 全体テスト・frontmatter のチェック・用語チェックの実行。新しい語の用語集への反映 | +| 確認してから行う | 設計 PR のレビューの観点の追加、機械の検査の追加、`pr-review` と `cross-review` の観点の追加（承認ゲート 1・2 で人が見る） | +| 行わない | 既存の設計文書と確定仕様の書き換え、`requirements-design` の手順の変更、領域ごとの標準の一覧の作成、新しい Skill の追加、レビューの担当の取得の権限・サンドボックスの設定の変更 | + +## 未決 + +| 項目 | 誰が決めるか | 期限 | +| --- | --- | --- | +| 1. 受け入れ条件 8 の指摘の置き場。設計で「機械の検査と設計 PR のレビューの観点の両方」と決め、利用者が承認ゲート 1（2026-11-05）で検査を設計のまま残すと答えた。決まった | 設計（`design`） | 済み | +| 2. 外部の調査の結果の形を、棚卸しのシーズの調査（#2315）と揃えるか。設計で「出典の項目だけ揃える」と決めた。決まった | 設計（`design`） | 済み | +| 3. 調べる量の上限の値と置き場。設計で「種類ごとの候補 6 件と取得の試み 30 回、`external-survey.md` の 1 か所」と決めた。決まった | 設計（`design`） | 済み | +| 4. レビューで「出典が古い」と指摘する基準。設計で「取得日が設計 PR を出した日より 90 日以上前、または取得日の後に新しい版か終了のアナウンスが出ていること」と決めた。決まった | 設計（`design`） | 済み | +| 5. レビューの担当が外部を調べる量の上限の値と置き場。設計で「1 ラウンドに取得の試み 10 回、`pr-review` の観点の節の 1 か所。`design` の上限とは共有しない」と決めた。決まった | 設計（`design`） | 済み | +| 6. 実装 PR のレビューで、同じ課題の設計文書をどう見つけて読むか。設計で「担当が PR の題・本文・ブランチ名の課題の番号から worktree の設計文書を探し、見つからなければ見つからなかったことを総評に書く」と決めた。決まった | 設計（`design`） | 済み | + +## 根拠にした MVV の項目 + +- Mission: 開発者が価値を利用者へ届けるまでの時間と費用を減らす（設計のやり直しの手戻りを減らす） +- Value 2: 人が判断できる量に収める（実装を 2 つの PR に分ける） +- Value 3: やめる・縮めるを既定にする（調べる量の上限と省ける条件。レビューの担当の調べにも上限を置く） +- Value 4: 外の利用で測って決める（carul での実際の手戻りが起点） +- Value 6: どのプロジェクトでも使える形を保つ（領域ごとの一覧を持たない・MVV に依らず働く・担当のランタイムに依らない観点の文） +- Value 7: 根本原因の場所で直す（プロジェクトの MVV で補うのでなく `design` とレビューの工程に置く）