scope-design

ハンズオン参加者が、限られた時間枠で何をどこまで作るかを決められるように、1問ずつの対話で scope.md に辿り着くまでをガイドする。

目的

• 参加者の「課題の一言」「解決策の一言」を出発点に、実装アプローチを複数案出してから選ばせることで、思いつきの第一案に縛られない設計体験を提供する
• 最終的に、Claude Code に渡してそのまま実装に進める粒度の scope.md を完成させる
• scope.md は一発で完成させるのではなく、対話で繰り返し調整する前提 で進める

前提

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

書き出し先

• 設計ドキュメント（input.md / idea.md / scope.md）は projects/<プロジェクト名>/ 直下に書き出す
• ディレクトリがなければ作成する
• アプリ本体（実装コード一式）は projects/<プロジェクト名>/apps/ 配下に作る。設計ドキュメントと混ざらないようにディレクトリで分離する。複数の実装を試したい場合は apps/<アプリ名>/ のようにサブディレクトリで分けてよい

起動時のふるまい

1. 「プロジェクト名を決めましょう。projects/<名前>/ の配下に書き出していきます」と伝え、プロジェクト名を聞く
2. projects/<名前>/ が存在しなければ作る
3. projects/<名前>/progress.log に start 行を追記する（共通原則 14）。以降、各 Phase でファイルを書き出すたびに write 行を追記する
4. その中の既存ファイル状況を確認する
   • 何もなければ Phase 1 から開始
   • input.md があれば内容を読み上げて「この内容で進めるか、書き直すか」を確認。## 時間枠 が無い古い形式なら質問3だけ追加で聞いて追記する
   • idea.md / scope.md も同様

対話の大原則

共通原則（1問ずつ・先回りしない・逐次書き出し・差分更新・既存ファイルの確認）は conversation-principles.md に従う。このスキル固有の原則：

• 1フェーズ = 1ファイル生成。Phase 1 → input.md、Phase 2 → idea.md、Phase 4 → scope.md。フェーズの完了時に必ず書き出してから次に進む
• scope.md は完成後も何度でも調整する前提。「実装に進みたい」と言われるまで対話で詰め、実装は /build-app に引き継ぐ
• ユーザーが時間配分に不安を示したら、MVP をさらに削る方向に誘導する
• 時間枠は Phase 1 で確認して input.md に記録し、以降の見積もりはすべてその値を基準にする。標準値は workshop-premises.md にあり、このファイル内には固定の時間を置かない
• 時間配分は「分単位の線形タイムライン」にしない。Claude Code 前提なので「一気に生成 → 動かして対話でチューニング」のサイクル単位で組む（詳細は Phase 3・4 を参照）

---

技術選定の制約（重要）

限られた時間で動くものを作り切ることを優先し、プロダクトへの有料 API・サービスの組み込みは避ける ことを前提にする。参加者のプロダクトのコード内で、クレカ登録や課金が必要な外部サービスを呼び出す実装は提案しない。

対象となる NG 例

• LLM API（OpenAI / Anthropic API / Google AI など）
• Google Maps API / 有料の気象・交通API
• SMS・決済・認証系の課金API
• その他、クレカ登録や課金が必要な外部 API・サービス

代わりに勧める方向

• 公的オープンデータ（政府統計ポータル、気象庁・国交省 CSV 等）
• 事前計算済みの静的データ（Claude Code を使って事前に生成・集計した結果をアプリに同梱）
• 完全無料のAPI（キー不要 or 無料登録のみ）— ただし「個人の自己責任」と明記する

Claude Code は別扱い

Claude Code（開発ツール） は全員が使う前提で、制約対象ではない。制約対象は「参加者のプロダクトのコード内から有料APIを呼び出す実装」のみ。

---

技術は原則 Next.js

workshop-premises.md の標準構成では、成果物は Next.js（App Router / TypeScript）の Web アプリ とする。理由：

• ページ追加・データ取得・静的書き出しまで一通り揃っており、短い時間枠でも動かしやすい
• ワークショップ環境に Node.js が用意されていれば環境構築が軽い
• LP（apps/lp/）と同じ Node.js 環境で完結し、成果物が「動くアプリ + LP」で揃う
• 参加者が後で拡張する（API ルート追加・デプロイなど）際にも資産が活きる

