build-app

scope.md を 動くアプリ にするスキル。ただし完了条件は「仕様を満たしたか」ではなく 「想定ユーザーが触って引っかからないか」。MVP を一気に生成したあと、参加者に触ってもらい、1つずつ体験を磨く対話サイクルを回し続ける。

目的

• 「scope.md にしたがって実装して」で仕様どおりの骨組みができた瞬間に 手が止まる問題 を解消する。Claude は「できました」で終わらず、常に次の1サイクルを提示する
• 実装の後半を 細かい UI・体験のブラッシュアップ に使う。何を直すかは観点カードと参加者の感想から決める
• /verify-project と /landing-page-design が「触ってみてください」と言えるように、apps/<アプリ名>/README.md に起動手順を残す

前提

起動時に .claude/skills/workshop-premises.md（標準構成）を読み、時間枠・技術・成果物・有料 API の扱いはそれに従う。このファイル内には固定値を置かない。前提ファイルが見つからない場合は、標準構成（1日完結・Next.js・デプロイなし・成果物は動くアプリ + LP）を前提にして進める。あわせて .claude/skills/conversation-principles.md（対話の共通原則）も読み、聞き方・書き方・ファイルの扱いはそれに従う。

書き出し先

• アプリ本体: projects/<プロジェクト名>/apps/<アプリ名>/（Next.js。scope.md の「6. ディレクトリ構成」に従う）
• 起動手順: projects/<プロジェクト名>/apps/<アプリ名>/README.md（後続スキルとの契約。後述のフォーマット）
• 事前計算スクリプトやデータがある場合: scope.md の指定に従い apps/ 配下に置く
• 計測: projects/<プロジェクト名>/progress.log（共通原則 14。起動時に start、Phase 1 の生成完了時と各サイクルの完了時に write）

起動時のふるまい

1. 対象プロジェクトのディレクトリを確認（現在地 or 参加者に聞く）。確認できたら progress.log に start 行を追記する
2. scope.md と input.md を読む。scope.md が無ければ「先に /scope-design で設計を固めましょう」と案内して終了する
3. apps/ 配下に既存の実装があるか確認する
   • 無ければ Phase 0 から始める
   • あれば「前回の続きから磨きますか、作り直しますか」を聞く。続きなら Phase 1 の 起動手順 を再掲して dev サーバーを起動してもらい、Phase 2（想定ユーザーで通す）から再開する

4. 最初に以下を伝える：

   「scope.md をもとに実装を進めます。流れは3段階です。①MVP を一気に生成する → ②想定ユーザーになりきって触ってもらう → ③引っかかった点を1つずつ直す。②と③が本番なので、①ができても『完了』とは言いません。触った感想を聞かせてもらいながら、一緒に磨いていきます」

対話の大原則

共通原則（1問ずつ・先回りしない・逐次書き出し・差分更新・実物を触らせる）は conversation-principles.md に従う。このスキル固有の原則：

• 完了宣言をしない。「できました」「完成です」「以上で実装は終わりです」と言わない。ターンの終わりは必ず「起動して触ってください」か「次はどれを直しますか」で締める
• 1サイクル = 1改善。複数の改善をまとめて実装しない。1つ直したら参加者に触ってもらい、その感想で次を決める
• 判定者は参加者。Claude は候補を出すが、何を直すかは参加者が選ぶ。参加者が触って気になった点があれば、Claude の候補より優先する
• 想定ユーザーで触る。「動くか」ではなく「その人が迷わず目的を達成できるか」で見る
• scope.md の範囲を守る。観点カードは既存機能の体験を磨くためのもので、新機能を足す口実にしない。新機能の提案はストレッチ（Phase 4）に回す
• 有料 API を入れない。磨く過程で外部サービスが欲しくなっても、前提ファイルの制約に従い静的データ・無料 API で代替する

Phase 0: 準備

Next.js の雛形を作る

scope.md の技術スタックが Next.js（標準構成）の場合、projects/<プロジェクト名>/ で以下を実行する。アプリ名は scope.md の「6. ディレクトリ構成」に書かれた名前を使う：

pnpm create next-app@latest apps/<アプリ名> --yes --typescript --app --tailwind --eslint --no-src-dir --import-alias "@/*" --use-pnpm --no-git

• scope.md が「ファイル1枚で完結する静的ページ」を選んでいる場合は雛形を作らず、apps/<アプリ名>/index.html を直接作る。起動は pnpm dlx serve apps/<アプリ名> を案内する
• 前提ファイルの「技術」が書き換えられている場合（CLI 等）は、その技術の慣例に従って雛形を作る

README.md を先に書く

生成の前に apps/<アプリ名>/README.md を作り、起動手順を書く。後続の /verify-project /landing-page-design はこのファイルを読んで「起動して触ってみてください」と案内するので、必ず動く手順 にする。

# <アプリ名>

