NDF Factory: 画面で行える操作を API と MCP からも同じく行える（機能から起こした配列の入出力・委任の認証・追記だけの操作の記録） #2384

親: #2168（Neural Development Factory を Web UI で操作できるサービスにする）。方針: マイルストーン「25 Neural Development Factory」のスプリント MVV の Value 2（画面先行）・Value 4（AI からも人と同じく使える）。

具体例

利用者が、自分の手元の Claude Code から「Factory で #2172 のスプリントを始めて、承認待ちになったら教えて」と頼む。今の Factory には MCP（Model Context Protocol）の受け口が無く、API は画面の都合で 1 件ずつ受け渡す形が混ざっている。この課題の後は、エージェントが利用者の委任で MCP からスプリントを始め、一覧を読み、承認の依頼を読める。ただし承認の確定は人だけが行う。だれの委任で、どのエージェントが、いつ何をしたかは、追記だけの記録に残る。

依頼（原文）

| AI からも人と同じく使える | 画面で行えるすべての操作を API と MCP からも行える。画面も同じ API を通る。委任を明示する認証・人と同じ認可・追記だけの操作の記録を持つ。承認ゲートとレッドラインの承認は人だけが行う |

| 画面先行 | UX の土台（画面の地図・部品・端末・オフラインの見せ方・国際化）→ 機能の画面をダミーデータで作り切る → API の中身をつなぐ、の順で作る。API の入出力は画面の 1 枚に合わせず機能から起こし、常に配列で受け渡す |

（書き手: 利用者、日付: 2026-11-02。#2168 の「方針（利用者の決定）」の表の 2 行。表は起票者が書き起こしたもので、利用者の決定として承認された行である）

画面で行えるすべての操作を API と MCP からも行えるようにする。画面も同じ API を通して動かし、画面にしか無い操作も、API や MCP にしか無い抜け道も作らない。ただし、承認ゲートの承認と、共通原則の C1〜C8・プロジェクト MVV の P に当たる操作の承認は人だけが行う。API と MCP からは承認の依頼と材料を読めるが、承認を確定できない（AI のエージェントの委任でも同じ）。API と MCP を使う者は、だれの委任で、どのエージェント・クライアントが動くかを確かめ、認可は人の操作と同じく掛ける。読み取りを含むすべての操作を、だれが・いつ・どの経路で・何を行ったかの追記だけの記録に残す。秘密と個人情報の値は記録に書かない。

（書き手: 利用者の承認を受けたスプリント MVV の Value 4、日付: 2026-11-02。文面は起票者が利用者の方針から起こし、利用者がスプリント MVV として承認した）

課題の題と、この後の「何をするか」の表・受け入れ条件の案（起票時の本文）は起票者が書いた。原文に無い条件は「起票者の推定」に分けた。

起票者の推定

題・本文のうち、利用者の指示の原文に無く起票者が推して足した条件。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。

目的

• 人が任せた AI のエージェントや連携するシステムが、画面と同じ操作を、画面と同じ認可と記録のもとで行える状態にする
• API の入出力を画面の 1 枚から切り離し、機能（エンティティと操作）単位の配列の形へそろえる。画面・API・MCP が同じユースケースを通る
• 承認ゲートの承認と、人の承認が要る操作の確定を、委任の経路から行えないことを仕組みで保証する
• だれの委任で、どのエージェントが、いつ何をしたかを後から確かめられる記録を残す

前提