例外

• 「ファイル1枚で完結する静的ページ」 で十分な場合（例: 集計済み JSON を Chart.js で表示するだけのダッシュボード）は、素の HTML + CSS + JS を選んでよい。Next.js を入れる手間に見合わないと判断したらシンプル側に倒す
• 前提ファイルの「技術」の行が書き換えられている場合（CLI 等）はそれに従う。ユーザーが明示的に他のフレームワーク（Vite + React / SvelteKit など）を希望した場合も尊重する

---

スキル動作への反映

• Phase 2 で実装アプローチを発散するとき、有料APIに依存しない案を必ず 1 つ以上含める。有料API依存の案を出す場合も、代替案とセットで提示する
• Phase 2 で Web アプリ案を出す場合、技術メモに Next.js 前提 であることを書く（静的1枚で済む案は素のHTMLでよい旨も併記）
• Phase 3 質問8（技術スタック） で有料API系が候補に上がったら、そのまま鵜呑みにせず代替案を提示して確認する
• Phase 3 質問8 で Web アプリの希望が出たら、原則 Next.js（App Router / TypeScript）を提案する。静的1枚で済むケースだけ素のHTMLを推す
• Phase 3 質問7（スコープ外） で、有料APIを使った機能（LLM呼び出しによる自然言語応答など）が自然にスコープ外に入ることを伝える

---

Phase 1: 課題と解決策を聞く（input.md を生成）

質問1

「解きたい課題を一言で教えてください」

• ユーザーの回答をそのまま記録する
• 曖昧でも修正を提案しない。後のフェーズで深めればよい

質問2

「その課題に対する解決策を一言で教えてください」

• 同じくそのまま記録する
• 「Webアプリ」「チャットボット」など具体的な実装形式が混ざっていてもOK。Phase 2 で掘り返す

質問3（時間枠の確認）

workshop-premises.md の「形式」の行を読み、標準構成なら 確認だけ する：

「標準構成は1日完結型です（設計から発表まで今日中に完走します）。この前提で進めてよいですか？ 半日など時間枠が違う場合は、だいたいの時間を教えてください」

• だいたいでOK。分単位の正確さは求めない。「2コマ」「午後いっぱい」のような答えはそのまま記録し、括弧で分数の目安を添える（例: 「2コマ（約180分）」）
• 守るのは「その時間枠で完走する」ことだけ。各ステップの配分は目安であり、参加者に分単位の管理を求めない
• 前提ファイルの「形式」が書き換えられていれば、その値を提示して確認する

書き出し

projects/<name>/input.md に以下のフォーマットで書き出す：

# インプット

## 課題

<質問1の回答>

## 解決策

<質問2の回答>

## 時間枠

<質問3の回答（例: 1日完結 / 半日 / 2コマ（約180分））>

書き出したら Phase 2 に進む旨を伝える。

---

Phase 2: 実装アプローチを発散（idea.md を生成）

Claude の作業

入力をもとに、2〜4個の実装アプローチ案 を考える。

鉄則

• 入力の解決策に含まれる UI／データの切り口（例: チャット、一覧表示）を必ず1案は外す。技術（Next.js）は前提で揃えるので、形式（Web か CLI か）ではなく アプローチ で発散させる
  • 例: 解決策が「チャットで質問できるWebアプリ」→ 「タイムピッカー + グラフの構造化ダッシュボード」「条件を選んで一覧・比較する画面」案も出す
  • 目的: 「解決策のアイデア ≠ 実装アプローチ」という気付きを与える
• input.md の時間枠で作れるかを各案の評価軸に入れる
• 有料API（LLM / 地図 / 決済 等）を使わない案を必ず1つは含める（構造化データ + 事前計算でいけるパターンを示す）。詳細は冒頭「技術選定の制約」を参照
• 有料API依存の案を出す場合は、代替案とセットで 提示し、有料APIの使用コスト・管理責任が生じる点を明記する

各案に書く項目

• どういうものか（一言）
• できること / できないこと
• 実装難易度（時間枠内で作れそうか、何がネックになりそうか）
• 学びどころ（この案を選ぶと何が面白いか・何が身につくか）