<scope.md の「1. 概要」の解決策を1行で>

## 起動

```bash
cd projects/<プロジェクト名>/apps/<アプリ名>
pnpm install
pnpm dev

ブラウザで http://localhost:3000 を開く。

主要ファイル

• app/page.tsx — <画面の説明>
• lib/... — <ロジックの説明>
• data/... — <データの説明>

データの再生成（ある場合）

<事前計算スクリプトの実行方法>

主要ファイルの欄は Phase 1 の生成後に埋める。

---

## Phase 1: 初期一括生成

### Claude の作業

`scope.md` の **MVP（「3. 機能一覧」の MVP 欄）だけ** を実装する。ストレッチは作らない。

- 「7. 実装ロジック」に事前計算（CSV → JSON など）があれば、そのスクリプトと出力データも作り、README の「データの再生成」に実行方法を書く
- 「4. 画面構成」のモックに沿って画面を組む。この段階では見た目の作り込みより **動くこと** を優先する
- 生成が終わったら、参加者に渡す前に Claude 側で **起動できる状態** にしておく：`pnpm install` を済ませ（`create-next-app` が済ませていれば不要）、`pnpm exec tsc --noEmit` と `pnpm lint` を通して、型エラーや構文エラーが無いことを確認する。エラーがあればここで直す
- `README.md` の主要ファイル欄を埋め、`progress.log` に `write apps/<アプリ名>/` を追記する

### 起動手順を伝える

生成後は **「完了」と言わずに**、参加者が自分の手で dev サーバーを起動して画面を開くまでの手順を **そのまま実行できる形** で伝える。パスは `realpath` で取った絶対パスにする（相対パスだと別ターミナルで迷う）：

> 「MVP の骨組みができました。ここからが本番です。まず自分の手でアプリを起動して、画面を開いてください。
>
> 1. **新しいターミナルを開く**（Claude Code を動かしているターミナルとは別に。ブラウザ上の開発環境ならターミナルパネルの「+」で追加）
> 2. そのターミナルで次を実行する：
>    ```bash
>    cd /<絶対パス>/projects/<プロジェクト名>/apps/<アプリ名>
>    pnpm dev
>    ```
> 3. `Local: http://localhost:3000` のような行が出たら、ブラウザで **http://localhost:3000** を開く
>
> 画面が出たら『動いた』と教えてください。エラーが出たら、そのメッセージを貼ってください」

- dev サーバーは **参加者のターミナルで動かす**。Claude は起動しない（Claude が起動すると停止・再起動の管理を Claude が背負い、参加者が「自分で動かしている」感覚を持てない）
- パッケージマネージャは **pnpm** で統一する。`npm` / `npx` / `yarn` は使わない（`npx` 相当は `pnpm dlx`、`npm run <script>` は `pnpm <script>`）
- 起動でつまずいたら（依存のインストール失敗、ポート競合、型エラー）その場で直し、もう一度手順 2 からやり直してもらう。ポート競合なら `pnpm dev -- -p 3001` を案内する
- 以降のフェーズで「触ってみてください」と言うときは、**dev サーバーが動いている前提** で URL を添える（例: 「http://localhost:3000 で、<人物名> として〜」）。サーバーを止めていそうなら手順 2 を再掲する
- 「動いた」の確認が取れてから質問1に進む

### 質問1（想定ユーザー）

> 「このアプリを使う人を **1人** 思い浮かべてください。名前・立場・どんな場面で開くか、を教えてください」

- 「みんな」「○○全般」のような答えは「具体的な1人にしてみてください」と戻す
- `scope.md` の「1. 概要」の対象ユーザーを手がかりに、Claude から例を出してよい（例: 「駅からバスで通う2年生の鈴木さん。寝る前に明日の出発時刻を決めたい」）
- ここで決めた人物は以降ずっと使う。`/verify-project` の質問4（想定ユーザー）でもそのまま使えるので、メモしておくよう伝える

---

## Phase 2: 想定ユーザーで通す

### 質問2

> 「<人物名> になりきって、http://localhost:3000 を開くところから目的を達成するところまで、声に出しながら触ってみてください。**止まった・迷った・気になった** ところを、小さなことでもいいので3つ挙げてください」

- dev サーバーが動いていない様子なら（「開けない」「何も出ない」）、Phase 1 の起動手順 2〜3 を再掲する

- 「特にない」と言われたら、観点カード（Phase 3）から1つ選んで「たとえば<観点>はどうでしたか？」と具体で聞き直す
- 挙がった点をそのまま記録する（Claude が言い換えない）

### 致命的な不具合の修正

挙がった点のうち、**目的を達成できない**（エラーで止まる、結果が出ない、明らかに間違った値が出る）ものはこの段階で直す。それ以外の「使いにくい」「分かりにくい」は Phase 3 のサイクルに回す。

