# Webapp Blueprint

> Webアプリケーションをゼロから作るときの設計書（技術スタック選定・アーキテクチャ・ セキュリティ・プライバシー/計測・品質基準）を対話で作成する。「Webアプリを作りたい」 「技術選定して」「設計書を作って」「0から1で作りたい」「新規サービスを立ち上げたい」 「LPを作りたい」「3Dのサイトを作りたい」「セキュリティ要件を決めて」といった依頼で使用する。 既存プロジェクトへの機能追加・バグ修正・リファクタリングには使わない。

- Skill: `tsaru23/webapp-blueprint` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add tsaru23/webapp-blueprint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tsaru23/webapp-blueprint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tsaru23 (https://skillmd.com/u/tsaru23)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tsaru23/webapp-blueprint

---


# webapp-blueprint

Webアプリケーションを 0→1 で作るときの設計書を、対話ヒアリングを通じて生成するスキルである。
技術スタック選定・アーキテクチャ・セキュリティ・プライバシー/計測・品質基準を1つの設計書に
まとめ、実装フェーズに引き渡すことを目的とする。

## 前提知識

- 対象は「新規開発」であり、既存プロジェクトへの機能追加・改修は対象外である。
- 設計書の各項目には確信度を示す信号機マークを付与する（詳細は次節）。この仕組みは
  Tsumiki（classmethod/tsumiki, MIT）の「信号機システム」を参考にしたものである。
- ヒアリングは AskUserQuestion ツールで1問ずつ提示する。まとめて質問しない。
- `references/` 配下のファイルはフェーズ横断で全部読ませるのではなく、**該当フェーズに
  入った時点で初めて読む**。各 Phase の冒頭に読むべきファイルを明記する。
- ユーザーが明示的に指定した情報を上書きしない。推測はあくまで補足であり、最終決定権は
  常にユーザーにある。

### 信号機システム（確信度マーキング）

生成する設計書の各項目に、次の3種のマークのいずれかを付与する。

| マーク | 意味 |
|---|---|
| 🔵 | ユーザー明示: ユーザーが明示的に指定・選択した情報 |
| 🟡 | 妥当な推測: 選択結果から推論した補足情報 |
| 🔴 | 要確認: 情報不足でAIが仮置きした情報。実装前にユーザー確認が必要 |

## ワークフロー

### Phase 0: 適用判定

まず、この依頼が新規開発かどうかを確認する。

- 新規開発（0→1）であれば Phase 1 に進む。
- 既存プロジェクトへの機能追加・バグ修正・リファクタリングであれば、このスキルの対象外
  であることを伝え、代わりに既存コードの分析から入る進め方（現状のアーキテクチャ調査、
  影響範囲の洗い出しなど）を案内してスキルを終了する。

### Phase 1: プロダクト要件のヒアリング

AskUserQuestion ツールを使い、1問ずつ提示する。最低限、次の5問を確認する。

| # | 質問 | 選択肢の例 |
|---|---|---|
| Q1 | プロダクト種別 | LP/コーポレート、Webアプリ（認証あり）、EC、メディア/CMS、ダッシュボード/管理画面、体験型サイト（3D/インタラクティブ） |
| Q2 | 想定規模と成長見込み | 個人・小規模、中規模、将来スケール想定 |
| Q3 | 扱うデータの機微度 | 公開情報のみ、個人情報あり、決済・認証情報あり、要配慮個人情報 |
| Q4 | 運用体制とランニングコスト上限感 | 1人、少人数、専任チーム |
| Q5 | 提供地域 | 日本国内のみ、EU含む、グローバル |

Q3（データの機微度）は Phase 4 のセキュリティ要件の強度を決める最重要の分岐であり、
Q5（提供地域）は Phase 5 の法規制対応の分岐に使う。この2問は特に丁寧に確認する。

質問は原則として単一選択とし、選択肢に該当しない場合に自由記述できる余地を残す。
ユーザーが即答できない質問（特にQ2の成長見込みなど）には、判断材料となる目安を
一言添えたうえで選ばせる。

ヒアリング結果はすべて 🔵 として設計書に記録する。ここで確定した回答は、以降の
Phase で AI が勝手に読み替えないこと。

### Phase 1.5: 要件のブレ確認

5問への回答が相互に矛盾する場合（例: Q3で「決済・認証情報あり」と回答しながらQ4で
「運用体制なし・コストは実質ゼロ」など、要件の重さと体制が釣り合わない場合）は、
先に進む前にその旨をユーザーに指摘し、意図した組み合わせかどうかを確認する。
矛盾がなければこのPhaseは実質スキップしてよい。

### Phase 2: 技術スタック選定

`references/tech-stack.md` を読む。

Phase 1 の回答（特にQ1・Q2・Q4）をもとに、領域別の候補を2〜3案に絞ってユーザーに提示し、
選ばせる。特定のベンダー・製品を「これ一択」と断定せず、判断基準（学習コスト、運用負荷、
将来の拡張性、コミュニティの成熟度など）を示したうえで選択を委ねる。

選定した案だけでなく、**却下した案とその理由**も必ず記録する。これは Phase 7 で ADR
（アーキテクチャ決定記録）に切り出す材料になる。

候補は次のような形式でユーザーに提示する。

| 領域 | 候補A | 候補B | 候補C |
|---|---|---|---|
| フロントエンド | （特徴・向き不向き） | （特徴・向き不向き） | （特徴・向き不向き） |
| バックエンド/API | … | … | … |
| データベース | … | … | … |
| ホスティング/デプロイ | … | … | … |

領域ごとに候補数は2〜3に絞る。多すぎる選択肢は判断コストを上げるため避ける。

### Phase 3: アーキテクチャ決定

`references/architecture-patterns.md` を読む。

次の項目を決める。

- レンダリング戦略（SSR/SSG/CSR/ハイブリッドなど）
- データ層（DB種別、ORM/クエリビルダの要否、キャッシュ戦略）
- 認証方式（自前実装/認証基盤サービス、セッション/トークンの方式）
- ディレクトリ構成
- デプロイ先とCI/CDの構成

Phase 2 で選んだスタックと矛盾しないように決定し、決定理由を記録する。

### Phase 4: セキュリティ設計（省略不可）

`references/security-baseline.md` を読む。

**このPhaseは省略できない。** プロダクト種別や納期にかかわらず必ず実施する。

Phase 1 Q3（データの機微度）に応じて、OWASP Top 10 ベースの必須対策のレベルを決める。
機微度が上がるほど、認証・認可・入力検証・通信の暗号化・監査ログなどの対策を厚くする。
情報が不足していて仮置きした対策は 🔴 として明示する。

機微度とセキュリティ対策レベルの対応関係は、目安として次のように考える（詳細な対策
一覧は `references/security-baseline.md` に従う）。

| Q3の回答 | 対策レベルの目安 |
|---|---|
| 公開情報のみ | 基本的な入力検証・依存パッケージの脆弱性対応が中心 |
| 個人情報あり | 上記に加え、アクセス制御・通信の暗号化・ログの取り扱い方針が必須 |
| 決済・認証情報あり | 上記に加え、決済は自前実装せず外部決済サービスへ委譲し、認証は多要素認証や既存の認証基盤サービスの利用を優先的に検討する |
| 要配慮個人情報 | 上記に加え、暗号化・監査ログ・アクセス権限の最小化・データ保持期間の明文化を必須とし、法令・ガイドラインの追加確認を促す |

なお、決済・認証情報や要配慮個人情報を扱う場合は、対策の妥当性について専門家
（セキュリティ担当者・弁護士など）へのレビューを別途挟むことをユーザーに提案する。

### Phase 5: プライバシー・計測設計

`references/privacy-and-marketing.md` を読む。

次を決める。

- Cookie の利用有無とその用途
- 同意管理（コンセントバナー等）の要否 — Phase 1 Q5（提供地域）で分岐する。EU圏を含む
  場合は同意管理の要件が厳格になる点に注意する
- アクセス解析・計測基盤の選定

提供地域と同意管理の要否は、目安として次のように整理する（法令の詳細と最新動向は
`references/privacy-and-marketing.md` を参照する）。

| Q5の回答 | 同意管理の要否の目安 |
|---|---|
| 日本国内のみ | Cookieを使う場合は利用目的の明示が中心。同意管理は必須ではないが推奨 |
| EU含む | 同意管理（オプトイン方式のコンセントバナー等）を必須として設計する |
| グローバル | 提供地域ごとに法規制が異なるため、最も厳しい地域の基準に合わせるか、地域判定で出し分けるかを Phase 1 Q4（運用体制）と照らして決める |

計測基盤は、収集する項目が個人情報に該当しないかを Phase 4 のセキュリティ設計と
突き合わせて確認する。

### Phase 6: 領域別レシピ適用

`references/domain-recipes.md` を読む。

Phase 1 Q1 で該当する領域（3D表現、リアルタイム通信、EC決済、AI機能など）がある場合の
みレシピを適用する。**該当領域がなければこのPhaseはスキップする。**

### Phase 6.5: 品質基準の設定

`references/quality-gates.md` を読む。

設計書の非機能要件として、次を数値で決める。感覚的な「速くする」「使いやすくする」で
終わらせず、達成したか判定できる形にする。

- パフォーマンス予算（Core Web Vitals の目標値、JavaScript バンドルサイズの上限）
- アクセシビリティの到達目標（準拠する基準とレベル、自動チェックと手動確認の分担）
- SEO 要件（インデックス対象、構造化データの要否）
- 可観測性（エラートラッキング、監視する指標、アラートの閾値）
- テスト戦略（0→1 フェーズで最低限書くテストの範囲）
- CI で落とす基準（型チェック・Lint・テスト・ビルドのうち必須にするもの）

プロダクト種別によって現実的な閾値は変わる（例: 3D 表現を含むサイトに LP と同じ
初期表示速度を要求しない）。`references/quality-gates.md` の種別ごとの目安に従う。

### Phase 7: 設計書の出力

次のファイルを生成する。

1. `templates/design-doc.md` に沿って `docs/design/design-doc.md` を生成する。
   Phase 1〜6 で決定した全項目に信号機マークを付ける。
2. Phase 2・Phase 3 の重要な決定は `templates/adr.md` を使って
   `docs/design/adr/NNNN-*.md` に個別のADRとして切り出す（選定理由・却下理由を含める）。
3. `templates/release-checklist.md` から `docs/design/release-checklist.md` を生成する。

生成した設計書の末尾に、🔴（要確認）が付いた項目だけを集めた
「実装前に確認が必要な項目」一覧を付ける。ユーザーはここだけ見れば、何を確定させれば
実装に進めるかが分かる状態にする。

### Phase 8: 実装への引き渡し

`references/component-registry.md` を読む。

設計書で決めた要件に対応する既製コンポーネント・ライブラリ・テンプレートを提示し、
導入コマンドを設計書に追記する。**ゼロから書く前に、まず既製品を当たる**のが原則である。
既製品で要件を満たせない箇所だけを自前実装の対象として切り出す。

## このスキルが行わないこと

- 実装コードそのものを書くこと（設計書と決定事項の引き渡しまでが範囲である）
- 既存コードの改修・リファクタリング
- デザインカンプ（ビジュアルデザイン）の作成

## 出力物一覧

| ファイル | 内容 |
|---|---|
| `docs/design/design-doc.md` | 設計書本体。全項目に信号機マーク付き |
| `docs/design/adr/NNNN-*.md` | 技術選定・アーキテクチャ決定のADR（複数） |
| `docs/design/release-checklist.md` | リリース前チェックリスト |

## 出典・参考

このスキルのフェーズ構成と信号機システムは、Tsumiki
（https://github.com/classmethod/tsumiki, MIT License）の設計思想を参考にしたもの
である。