書き出し

projects/<name>/idea.md に書き出す。フォーマット例：

# 実装アプローチ案

入力: `input.md`

## 案A: <一言で>

- **何をするか**: ...
- **できる**: ...
- **できない**: ...
- **難易度**: ...
- **学びどころ**: ...

## 案B: <一言で>
...

## 案C: <一言で>
...

質問4

書き出した idea.md の要点を会話でも簡潔に提示しつつ聞く：

「どの案で進めますか？ 混ぜてもOKです」

回答を待って Phase 3 に進む。

---

Phase 3: スコープ絞り込み（対話で1問ずつ）

採用案が決まったら、以下を 1問ずつ 聞いて詰めていく。各回答はメモしておき、Phase 4 で scope.md に反映する。

質問5（MVP）

「MVP として『これだけは絶対作る』機能を3つ挙げるとしたら？」

• ユーザーが迷ったら Claude から候補を示す。ただし決めるのはユーザー
• 4つ以上挙がったら「時間枠に収まりそうか」を一緒に検討する

質問6（ストレッチ）

「時間が余ったらやりたいストレッチ機能はありますか？」

• ゼロでもOK。その場合は「なしでOK」と記録

質問7（スコープ外）

「今回はあえてやらないこと（スコープ外）を宣言しておきますか？」

• 例：LLM使用しない / 認証なし / 永続化しない / 地図表示なし
• 「やらないことを明示する」のは締め切りを守るために効く、と伝える

質問8（技術スタック）

「使う技術に希望はありますか？ 任せてもOKです」

• 任せると言われたら、採用案から素直に推奨を出す（例: CLI なら Python + Click + Rich）
• 希望があればそれを尊重
• ただし有料API（LLM / 地図 / 決済 等）が希望に含まれていたら、そのまま鵜呑みにしない。冒頭「技術選定の制約」に従って代替案（公的オープンデータ / 事前計算 / 無料API）を提示し、本当にその有料APIが必要か再確認する

時間見積もりの確認

Claude Code 前提なので、線形分解ではなく「一気に生成 → 対話でチューニング」のサイクルで組む。

「ここまでの内容で、『Claude Code に scope.md を渡して初期一括生成 → 動かしながら対話で詰める』というサイクルで <input.md の時間枠> に収まりそうか、一緒に見てみましょう」

目安（時間枠を 前半・後半 に二分して組む。休憩やコマの区切りがあればそこで分ける）。配分はあくまで目安 で、守るのは時間枠内に完走することだけ：

• 前半: 初期一括生成（10〜15分） + 動作確認（15分程度） + 対話チューニング（残り時間・1サイクル 10〜20分） → MVP が動く状態
• 後半: MVP 仕上げ（前半の 1/3 程度） + ストレッチを対話サイクルで積む（1つ 15〜25分 × 数本）

時間枠ごとの読み替え例：

時間枠	前半	後半	調整の方向
90分	生成 10分 + 確認 10分 + チューニング 25分	仕上げ 15分 + ストレッチ 1本	MVP を 1〜2 機能に絞る
1日完結（標準構成。実装パートの目安 約180分）	生成 15分 + 確認 15分 + チューニング 60分（3〜4サイクル）	仕上げ 30分 + ストレッチ 60分	標準。MVP 3 機能が目安。検証・LP は実装パートの外側に時間がある
実装だけで半日〜1日	同上	ストレッチを厚く積む	MVP を増やすより、検証・LP などの後工程に時間を回す

MVP が多すぎて対話サイクルが回らなさそうなら MVP を削る方向に誘導する。

---

Phase 4: scope.md を生成

Phase 3 の回答をもとに、以下の 9セクション構成 で projects/<name>/scope.md を書き出す。

scope.md の9セクション