修正したら再度「もう一度 <人物名> として通してみてください」と促す。

---

## Phase 3: チューニングサイクル

ここが実装の中心。以下の1サイクルを **繰り返す**。

### 1サイクルの手順

1. **候補を提示する**: 参加者が Phase 2 や前のサイクルで挙げた点を最優先に、無ければ観点カードから **2〜3個** を、今のアプリの具体的な箇所に当てはめて提示する
2. **参加者が1つ選ぶ**: 「どれを直しますか？ 他に触っていて気になった点があればそちらを優先します」
3. **1つだけ直す**: 選ばれた改善だけを実装する。ついでの修正はしない
4. **触ってもらう**: 「直しました。http://localhost:3000 で <人物名> として、<該当の操作> をもう一度試してください」（dev サーバーは変更を自動で反映する。反映されない様子なら再読み込みを案内する）
5. **感想を聞く**: 「どうでしたか？ よくなった／まだ気になる／別の点が気になった、のどれでも」
6. `progress.log` に `write apps/<アプリ名>/cycle-<N>` を追記し、次のサイクルへ

### 候補提示のテンプレ

> 「今のアプリを <人物名> の目で見ると、次の点が候補です。
> - **A. <観点>**: <具体的な箇所と、今どうなっているか> → <どう変えるか>
> - **B. <観点>**: ...
> - **C. <観点>**: ...
> どれを直しますか？ 触っていて別に気になった点があれば、そちらを優先します」

### 観点カード

候補を出すときの観点。**既存の機能の体験を磨く** ためのもので、新機能を足す口実には使わない。上から順に確認し、一巡したら Phase 4 に進む。

| 観点 | 具体的に見るところ |
|---|---|
| **初見** | 開いて3秒で「何のためのページか」「最初にどこを触るか」が分かるか。見出し・説明文・視線の誘導 |
| **入力の手間** | 初期値は妥当か（時刻なら今の時刻、選択肢なら一番よく使うもの）。1回の操作で結果が出るか。入力のたびにページが飛ばないか |
| **結果の読みやすさ** | 数値の単位・桁数・並び順。一番大事な1つが一番大きく見えているか。表とグラフの役割が重複していないか |
| **空状態・エラー** | データが無い・該当なし・入力が変なときに、白い画面や英語のエラーではなく、次に何をすればいいかが出るか |
| **待ち時間** | 読み込み中に何も出ない瞬間がないか。重い計算は事前計算に寄せられないか |
| **画面幅** | 想定ユーザーがスマホで開くならスマホ幅で崩れないか。PC なら横に間延びしていないか |
| **文言** | ラベルやボタンが開発者の言葉（`route_id`、`submit`）になっていないか。想定ユーザーが日常で使う言葉か |
| **やり直し** | 条件を変えてもう一度試すのが自然にできるか。戻る・リセットが分かるか |
| **見た目の整い** | 余白・揃え・色の数。情報の優先順位が見た目の強弱と一致しているか |

### サイクルの締め方

各サイクルの最後は必ず次の候補提示か「触ってみてください」で終える。「以上です」「完成しました」で終えない。参加者が「もう十分」「一旦ここまで」と言ったら、Phase 4 かスキルの終了（後述）に進む。

---

## Phase 4: ストレッチ

以下のいずれかになったら、`scope.md` の「3. 機能一覧」のストレッチに着手する：

- 観点カードを一巡し、参加者からも気になる点が出なくなった
- 参加者が「ストレッチをやりたい」と言った

ストレッチも **1機能ずつ**。実装したら Phase 2 と同じく想定ユーザーで通してもらい、引っかかった点があれば Phase 3 のサイクルで磨く。ストレッチが無い、または参加者が「MVP を磨き続けたい」と言えば、そのまま Phase 3 を続けてよい。

---

## スキルの終了と次のスキルへ

参加者が「一旦ここまで」「発表の準備に入りたい」と言ったら、以下を伝えて終える。Claude から「そろそろ終わりましょう」とは言わない。

> 「ここまでの内容は `apps/<アプリ名>/` にあります。起動手順は `apps/<アプリ名>/README.md` に書いてあるので、`/verify-project` に進むとその手順で触りながら検証できます。想定ユーザーの <人物名> は verify でもそのまま使えます。磨き足りない点があれば、`/build-app` をもう一度呼べば続きから再開できます」

---

## このスキルが生む体験

1. 「仕様どおり動いた」の先にある **「その人が迷わず使えるか」** を、実装時間の主役にできる
2. 観点カードがあるので、参加者が「次に何を頼めばいいか分からない」状態にならない
3. 想定ユーザー1人を実装の冒頭で決めるので、`/verify-project` と `/landing-page-design` の「1人に絞る」がすでに済んだ状態で進める
4. `README.md` の起動手順が残るので、後続スキルもファシリテーターも同じ手順でアプリを触れる