# Web Project Plan

> Skill for planning and scaffolding new web projects through a structured interview. Walks developers through features, tech stack, MVP scope, and generates AGENTS.md + docs/ structure as real files. Also generates CLAUDE.md for Claude Code users. Triggers on: "new project", "project setup", "pick a stack", "web project plan", "새 프로젝트", "프로젝트 세팅", "スタック選定", "新しいプロジェクト", "新项目", "项目搭建", "nouveau projet", "neues Projekt", "nuevo proyecto"

- Skill: `rhino-ty/web-project-plan` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add rhino-ty/web-project-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rhino-ty/web-project-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: rhino-ty (https://skillmd.com/u/rhino-ty)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rhino-ty/web-project-plan

---


# Web Project Plan

Skill that concretizes a new web project through an interview and generates project files.

**Audience**: Developers. Use technical terms directly.
**Scope**: Web projects only.
**Goal**: By end of session, agent context file + required `docs/` structure exist as real files.

> Which context file to generate depends on the user's AI tool (see Phase 4-3):
> `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex/Copilot/Gemini, etc.

---

## Directory Structure

```
README.md
AGENTS.md or CLAUDE.md # Agent context file (see Phase 4-3 for which one)
docs/
  INDEX.md             # Document map
  QUICK_REF.md         # Commands & env vars cheatsheet
  ROADMAP.md           # MVP scope + backlog
  references/          # Tech references (generated by this skill)
    UI.md
    AUTH.md
    DB.md
    ...
```

---

## Session Flow

### Phase 1 — Project Identity

> **1. Project name / working title?**
>
> **2. One-line description?**
> (What it does, for whom, what problem it solves)
>
> **3. Primary users?**
> → Personal tool / Public product / Internal tool
>
> **4. Web project type?**
> → SPA / SSR (SEO matters) / SSG (static content) / Not sure yet
>
> **5. Existing stack or boilerplate?**
>
> **6. Package manager?**
> → pnpm / npm / yarn / bun / Not sure yet

---

### Phase 2 — Feature Scoping

Only present questions relevant to Phase 1 answers.

**[Data Persistence]**
```
A. Need a database?
   → Yes — What data?
   → No
```

**[Auth & Permissions]**
```
B. Login / accounts?
   → Yes → Social / Email / Both
   → No

   (If Yes) B-1. User data visibility?
   → Private / Partially public / Fully public

   (If Yes) B-2. Role separation?
   → None (single user type)
   → Yes → Which roles? (admin / user / guest, etc.)
```

**[Social / Sharing]**
```
C. Can users view other users' content? (feed, board, etc.)
   → Yes / No
```

**[Search]**
```
D. Search feature?
   → No
   → Yes → What data to search?
            Real-time suggestions needed? (Yes / No)
            Data scale? (Small → PostgreSQL FTS / Large → Algolia · Meilisearch)
```

**[Payments]**
```
E. Payments?
   → No / one-time / subscription / per-feature
```

**[AI]**
```
F. AI features needed?
   → Yes → What kind? (generation / analysis / recommendations / summarization)
            Streaming responses needed? (Yes / No)
   → No
```

**[External APIs]**
```
G. External service integrations?
   → Yes → Which ones?
   → No
```

**[Files / Media]**
```
H. File upload / storage needed?
   → Yes → What files? (images / documents / video)
            Per-user private or public?
   → No
```

**[Notifications]**
```
I. Notifications? (push / email / SMS)
   → Yes → What triggers?
   → No
```

**[Realtime]**
```
J. Real-time sync or collaboration needed?
   → Yes / No
```

**[i18n]**
```
K. Multi-language support?
   → No
   → Yes → How many languages? / From v1 or later?
```

---

### Phase 3 — Design & UI

Only present relevant questions.

**[References & Assets]** — Always ask
```
L. Design reference? (Figma / reference site / none)

M. Brand assets? (colors, logo, fonts) → Yes / No
```

**[Rendering & SEO]** — Always ask if Public product
```
N. SEO requirements?
   → None
   → OG tags + sitemap level
   → Content SEO — search visibility matters (SSR/SSG strategy needed)
```

**[Theme]** — Always ask
```
O. Dark mode support?
   → Yes / No
```

**[Screen Structure]** — Always ask
```
P. Number of screens?
   → ~3 / 4~10 / 10+

   Reusable components? → Yes / No

P-1. Layout approach?
   → Responsive (mobile-first)
   → Fixed width (dashboard, admin, etc.)
   → Both

   (If responsive) P-2. Primary usage context?
   → Mobile-first / Desktop-first / Equal

   (If responsive) P-3. Layout changes at breakpoints?
   □ Navigation (e.g., desktop sidebar → mobile bottom tab bar or hamburger)
   □ Grid/card layout (e.g., 3 cols → 1 col)
   □ Table → card-based restructure
   □ Form layout changes
   □ No changes (scale only)

   (If responsive) P-4. Touch interactions needed?
   → Yes (swipe, tap target sizing, etc.) / No
```

**[Interactions]** — Always ask
```
Q. Interaction requirements?
   □ Drag and drop
   □ Animations / transitions
   □ Charts / data visualization
   □ None
```

---

### Phase 4 — Stack & MVP Scope

#### 4-1. Stack Proposal

Propose stack based on Phase 1–3 answers.
If existing stack provided, align with it.
Only add rows relevant to feature answers.

**Framework selection guide** (based on Phase 1 answers):
- SSR/SSG needed + React → **Next.js 15 (App Router)**
- SSR/SSG needed + Vue → **Nuxt 3**
- SPA + React → **Vite + React**
- SPA + Vue → **Vite + Vue**
- Static content focused → **Astro**
- Not sure → Default to Next.js 15 (most versatile)

```
## Proposed Stack

| Area          | Choice                      | Why  |
|---------------|-----------------------------|------|
| Pkg Manager   | pnpm                        | ...  | ← Phase 1-6 answer
| Frontend      | Next.js 15 (App Router)     | ...  | ← guide above
| Styling       | Tailwind v4 + shadcn/ui     | ...  |
| Auth          | Supabase Auth               | ...  | ← if B = Yes
| DB            | Supabase (PostgreSQL)       | ...  | ← if A = Yes
| ORM           | Drizzle ORM                 | ...  | ← if A = Yes
| Search        | PG FTS / Algolia            | ...  | ← if D = Yes
| AI            | Anthropic / OpenAI          | ...  | ← if F = Yes
| Storage       | Supabase Storage / S3       | ...  | ← if H = Yes
| Notifications | Resend / FCM                | ...  | ← if I = Yes
| Payments      | Stripe / Toss Payments      | ...  | ← if E = Yes
| i18n          | next-intl                   | ...  | ← if K = Yes
| Testing       | Vitest + Playwright         | ...  | always
| Deploy        | Vercel                      | ...  |
```

**"Anything you'd like to change?"** — Confirm or revise, then finalize stack.

#### 4-2. MVP Scope Cut

Show the full feature list from Phase 2–3:

> "Separate into must-have for v1 vs. can-wait for later. If unsure, I'll propose."

- **v1 (Must)** → `docs/ROADMAP.md` confirmed section
- **v2+ (Later)** → `docs/ROADMAP.md` backlog section

#### 4-3. Deploy & Dev Environment

```
1. Deploy platform? (Vercel / Railway / AWS / other)
2. CI/CD pipeline? (GitHub Actions / other / none)
3. Testing strategy?
   → Unit only / Unit + E2E / none
   → E2E tool: Playwright / Cypress
4. Monorepo vs single repo?
5. AI coding tool? (Claude Code / Codex / Cursor / Copilot / Gemini / none)
```

**Agent context file generation** (based on Q5 answer):

| Q5 Answer | File generated |
|-----------|----------------|
| Claude Code | `CLAUDE.md` |
| Codex / Copilot / Gemini | `AGENTS.md` |
| Cursor | `AGENTS.md` + `.cursorrules` suggested |
| None / not sure | Present the options and recommend |

> Content is the same regardless of filename — only the filename changes to match what each agent reads.
> Write the file following `references/AGENTS_MD_GUIDE.md`.
>
> **If the user doesn't specify an AI tool, or says "not sure":**
> Present a short recommendation like this:
>
> "Which AI coding tool will you use? This decides the context filename:
> - **Claude Code** → `CLAUDE.md`
> - **Codex / Copilot / Gemini** → `AGENTS.md`
> - **Not sure / multiple** → I'll generate `AGENTS.md` (most widely supported)
> - **None** → I'll still generate `AGENTS.md` — useful if you adopt one later"
>
> Then proceed with their choice. Don't silently pick one.

---

## Internal Mapping Table

| Answer | Generated Document |
|---|---|
| A: DB needed | `docs/references/DB.md` |
| B: Auth needed | `docs/references/AUTH.md` |
| B-2: Roles needed | `docs/references/AUTH.md` — add RBAC section |
| C: Social/feed | `docs/references/AUTH.md` + `docs/references/DB.md` |
| D: Search — PostgreSQL FTS | `docs/references/DB.md` — add search strategy section |
| D: Search — external (Algolia, etc.) | `docs/references/API.md` — add Search section |
| E: Payments | `docs/references/BILLING.md` |
| F: AI features | `docs/references/AI_SYSTEMS.md` |
| G: External APIs | `docs/references/API.md` |
| H: Storage | `docs/references/ARCHITECTURE.md` — Storage section |
| I: Notifications | `docs/references/ARCHITECTURE.md` — Notifications section |
| J: Realtime | `docs/references/ARCHITECTURE.md` — Realtime section |
| K: i18n | `docs/references/ARCHITECTURE.md` — i18n section |
| Any of L~Q | `docs/references/UI.md` |
| P-1: Responsive | `docs/references/UI.md` — Breakpoints & layout changes section |
| N: SEO needed | `docs/references/UI.md` — SEO section |
| CI/CD needed | `docs/references/ARCHITECTURE.md` — CI/CD section |
| AI coding tool = Claude Code | `CLAUDE.md` + `docs/references/prompts/` |
| AI coding tool = other/none | `AGENTS.md` + `docs/references/prompts/` (if AI features exist) |

**Always generated**: `README.md`, agent context file (per Phase 4-3), `docs/INDEX.md`, `docs/QUICK_REF.md`, `docs/ROADMAP.md`, `docs/references/README.md`

---

## Document Writing Rules

All generated `docs/references/*.md` follow this section order:

```md
## Purpose
## Current State
## Current Rules
## [Topic-specific core sections]
## Related Docs
```

File naming:
- Reference docs: uppercase topic — `AUTH.md`, `DB.md`, `UI.md`
- Session records: date-based — `SESSION-SUMMARY-2026-04-06.md`
- Filenames in English, body text in user's language

### Agent context file principles

When writing `CLAUDE.md` / `AGENTS.md`, apply these principles (adapted from [Karpathy's coding guidelines](https://x.com/karpathy/status/2015883857489522876)):

1. **Surface, don't assume** — include only what the agent would get wrong without knowing. Skip generic advice ("write clean code"). Prefer concrete prohibitions ("Never modify `src/components/ui/`").
2. **Minimum content** — respect Length Guidelines in `references/AGENTS_MD_GUIDE.md` (Simple 30-50 / Standard 60-100 / Complex 100-150). When over budget, delegate details to `docs/references/*.md` and link.
3. **Trace every line to a Phase 1-3 answer** — no speculative future-proofing, no sections for features the user didn't request. If a line can't point back to an interview answer, cut it.
4. **Verifiable, not aspirational** — Commands must actually run. "Do Not" rules must be checkable. Replace "follow best practices" with "Server components by default, `'use client'` only when needed".

#### Required block in generated file

Append this section verbatim at the end of the generated `CLAUDE.md` / `AGENTS.md`. Counts toward length budget (~7 lines):

```md
## Coding Principles
- Surface assumptions; ask when unclear, don't pick silently.
- Minimum code only — no speculative features, abstractions, or "flexibility" that wasn't requested.
- Surgical changes — every changed line must trace to the request; don't refactor unrelated code.
- Define verifiable success before coding (test, command, or expected output).
- For multi-step tasks, state a brief plan with verify steps before executing.
```

---

## Final Output

```
## Document Structure

[Always generated]
README.md
CLAUDE.md or AGENTS.md   ← depends on AI tool (Phase 4-3)
docs/
  INDEX.md
  QUICK_REF.md
  ROADMAP.md
  references/
    README.md

[Added for this project]
docs/references/AUTH.md         ← Login + RBAC
docs/references/DB.md           ← Data persistence + search strategy
docs/references/BILLING.md      ← Subscription payments
docs/references/AI_SYSTEMS.md   ← AI features
docs/references/UI.md           ← Screen specs + dark mode + SEO
docs/references/ARCHITECTURE.md ← Storage, notifications, realtime, i18n, CI/CD

[Omitted]
docs/references/API.md ... (one-line reason each)
```

> Generate files with this structure?

If YES, generate in this order:

1. Agent context file — Read `references/AGENTS_MD_GUIDE.md`, then write `CLAUDE.md` or `AGENTS.md` per Phase 4-3, applying the "Agent context file principles" in Document Writing Rules.
2. `README.md` — Project overview + confirmed stack + local run instructions
3. `docs/INDEX.md` — Links to all active docs + one-line descriptions
4. `docs/ROADMAP.md` — Based on MVP scope cut results
5. Remaining `docs/references/*.md` — Follow section template above

---

## Tone

Direct, technical conversational style. Present phase by phase, one at a time.
Respond in the user's language.