1. 概要 — 課題 / 解決策 / 対象ユーザー / アーキテクチャ を表形式で
2. 入力データ or 入力フォーマット — 外部データ or 入力CSV/JSONの仕様
3. 機能一覧 — MVP と ストレッチ を表で
4. 画面構成 or CLIインターフェース — UIモック or コマンド実行例
5. 技術スタック — レイヤーごとに選定理由も
6. ディレクトリ構成 — ツリー表示。設計ドキュメントは projects/<name>/ 直下、アプリ本体は projects/<name>/apps/ 配下に置く前提で書く
7. 実装ロジック — 主要な処理をステップで（データ加工の方針など）
8. 実装計画 — input.md の時間枠を前半・後半に分け、何をやるか時間配分付きで（コマや休憩の区切りがあればそれに合わせる）
9. スコープ外 — やらないことを明示

書き出し後

書き出したら、ユーザーに以下を伝える：

「projects/<name>/scope.md に書き出しました。確認して、気になる箇所があれば『ここを変えたい』と教えてください。scope.md は何度でも調整できます。実装に進むときは /build-app を呼んでください。アプリ本体は projects/<name>/apps/ 配下に作るので、設計ドキュメントとは混ざりません。あわせて レビュー用のページ（HTML）を作りますか？ 内容に読むときの観点を添えて、ブラウザで読める形にします。ペアフィードバックで相手に見せるのにも使えます」

肯定なら review-page.md に従って projects/<name>/review/scope.html を作る（共通原則 15）。

調整フェーズ

ユーザーが調整を要求したら：

• 該当箇所のみを Edit で差分更新する（ファイル全体の書き直しは避ける）
• 「MVP を削りたい」「技術を変えたい」「ストレッチを足したい」などに応じる
• 関連するセクションに波及する変更（例: 技術変更 → ディレクトリ構成も変わる）は必ず連動して更新する
• review/scope.html があれば、聞かずに作り直す

---

参考: 完成 scope.md のサンプル

以下は実際に同じプロセスで作られた2つのサンプルプロジェクトの scope.md。生成時はこの粒度を目指す。どちらも実装時間 180分（90分 × 2コマ）で作られた記録 で、実装パートの長さは標準構成と同じ。サンプル2（CLI）は標準構成の技術（Next.js）から外れる別形態の参考例なので、着地の粒度と実装計画の組み方だけを参考にする。時間枠が異なる場合は「8. 実装計画」の区切りと配分を読み替える。

サンプル1（Web・公的データ活用）: 通学バス所要時間ダッシュボード

入力の解決策: 「国土交通省のデータを活用して、最寄り駅から大学キャンパスに行くバスがおおよそどれくらいの時間を要するかチャットで質問できるWebアプリを作る」

scope.md で着地したアプローチ: 「CSVから事前計算したJSONを静的サイトが読み込む構成。チャット UI は採用せず、タイムピッカー + グラフ + 表の構造化UIに転換」

# スコープ設計書: 通学バス所要時間ダッシュボード

## 1. 概要

| 項目 | 内容 |
|---|---|
| 課題 | 大学への通学時にバスの遅延が大きく、自宅を出発する時間に対する学校の到着時間の予測が立てづらい |
| 解決策 | 国土交通省の道路交通センサスデータを事前集計し、時間帯別の所要時間を可視化する静的Webダッシュボードを作る |
| 対象ユーザー | 市街地から郊外キャンパスにバス通学する学生 |
| アーキテクチャ | CSVから事前計算したJSONを静的サイトが読み込む構成。バックエンド不要 |

## 2. 使用データ

国土交通省「全国道路・街路交通情勢調査（道路交通センサス）」の福岡県データを使用する。

### データファイル

| ファイル | 内容 | 主な用途 |
|---|---|---|
| kasyo40.csv | 箇所データ（道路区間の属性情報） | 路線名、区間延長（km）、旅行速度（混雑時/非混雑時） |
| zkntrf40.csv | 交通量データ（時間帯別） | 各区間の時間帯別交通量（7時台〜翌6時台） |

## 3. 機能一覧

### MVP（必ず作る）

| # | 機能 | 説明 |
|---|---|---|
| 1 | 時間帯別所要時間グラフ | 横軸=時間帯（7〜22時）、縦軸=推定所要時間の折れ線グラフ |
| 2 | 区間別旅行速度テーブル | 国道202号の博多→糸島区間を一覧表示 |
| 3 | 出発時刻シミュレーター | 到着希望時刻をタイムピッカーで選ぶと、推定所要時間と推奨出発時刻を表示 |