• 前提 1: 「画面で行える操作」は、画面の API クライアント（factory/web/src/api.ts の Api）が呼ぶ操作の全体と、承認と通知（NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173）が足す Web からの承認の操作を指す。2026-11-04 の時点で Api は 31 の操作を持つ（request( の呼び出し 31 件）
• 前提 2: 配列の規則と MCP のツールの対象は、利用者（人か、人の委任を受けたエージェント）が呼ぶ操作である。ランナー向けの経路（/run-jobs/*・/ingest/events・/ingest/api/events）と GitHub の Webhook（/ingest/github）は対象に含めない（S7）
• 前提 3: 1 回の要求で受け渡す配列の要素は 100 個までとする。値は設計で実測を見て変えてよいが、上限を超えた要求は処理せずに 400 と上限値を返す、という振る舞いは変えない
• 前提 4: 委任の資格情報の期限は 1 時間以内とする。範囲は「読み取りだけ」と「読み書き」の少なくとも 2 つを選べる。値と範囲の分け方は設計で決める
• 前提 5: GitHub App の導入とリポジトリへの認可は、人がブラウザで GitHub の画面を操作する流れである。MCP からは導入と認可の URL を返すところまでを行い、GitHub の画面の操作は人が行う
• 前提 6: 委任の資格情報の発行と取り消しは、人が画面で行う。委任の資格情報で委任の資格情報を発行できない
• 前提 7: 既存の契約（factory/contracts/openapi/ の 5 ファイル）の経路を配列の形へ変える。画面と API は同じリポジトリで同時に変わり、外部の利用者はまだいないため、旧い形との互換の経路は持たない
• 前提 8: 操作の記録を置く表の定義は、インフラ（private リポジトリ）が作る。このリポジトリは保存の契約（interface）と、メモリの実装・本物の実装を持つ

対象範囲

含む:

• 契約（factory/contracts/openapi/）の利用者向けの操作を、機能（エンティティと操作）単位の配列の入出力へ起こし直すこと
• 画面の API クライアントと、ダミーの API クライアントを新しい契約の形へ合わせること
• MCP のサーバー（API と同じユースケースを呼ぶ）と、契約の操作と MCP のツールの対応表
• 委任の資格情報の発行・検証・取り消しと、それを発行・取り消す画面
• 人だけが確定できる操作の印と、その印のある操作を委任の資格情報から断る共通の処理
• 操作の記録（追記だけ）の保存の契約・実装と、すべての利用者向けの操作からの書き込み
• 画面の操作・契約・MCP の対応と、単一のレコードの受け渡しが無いことを確かめる検査

含まない:

• ランナー向けの経路と GitHub の Webhook の形（前提 2）
• Web からの承認の操作そのもの（NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173 が作る）。この課題は、その操作に人だけが確定できる印が付き、委任の資格情報から断られる仕組みを用意する
• 操作の記録を読む画面と、記録の検索の機能
• 操作の記録の保存期間と、国ごとの法令（GDPR など）に応じた削除の手続き（未決 2）
• 外部の利用者向けの公開の手続き（MCP のサーバーの一覧への掲載など）
• インフラの定義（表・Lambda・API Gateway）

ドメインイベント

E8 の「追記に失敗したとき操作も失敗にするか」は、記録の欠けを許すかと可用性の取り合いである。未決 1 に置いた。

用語

受け入れ条件

対応と形:

• 1. 画面の API クライアントが呼ぶ操作がすべて契約（factory/contracts/openapi/）の operationId に対応することを、検査（npm run check の一部）が確かめる。対応しない操作が 1 つでもあると検査が落ちる
• 2. 契約の利用者向けの操作がすべて MCP のツールに対応し、MCP のツールがすべて契約の操作に対応することを、検査が確かめる。片方にしか無い操作かツールが 1 つでもあると検査が落ちる
• 3. MCP のツールは、API の経路と同じユースケースの関数を呼ぶ。MCP のツールから、契約に無い保存の操作を呼べないことをテストで確かめる
• 4. 契約の利用者向けの操作で、要求の本文か応答の本文が配列でない操作が無いことを、検査が確かめる（1 件の取得・作成・更新・削除も要素 1 個の配列で受け渡す）
• 5. 経路の変数で単一のレコードを指す取得（/sprint-runs/{sprintRunId} の形）が、利用者向けの操作の契約に無いことを、検査が確かめる

配列の受け渡し:

• 6. 101 個の要素を送ると、どの要素も処理されずに 400 が返り、応答に上限の値 100 が入る
• 7. 3 個の要素のうち 1 個だけに認可が無いとき、応答は入力と同じ順に 3 個の結果を返し、認可の無い 1 個だけに理由（forbidden）が付き、残り 2 個は処理される
• 8. 0 個の要素を送ると、何も処理されずに 400 が返る
• 9. 作成の要素に同じ冪等の鍵を付けて 2 回送ると、レコードは 1 件だけでき、2 回目の応答は 1 回目と同じ識別子を返す

委任の認証:

• 10. 人のログインの token で呼んだ操作と、同じ人が発行した委任の資格情報で呼んだ同じ操作は、同じ認可の判定になる（人に許された操作は委任でも許され、人に断られる操作は委任でも断られる）
• 11. 期限を過ぎた委任の資格情報で呼ぶと 401 になり、操作は行われない
• 12. 取り消した委任の資格情報で、取り消しの後に呼んだ最初の要求が 401 になる
• 13. 「読み取りだけ」の範囲の委任の資格情報で作成・更新・削除の操作を呼ぶと 403 になり、操作は行われない
• 14. 委任の資格情報で委任の資格情報の発行を呼ぶと 403 になる（前提 6）
• 15. 認可は要素ごとに掛かる。他人のアカウントの要素を混ぜた配列で、他人の要素だけが断られ、応答に他人のデータが含まれない

人だけが確定できる操作:

• 16. 契約で、人だけが確定できる操作に印が付いている。ループの判断待ちへの答え（answerLoopPending）には印がある
• 17. 印のある操作を委任の資格情報で呼ぶと、範囲が「読み書き」でも 403 になり、答えも状態も保存されない。印のある操作をすべて委任の資格情報で呼ぶテストがある（S6 の操作を含む）
• 18. 委任の資格情報で、承認の依頼とその材料（スプリントの詳細・承認待ちの一覧）は読める

操作の記録:

• 19. 利用者向けの操作 1 回ごとに、操作の記録が 1 件増える。記録は、操作した利用者の ID・委任の資格情報の識別子（人の直の操作では空）・日時（UTC）・呼び出し元の種類（画面・API・MCP）・operationId・対象の ID の配列・結果（成功・一部失敗・断った理由）を持つ
• 20. 読み取りの操作と、401・403・400 で断った操作も記録に残る
• 21. 操作の記録の保存の契約に、書き換えと削除の関数が無い。テストが契約の関数の一覧を確かめる
• 22. モデルの認証情報（API キー・ロールの ARN）・ログインの token・委任の資格情報の値・GitHub の token を含む要求を送っても、記録にそれらの値が入らないことをテストで確かめる
• 23. 記録に、メールアドレス・氏名・チームの名前・課題の題と本文が入らない

退行しないこと:

• 24. 契約の形を変えた後も、画面の既存の画面テスト（factory/web の Vitest と Playwright）が通る
• 25. ランナー向けの経路（/run-jobs/*・/ingest/*）の入出力が変わらない（前提 2）
• 26. 委任の資格情報を使わない人の操作で、今と同じく 401（token の検証の失敗）と 403（アカウントの解決の失敗）が返る
  前提の確認: factory/api/src/auth/verify.test.ts と factory/api/src/handlers/api.test.ts が今の 401・403 を確かめている（実装の前に npm run check で通ることを確かめる）

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

関連

• 前提にする契約: docs/specifications/ndf-factory-accounts-and-plans.md（認証）・docs/specifications/ndf-factory-contracts-and-progress.md（契約）
• NDF Factory: UX の土台（画面の地図・部品・端末・オフラインの見せ方・国際化・ダミーデータの API クライアント）を機能の画面より先に作る #2382（UX の土台）のダミーの API クライアントは、この契約の形へ合わせる
• NDF Factory: 承認ゲートの通知（Slack を含む）と Web からの承認 #2173（承認ゲートの通知と Web からの承認）が足す承認の操作は、人だけが確定できる操作の印を持つ

進行

モード: — / 進め方: auto

• 要求と受け入れ条件 — 2026-11-04 15:29
• 作業場所の用意 — 2026-11-04 22:15
• 設計 — 2026-11-04 15:34
• 素材の収集と出典の確定
• ドキュメント再構成 — 2026-11-04 15:57
• ドキュメントレビュー
• 計画 — 2026-11-04 22:15
• 実装 — 2026-11-04 22:15
• 構造改善 — 2026-11-05 00:25
• 実装レビュー — 2026-11-05 00:50
• 完了判定 — 2026-11-04 22:47
• Pull Request — 2026-11-04 23:06
• 確定仕様化 — 2026-11-05 03:28
• 後片付け — 2026-11-05 03:53
• 配布 — 2026-11-05 01:34
• 体裁レビュー
• リリース後テスト — 2026-11-05 03:48
• 振り返り — 2026-11-05 03:48
• 棚卸し — 2026-11-05 03:54

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

• 判定: unknown（承認ゲート 1）
• 理由: 判定を読めない
• 根拠の項目: —
• 設計 Pull Request: NDF Factory: 画面で行える操作を、委任を受けたエージェントが API と MCP から同じ認可と記録のもとで行える（#2384） #2498
• 答え: approved
• 答え方: python3 /persistent/ai/.claude/plugins/cache/ai-plugins/ndf/10.27.16/scripts/sprint-state.py loop answer lfactory3 2384 --approved|--rejected|--revise --note <指摘ファイル>

振り返り: #2532 (comment)