MVPファースト開発 — 必要な機能一式で出し、そこから育てる
§0. 最上位の優先順位(このスキル全体を貫く原則)
- 最優先は「社内でさっと使える、業務に必要な機能が一式そろったアプリ」を最短で出すこと。
- MVP = 機能を削ったハリボテではない。業務がそれだけで回る機能一式と、迷わないUI/UXを初回から盛り込む。削るのは「将来的にあった方がいい改善・拡張」であって、業務に必要な機能ではない。
- 速さは「作らないこと」で稼ぐ: 過剰な堅牢化・使うか分からない拡張・完璧を目指した磨き込みを初回に作り込まない。これらは残課題リスト(§7)に明示して後回しにする。
- 安全性は「最低ライン」(§4)を必ず守って出す。それ以上のセキュリティ強化は残課題として反復で追加する。
- 依頼者は非エンジニアである前提で進める。専門知識を要求する確認・報告をしない(§6)。
- 通常は事前質問ゼロ。依頼文・既存コード・業務資料・データ・ログを最大限調べ、最有力の業務仮説を1つ選び、質問より先に動くたたき台を出す。
§1. 初回リリースの線引き — 「業務に必要」と「将来あるといい」
初回リリース = 対象業務が最初から最後までこのアプリだけで回る状態。 紙やExcelに戻らないと業務が完結しないなら、それはまだ完成ではない。
この §1 が指す「初回リリース」は v1(本来の利用者へ公開する版)である。 app-orchestrator を使う場合、その手前に v0(関係者だけへ公開する版) がある。v0 は最頻業務1本が端から端まで通れば出してよく、全画面の実装完了は v0 の条件ではない。v0 で早く触ってもらい、フィードバックを受けながら §1 の「含めるもの」を埋めて v1 に到達させる。削ってよい範囲が広がるわけではない — 到達する順番が変わるだけである。
初回リリースに含めるもの(削らない)
- 対象業務のフロー全体(入力→計算・処理→確認→出力まで一気通貫)
- 業務上必要な全画面と、迷わないためのUI/UX(§2)
- 間違いに気づける仕組み(入力チェック、異常値の表示、確認画面)
- 実データでの動作確認(サンプルではなく本物の業務データで検証する)
残課題に回すもの(初回では作らず、リストに明記する)
- 「あれば便利」な拡張(別形式のエクスポート、通知、ショートカット、一括操作の亜種)
- 権限ロールの細分化、監査ログ、追加のレートリミット等の堅牢化(§4とlaunch-securityの段階別ゲートで必須の防御は除く)
- パフォーマンス最適化(実測で問題が出てから)
- 対象業務の外にある隣接業務への拡張
判定に迷ったら
「これが無いと、使う人は紙・Excel・口頭連絡に戻るか?」で判定する。戻るなら初回に含める。戻らないなら残課題。迷ったら既存業務フローと利用頻度からエージェントが決め、たたき台へ反映する。
§2. UI/UXの鉄則 — 1画面1目的
過去のプロジェクトで「1つの画面に複数の要素が詰め込まれ、使う人が迷う」問題が実際に起きた。UI/UXはv0(関係者限定公開)から手を抜かず、以下を機械的に適用する。以下は3-Aの範囲で実施できる(最後の項目「詳細な体験設計」だけは 3-B の対象)。
- 1画面 = 1つの質問に答える、または1つの作業を完了する。画面の目的を一文で言えないなら分割する。
- 異なる作業(例: データ入力と分析閲覧)を同じ画面に同居させない。ナビゲーションで分ける。
- 全画面に状態を用意する: 読み込み中 / データが空(初回) / エラー / 正常。空状態には「次に何をすればいいか」を必ず書く。
- 入力は最小に。選択式 > 自由入力。システムが計算・取得できる値を人に入力させない。
- 業務の流れと画面の並びを一致させる(月次業務なら「取込→確認→修正→確定→閲覧」の順にナビを並べる)。
- 詳細な体験設計(6状態・ピークエンド設計)は
app-excellence と ux-design に従う。
§3. 決めること・決めなくていいこと
非エンジニアの依頼者に技術選定を尋ねない。以下の仕分けで自律的に進める。
決めなくていい(既定値に従う。依頼者にも聞かない)
この表がキット全体における技術スタック既定値の単一の正本であり、要件で明示的に上書きされない限りこれに従う。
| 項目 | 既定値 |
|---|
| パッケージマネージャ | pnpm(npm/yarnは使わない。コマンド案内も pnpm run 〜 に統一する。詳細は §8) |
| ランタイム | Cloudflare Workers(Pages ではなく Workers。CLIは wrangler) |
| DB / ファイル / セッション・キャッシュ | D1 / R2 / KV |
| フレームワーク | 画面中心の業務アプリ(既定)は Next.js + OpenNext。API中心で画面が少ないツールは Vite + React + Hono。既存アプリは既存構成に従う(Next.js + OpenNext のアプリに Hono を追加せず、Route Handler を使う) |
| アクセス制御 / 認証 | better-auth-google-gate §0 の単一決定表に従う。社内利用者以外をエッジで遮断するだけなら Cloudflare Access、アプリ内identity・role・session・ユーザー単位データ・WebSocketが必要なら Better Auth + Googleログイン |
| デザイン | 可視UIありなら jp-web-design references/catalog-default-contract.md の既定profile。明示上書きと NON_VISUAL の扱いも同契約 |
| デプロイ先 | 使用する Cloudflare アカウントの workers.dev サブドメイン。Worker 名は業務内容から命名する(既存プロジェクトがあればその慣例に従う) |
| CI/CD | v0 の URL 引渡し後に ci-cd-pipeline §0 で deploy 責任者を1経路だけ選ぶ。D1 を使う案件(既定)は外部 CI/CD(migrate.yml + deploy.yml)、DB を持たない・静的配信だけの案件に限り Workers Builds |
技術を聞かない自動裁定(単一の正本)
- 依頼者は backend / DB / frontend / UI・UX / security / infra を知らない前提とし、技術名・構成・保存方式を質問しない。業務の目的・実物・既存資料・既存コードから推定し、上の既定値で画面から保存先まで接続する。
- 未確定でも、安全で可逆な仮説を1つ選び、最頻業務の代表フローを先に動かす。内部の全層traceと品質フラグは app-excellence
references/03-feature-decomposition.md §2-1 を使い、依頼者には業務語の成果物だけを見せる。技術情報を質問しないだけでなく可視DOMへも出さず、表示文の境界は jp-web-design references/information-design.md §3-1を正本とする。
- デザイン指定の有無を質問しない。DOM/JSX/HTML、描画component、新画面、layout、style/token、利用者interactionを作る・変える場合はcatalog-default対象とし、T2 provenance→T3 adoption→T4 conformanceを
jp-web-design の同契約どおり受け渡す。可視UIへ一切触れない場合だけ NON_VISUAL(理由) を記録する。
- 確認するのは、不可逆な本番データ変更、課金・契約、公開、個人情報の取得目的・所有境界、法的同意、秘密情報の受け渡しなど本人しか決められない境界だけ。成果物と推奨案を先に示し、関連する確認を1回に束ねる。
最初に成果物へ明記する(後から変えるとデータ移行が必要になるもの)
- 何を1件と数えるか(例: 車両×月で1レコードか、伝票1枚で1レコードか)。テーブルの主キー・一意制約に直結する。
- 金額・日付・数量の型と単位(円は整数、日付はISO文字列、など)。
- 誰のデータか(全社共有か、ユーザーごとに分けるか)。
- コード・既存帳票・データの一意性から推定できる場合は自律的に確定する。推定しかできない場合も、安全で可逆な仮説を1つ選び、schemaと画面のたたき台を先に作る。不可逆な本番データ移行の直前だけ、成果物を示して1回確認する。
後で決めてよい(残課題リストへ)
権限ロールの細分化 / 通知・メール / パフォーマンス最適化 / 監査ログ / 隣接業務への拡張
§4. 社内アプリの必要最低限セキュリティライン
「必ず」の4つを守れば公開してよい。(この4項目が INV-9 の正本。INVARIANTS.md 参照) それ以外のセキュリティ強化を理由にリリースを遅らせない(残課題に記録して反復で追加する)。
必ず(v0・v1 いずれでも省略不可)
- 許可した利用者以外を遮断する。方式は
better-auth-google-gate §0 の単一決定表で決める。
- 遮断だけで足りる社内アプリは、v0・v1 とも Cloudflare Access を継続してよい。
- アプリ内で利用者を識別する、role/権限を持つ、sessionを利用する、ユーザー単位でデータを分ける、または WebSocket を使う場合は Better Auth を必須とする。
- 「社内でしか使わない」をURLの秘匿だけで守ったことにしない。
- 秘密情報をコードに書かない。APIキー等は
wrangler secret put。.dev.vars はgitignore済みであること(INV-1)。
- データを消す操作には確認を挟む(確認ダイアログ、または論理削除)。業務データはユーザーの財産。
- 本番DBのスキーマ変更前に
wrangler d1 export でバックアップを取る(INV-7)。
リリース可否の判定はこの4項目 + launch-security の段階別ゲート + その公開段階のゲート、の3つだけ(正本は app-orchestrator 裁定ルール1 = INV-5)。v0 / v1 の CRITICAL・HIGH の扱いと例外条件は launch-security「段階別判定」(INV-3)に従い、ここでは複製しない。速さのためにこの品質を下げない。
残課題でよい(v2以降で追加)
細かい権限ロール / 監査ログ / Better Authの既定を超える防御 / launch-security のうち、悪用経路がなく v1 ゲートを妨げない項目。公開エンドポイントの必要なレート制限など、実際に悪用可能な HIGH はここへ送らない。
§5. 実装・確認・デプロイの鉄則(INV-12)
- **ローカルの最終確認は
pnpm run preview(Workersランタイム、http://localhost:8787)で行う**。`pnpm dev`(localhost:3000)はコーディング中の高速確認専用。Node.jsとWorkersのランタイム差で「devでは動くのに本番で壊れる」が実際に起きるため、依頼者に見せる確認・デプロイ前確認は必ずpreviewで行う。
- D1マイグレーションは ローカル(
--local)で適用・動作確認 → リモート(--remote) の順。リモート適用はデプロイの直前に行う。
- デプロイ前に
pnpm run cf:dry-run(または wrangler deploy --dry-run)でビルドが通ることを確認する。
- デプロイ後は必ず本番URLを実際に開いて業務フローを1周する。「デプロイ成功」のログは動作確認ではない。
- テストは計算ロジック・パーサー・集計など「壊れると気づきにくい所」に必ず書く。UIの網羅テストは残課題でよい。テストをいつ書くかは §9(たたき台→確認→固定化)に従う。
- 外部から入る値(フォーム・CSV・URLパラメータ)は境界で zod 等によりバリデーションしてから使う(型と範囲のチェック。エラーは日本語で画面に返す)。
- デプロイ前に
pnpm audit --prod を1回実行する。v0 は CRITICAL を解消し、v1 は high/critical の到達可能性と悪用可能性を確認して、悪用可能な HIGH も解消する。
- 実データ(本物のCSV・Excel)での取込テストをv0 の公開前に必ず行う。サンプルデータだけで「動いた」と判断しない。
- 版管理は app-orchestrator の「準備」「公開」「追加開発モード」の git 手順に従う(main にマージした版だけをデプロイ。デプロイ後にタグ)。
§6. 非エンジニアの依頼者との進め方
- 専門用語を訳して話す: デプロイ→「インターネットに公開」、DB→「データの保管場所」、マイグレーション→「保管場所の作り変え」、認証→「ログイン」、API→「画面と保管場所の間の連絡係」。
- 依頼者へ尋ねるのは業務の目的・実物との差分だけ。技術選択と全層の接続は §3「技術を聞かない自動裁定」で決める。
- 質問より成果物: 完成度の高いたたき台、preview、入力済み仕様カードを先に見せる。空欄の質問票やA/B比較を渡さない。
- 内部で候補を比較し、推奨案を1つに確定して実装する。依頼者には抽象的な選択ではなく、成果物への差分だけを尋ねる。
- 技術的判断を依頼者に委ねない。業務事実もコード・帳票・データから先に推定する。秘密、法的同意、課金、公開、破壊操作など本人しか決められない境界だけを1回に束ねて確認する。
- 進捗報告は「URL + 試してほしい操作 + 今できないこと(残課題)」の3点セット。コードやログを貼らない。
- エラー報告のお願いは「画面をそのままスクリーンショットで送ってください」。再現手順の聞き取りを依頼者に強いない。
§7. 残課題リストの管理と育て方
残課題は「やらないこと」ではなく「順番を後にしたこと」。以下のルールで管理する。
docs/product/backlog.md に1件1行で記録する。書式: - [分類: 機能/UX/セキュリティ/性能] 内容 — 後回しにした理由。v0・v1 いずれの公開報告にも必ずこのリストを添える。- 依頼者が v0(または初回リリース) を触った後、最頻業務1本の最小3イベント(開始 / 完了 / 失敗理由コード)・不完了フロー・影響度からエージェントが次の最有力1件を実装候補として確定する。イベントに PII・Secret・自由入力本文を入れず、この3種のために分析基盤を新設しない。依頼者は完成物を見て差分を返せる。
- 追加開発は1機能ずつ縦切りで実装し、既存フローを壊していないことをpreviewで確認してからデプロイする。
- 既存データがあるDBへのスキーマ変更は、必ず新規マイグレーションファイルで行う(適用済みマイグレーションを書き換えない)。
- 「作ったが使われていない機能」に気づいたら削除を提案する。機能を減らす提案は成果である。
§8. Windows / Mac 両対応の注意
開発者・依頼者のどちらにもWindowsとMacが混在する前提で作る。
- 案内するコマンドは
pnpm run 〜 のscripts経由に統一する(生のシェルコマンド・パイプ・環境変数指定をチャットで案内しない)。OS差はpackage.jsonのscriptsに閉じ込める。
- scripts内でもOS依存の書き方を避ける: パス区切りは
/、rm -rfや環境変数の直接指定を使わずNode/ツール標準機能を使う。秘密情報は .dev.vars / wrangler secret で渡す。
- リポジトリに
.gitattributes(* text=auto eol=lf)を置き、改行コード差分を防ぐ。
- 環境構築はキット付属の
setup-env-mac.command / setup-env-windows.bat(Node.js + pnpm導入)を案内する。
§9. たたき台 → 確認 → 固定化(TDDの弱点を補う開発方式)
前提: Evidence → Decide → Draft → Validate → Diffで、最初のやり取りから動くたたき台を一気に作り、依頼者が触ってから仕様を固める。仕様が流動的な段階のフルTDDは、間違った仕様を固定化するため採用しない。
- たたき台(初回): テストより先に、軽量仕様メモ(画面一覧・データの数え方・業務フローを各1行)を標準の
docs/product/T2-experience-spec.md(プロジェクトに同じ責務の正本が既にある場合はファイルを増やさずその正本)に書き、それを合意点として一気に実装する。同じ正本に、最頻業務1本の学習用イベントを 開始 / 完了 / 失敗理由コード の3種だけ追加する(PII・Secret・自由文なし)。例外として計算・集計・パーサーだけは最初からテストを書く(業務ルールとして仕様が確定しているため)。
- 確認: 依頼者は preview を触り、違う箇所だけを差分として返す。変更指摘がない挙動を初稿の正式仕様とし、T2(または上記の同等正本)を実物に合わせる。
- 固定化(ブラッシュアップ開始時): OKが出た主要フローを回帰テスト(その画面・APIの入出力を固定する特性テスト)として書き、以後の追加開発で壊れたら気づけるようにする。テストは「これから作るもの」ではなく「守りたいと確認できたもの」に書く。
- テストが変更の障害になったら、仕様変更としてテストを書き換える(テストに合わせて仕様を歪めない)。
- カバレッジ目標は設けない(app-orchestrator 裁定ルール4)。testing-excellence の TDD サイクルとカバレッジ目標は、同スキル §0「適用段階」のとおり固定化段階から適用する。