### ストレッチ（時間があれば）

| # | 機能 | 説明 |
|---|---|---|
| 4 | 区間別速度ヒートマップ | 区間 × 時間帯のヒートマップ |
| 5 | 上り/下り切替 | 通学（駅→大学）と帰宅（大学→駅）の切替 |

## 4. 画面構成

1画面構成。3つのセクションを配置。

（タイムピッカー → 所要時間グラフ → 区間テーブル）

## 5. 技術スタック

| レイヤー | 技術 | 選定理由 |
|---|---|---|
| フロントエンド | HTML + CSS + JavaScript | ビルド不要、ワークショップ環境ですぐ動く |
| グラフ描画 | Chart.js（CDN読み込み） | 導入が簡単 |
| データ集計（ビルド時） | Python スクリプト | CSVの読み込み・集計が簡潔。実行は1回のみ |
| 配信 | 静的ファイルのみ | バックエンド不要 |

## 6. ディレクトリ構成

01_bus-arrival-dashboard/ ├── input.md ├── idea.md ├── scope.md └── apps/ ├── scripts/ │ └── build_route_data.py ├── app/ │ ├── index.html │ ├── app.js │ └── data/ │ └── route_hakata_kyudai.json └── data/ ├── kasyo40.csv └── zkntrf40.csv

## 7. データ加工の方針

CSVからの集計はビルド時に1回だけ実行し、結果をJSONとして出力する。

- ステップ1: 対象区間の抽出（国道202号）
- ステップ2: 時間帯別交通量の取得
- ステップ3: 混雑度の算出 `混雑度(h) = その時間帯の交通量 / ピーク時間帯の交通量`
- ステップ4: 推定速度の線形補間 `推定速度(h) = 非混雑時速度 × (1-混雑度) + 混雑時速度 × 混雑度`
- ステップ5: 時間帯別の所要時間算出

## 8. 実装計画（2コマ = 180分）

Claude Code 前提。「一気に生成 → 動かして対話でチューニング」のサイクルで進める。

### 1コマ目（90分）: MVP が動く状態まで
- **初期一括生成（0〜15分）**: scope.md を Claude Code に渡して、CSV 集計スクリプト + 静的 HTML + Chart.js のドラフトを一気に生成
- **動作確認（15〜30分）**: ブラウザで開いて挙動確認。致命的な不具合の修正
- **対話チューニング（30〜90分）**: グラフの見た目、シミュレータのロジック、区間テーブルの粒度などを対話で詰める（1サイクル 10〜20分 × 3〜4本）

**目標**: 1コマ目終了時点で MVP 3機能（グラフ・シミュレータ・区間テーブル）が動く状態

### 2コマ目（90分）: 仕上げ + ストレッチ
- **MVP 仕上げ（0〜30分）**: UI の詰め（コントラスト・レスポンシブ・見出し・空状態）を対話で
- **ストレッチ（30〜90分）**: 対話サイクル単位で順に積む。1つあたり 15〜25分目安

## 9. スコープ外

- リアルタイム交通情報取得
- 地図上での経路表示
- バス時刻表との連携
- LLM/AIエージェント（構造化UIで代替）
- ユーザー認証・データ永続化
- 複数路線の比較

サンプル2（CLI）: 履修登録シミュレータ (jiji)

入力の解決策: 「履修候補をCSVに書き出すと、時間割の衝突・週マップ・単位数サマリをターミナルに表示してくれるコマンドラインツールを作る」

scope.md で着地したアプローチ: 「Python + Click + Rich で、単一CSVを読み込みターミナルに整形出力するシンプルCLI」

# スコープ設計書: 履修登録シミュレータ (jiji)

## 1. 概要

| 項目 | 内容 |
|---|---|
| 課題 | 履修登録のときに複数の候補科目から選ぶのだが、時間割の衝突や単位数の合計を手作業で確認するのが大変 |
| 解決策 | 履修候補をCSVに書き出すと、時間割の衝突・週マップ・単位数サマリをターミナルに表示するCLIツール |
| 対象ユーザー | 履修登録を控えた大学生 |
| アーキテクチャ | 単一のPythonパッケージ。CSVを読み込んでターミナルに整形出力 |

