design: 設計の前に外部の最新動向・事実上の標準・既存のライブラリを調べ、判断に反映する手順を足す #2519

何が困っているか

design など設計の Skill には、設計の前に外部の最新動向・事実上の標準（デファクトスタンダード）・使える既存のライブラリやサービスを調べ、その結果を設計の判断に反映する手順が無い。設計の雛形には「あるべき姿の根拠」の表（種類に「外部の一次情報」がある）はある。しかし「何を調べるか」「いつ調べるか」「調べた結果で何を決めるか」は決まっていない。

そのため設計は、手元のコードと要求の文だけから組み立てられる。業界の標準の形や枯れたライブラリがあっても、自前で作る設計になったり、古い形のまま決まったりする。利用者が後から気づいて指示し、設計をやり直すことになる。

具体例: carul（volareinc/carul、2026-11）

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 の利用者の原文とは突き合わせていない。

起票者の推定

目的

• 設計が手元のコードと要求の文だけから組み立てられ、業界の標準の形・枯れたライブラリ・主要な製品の解き方を比べないまま「自前で作る」「古い形に寄せる」と決まる状態をなくす
• 設計の承認（承認ゲート 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: 棚卸しの見直しで行う「シーズの調査」（ライブラリの競合・周辺環境の変化を調べて起票する。開発ワークフローに「見直し」と「大整理」を足す: 棚卸しを毎スプリントの差分の棚卸し・数回に 1 回の見直し・十数回に 1 回の大整理（根本原因の発見と組み直し、後回しの再評価）に分ける #2315）とは時期と目的が別である。結果の形は出典の項目だけ揃える（設計で決めた。未決の項目 2）
• 前提 7: design の手順・設計文書の雛形・検査のスクリプト（design-survey.py）は、承認ゲート 1 に出した設計（設計 PR design: 設計の判断の前に外部の標準・主要な製品・既存のライブラリを調べ、自前で作る決定に比べた候補を残す（#2519） #2523。確定仕様は docs/specifications/ndf-design-external-survey.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 Add: cross-refactoring — 多ランタイム・リファクタリング収束ループ (#113) #117 のような既存の決定の見直しは、各プロジェクトの課題で行う
• 棚卸しのシーズの調査（開発ワークフローに「見直し」と「大整理」を足す: 棚卸しを毎スプリントの差分の棚卸し・数回に 1 回の見直し・十数回に 1 回の大整理（根本原因の発見と組み直し、後回しの再評価）に分ける #2315）の変更
• 外部の調査を行う新しい Skill・エージェントの追加
• レビューの担当の取得の権限・サンドボックスの設定の変更（前提 9）
• cross-refactoring の提案の担当への観点の追加（利用者の指摘はレビューの工程を挙げており、リファクタリングの提案は挙げていない）

ドメインイベント

用語

受け入れ条件

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）

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

根拠にした MVV の項目

• Mission: 開発者が価値を利用者へ届けるまでの時間と費用を減らす（設計のやり直しの手戻りを減らす）
• Value 2: 人が判断できる量に収める（実装を 2 つの PR に分ける）
• Value 3: やめる・縮めるを既定にする（調べる量の上限と省ける条件。レビューの担当の調べにも上限を置く）
• Value 4: 外の利用で測って決める（carul での実際の手戻りが起点）
• Value 6: どのプロジェクトでも使える形を保つ（領域ごとの一覧を持たない・MVV に依らず働く・担当のランタイムに依らない観点の文）
• Value 7: 根本原因の場所で直す（プロジェクトの MVV で補うのでなく design とレビューの工程に置く）

進行

モード: — / 進め方: auto

• 要求と受け入れ条件 — 2026-11-05 00:58
• 作業場所の用意 — 2026-11-05 12:18
• 設計 — 2026-11-05 01:02
• 素材の収集と出典の確定
• ドキュメント再構成 — 2026-11-05 01:11
• ドキュメントレビュー — 2026-11-05 01:10
• 計画 — 2026-11-05 12:18
• 実装 — 2026-11-05 12:18
• 構造改善 — 2026-11-05 15:21
• 実装レビュー — 2026-11-05 16:07
• 完了判定 — 2026-11-05 13:20
• Pull Request — 2026-11-05 13:39
• 確定仕様化 — 2026-11-05 19:13
• 後片付け — 2026-11-05 19:40
• 配布 — 2026-11-05 16:39
• 体裁レビュー
• リリース後テスト — 2026-11-05 19:34
• 振り返り — 2026-11-05 19:34
• 棚卸し — 2026-11-05 19:40

設計の承認ゲート 1 での利用者の指摘（直して出し直す）