## 2. 入力フォーマット

```csv
id,name,day,period,credits,category,priority
CS101,プログラミング基礎,月,1,2,必修,high
CS201,アルゴリズム,水,3,2,選択必修A,medium
CS202,データベース,水,3,2,選択必修A,medium

カラム	必須	内容
id	✓	科目コード
name	✓	科目名
day	✓	曜日
period	✓	時限
credits	✓	単位数
category	✓	区分
priority	—	取りたさ（デフォルト medium）

3. 機能一覧

MVP

#	機能	説明
1	jiji check	衝突検出 + 週マップ + 単位数サマリ
2	衝突検出	同じ(day, period)の重複を警告
3	週マップ描画	Rich Tableで曜日×時限を表示
4	単位数サマリ	category別に集計

ストレッチ

#	機能	説明
5	jiji diff	2プラン比較
6	priority推奨	衝突時の推奨選択

4. CLIインターフェース

$ jiji check courses.csv

[衝突] 水3限
  - CS201 アルゴリズム     (priority: medium)
  - CS202 データベース     (priority: medium)

週間マップ:
     月     火     水     木     金
  1  CS101  ...    —     ...    —
  ...

単位数サマリ:
  必修      : 5 単位
  選択必修A : 2 単位
  合計      : 11 単位

5. 技術スタック

レイヤー	技術	選定理由
言語	Python 3.10+	ワークショップ環境に標準。CSV処理が簡潔
CLIフレームワーク	Click	サブコマンド定義が簡単
ターミナル装飾	Rich	表・色付き出力が綺麗
パッケージ管理	uv	高速

6. ディレクトリ構成

02_rishu_simulator/
├── input.md
├── idea.md
├── scope.md
└── apps/
    ├── pyproject.toml
    ├── src/
    │   └── jiji/
    │       ├── cli.py
    │       ├── loader.py
    │       ├── conflict.py
    │       ├── timetable.py
    │       └── summary.py
    └── samples/
        └── courses.csv

7. 実装ロジック

• ステップ1: CSVの読み込みと正規化（csv.DictReader）
• ステップ2: 衝突検出（(day, period)でグルーピング）
• ステップ3: 週マップ描画（Rich Table）
• ステップ4: 単位数サマリ（categoryで集計）
• ステップ5: 最終整形（衝突→マップ→サマリの順で出力）

8. 実装計画（2コマ = 180分）

Claude Code 前提。「一気に生成 → 動かして対話でチューニング」のサイクルで進める。

1コマ目（90分）: MVP が動く状態まで

• 初期一括生成（0〜15分）: scope.md を Claude Code に渡して、pyproject.toml と src/jiji/ の各モジュールを一気に生成
• 動作確認（15〜30分）: uv run jiji check samples/courses.csv を実行して挙動確認、致命的な不具合の修正
• 対話チューニング（30〜90分）: 衝突検出のロジック、Rich Table の見た目、サマリの粒度などを対話で詰める（1サイクル 10〜20分 × 3〜4本）

目標: 1コマ目終了時点で jiji check が MVP 4機能を含めて動く状態

2コマ目（90分）: 仕上げ + ストレッチ

• MVP 仕上げ（0〜30分）: 色分け・エラーメッセージ・空入力時の挙動を対話で詰める
• ストレッチ（30〜90分）: 対話サイクル単位で順に積む（jiji diff → priority 推奨 など）。1つあたり 15〜25分目安

9. スコープ外

• シラバスからの自動取り込み
• 卒業要件の自動判定
• GUI/Web UI
• LLMによる推薦
• データ永続化
• 前期/後期の同時管理

---

## まとめ：このスキルが生む体験

1. 参加者は「課題+解決策」の一言だけ持ってくれば始められる
2. Claude が実装アプローチを複数案ぶつけるので、**第一案に縛られずに選べる**
3. MVP / ストレッチ / スコープ外 を明文化することで、**時間枠内の見通しが立つ**
4. scope.md は完成後も対話で何度でも調整できる
5. 最終的な scope.md はそのまま Claude Code に渡して実装着手できる粒度になっている