（書き手: 利用者の答えをオーガナイザーが写した、日付: 2026-11-05。出し直しの設計はこの節を満たすように直す。満たせない項目は理由を設計に書く。この節は上書きしない）

利用者の判断（2026-11-05）: 直して出し直す。外部の調査の確認を、design の工程だけでなく、レビューの工程（pr-review）と cross-review の工程にも入れる。

• レビューの側の確認: 設計 PR・実装 PR のレビューで、触る領域の標準・主要な製品・既存のライブラリと比べたか（「外部の調査」の節と、決定ごとの「作り方」「比べた候補」）を観点として見る。自前で作るのに比べた候補が無い、出典が無い・古い、といった点を指摘にする
• cross-review の担当（codex・kiro・claude など）への起動指示にも同じ観点を載せる。担当が自分で外部を調べて、より良い標準やライブラリがあれば指摘できるようにする
• design の手順・雛形・design-survey.py の検査はこの設計のまま残す
• 量が増えるので、MVV 版 5 の量の上限に照らして実装の PR を分ける（例: design の手順と検査 / レビューと cross-review の観点）

人の判断待ち（開発ループ lflow2）

• 判定: follow（承認ゲート 1）
• 理由: Mission と Vision、Value 4 に照らして follow とした。NDF の外のプロジェクト carul（feat: 全 Skill の description を新書式へ圧縮する（平均 237 → 150 文字） #102・Add: cross-refactoring — 多ランタイム・リファクタリング収束ループ (#113) #117）で、比べないまま自前で作ると決めた設計をやり直した実例がある。この変更はそれを起点に、設計の承認の前に比べた候補を機械の検査とレビューで確かめる。どのリポジトリでも、設計の工程の中で同じに働く。／Value 2 と Value 3 に照らして follow とした。利用者の指摘どおり、実装を『design の手順と検査』と『レビューと cross-review の観点』の 2 つの PR に分けている。調査には上限（候補 6 件・取得の試み 30 回、レビューの担当は 1 ラウンド 10 回）を置き、当たったら止める。直しは 1 回だけ試み（fix-survey）、残れば止めて人へ戻す。同じ指摘のラウンドを重ねない。／Value 5、Value 6、Value 7 に照らして follow とした。判定の要らない検査はスクリプト（design-survey.py）に任せ、文の意味を読む確認はレビューに任せる。設計文書の探し方は lib/design_docs.py に寄せて共有し、Markdown の読み方は既存の markdown-it-py（lib/md.py）を使う。継続的統合でなく設計のプランと Skill の手順から検査を打つので、ほかのリポジトリでも働く。観点の正本は pr-review の SKILL.md の 1 か所に置き、cross-review はそれを読む。／Value 8 と Value 1 に照らして follow とした。決定 15 件のそれぞれに、理由と採らなかった形を残している。確かめられなかったこと（既存の検査の Tool を探していないこと、Codex で外部を取得できる範囲など）と、リリース後の測定へ回す項目を明記している。上限の値の妥当性など配布の後でしか測れない効果は、判定の対象にしない。／共通原則 C1〜C8 と P1 に照らして、承認が要る操作は無いと判断した。この PR が変えるのは issues/ の要求と設計の文書、docs/ の用語集だけである。.ndf/ の設定、AGENTS.md / CLAUDE.md の運用の節、秘密、認証、利用者のデータ、配布の取得元と版の規則には触れない。後の実装の範囲（design の Skill・検査のスクリプト・sprint_waves.py・pr-review・cross-review）にも当たる操作は無く、codex の起動の引数など取得の権限も変えないと明記している。
• 根拠の項目: Mission, Vision, Value 1, Value 2, Value 3, Value 4, Value 5, Value 6, Value 7, Value 8, C5, C7, P1
• 設計 Pull Request: design: 設計の判断の前に外部の標準・主要な製品・既存のライブラリを調べ、自前で作る決定に比べた候補を残す（#2519） #2523
• 答え: approved
• 答え方: python3 /persistent/ai/.claude/plugins/cache/ai-plugins/ndf/10.27.21/scripts/sprint-state.py loop answer lflow2 2519 --approved|--rejected|--revise --note <指摘ファイル>

振り返り: #2586 (comment)

状況（v10.27.24）

• 受け入れ条件 1〜17 は v10.27.24 のリリース後テスト Release: ndf v10.27.24 #2586 (comment) で合格
• 残りは手動確認 1 件（保留）: NDF の外のプロジェクトで design と cross-review を 1 回ずつ通し、外部の調査の節が出典つきで埋まること・観点の指摘か指摘 0 件の理由が出ることを見る。次に NDF の外のプロジェクト（例: volareinc/carul）で 10.27.24 以降の design と cross-review を通したとき、その設計 PR で確かめる