claudecode-boilerplate/README.md

# claude-code-book-chapter8

This repository is the GitHub repository that manages the sample code for ["Practical Claude Code Introduction - A Way of Thinking About AI Coding for Real-World Use"](https://www.amazon.co.jp/dp/4297153548), published by Gijutsu-Hyohron Co., Ltd.

For detailed explanations of the code and prompts in this repository, please refer to the book.

For questions about the book's content or to report errata, please use the issues in the following repository.

https://github.com/GenerativeAgents/claude-code-book

## Development Workflow (Step by Step)

How a project goes from idea to working code with this boilerplate:

```
Idea → /setup-project → /define-design → refine design → /plan-milestones → /execute-milestones (phase by phase; milestone 01 generates the app)
```

### Step 1 — Write down your idea
Put your brainstorming notes, requirements, and constraints into
`docs/ideas/initial-requirements.md` (free-form; replace the sample content with your own).

### Step 2 — Create the specification: `/setup-project`
Automatically creates the six persistent documents that define **what to build**:
PRD, functional design, architecture, repository structure, development guidelines, and glossary
(all under `docs/`). Review them and request edits in normal conversation if needed.

### Step 3 — Define the UI/UX design: `/define-design`
First builds an **exhaustive screen inventory** (`screen-inventory.md`) from the PRD and
functional design — every user story walked end-to-end, plus list/detail/create/edit/delete
coverage for every entity — so no screen gets skipped. Then creates the design specification
under `docs/design/`: design brief, design tokens, **`ui-blueprint.json` (the source of truth
for UI generation, one entry per inventory screen)**, platform mapping, and SVG wireframes
(visual references only). You'll be asked once about platform, style, screens, navigation,
branding, and accessibility.

### Step 4 — Review and refine the design **before writing any code**
This is the key design-decision gate: iterate on the design while it is still cheap to change.

- `/update-design <change>` — targeted refinements (e.g. `add a profile screen`)
- Re-run `/define-design` — change the overall direction
- Repeat until you approve the design (especially `ui-blueprint.json`)

### Step 5 — Plan milestones: `/plan-milestones`
Breaks the product into **phases** and milestones, and generates `docs/milestones/`:
a `roadmap.md` overview plus **one file per phase** (`phase1-milestones.md`,
`phase2-milestones.md`, …). Each phase file lists its milestones and **the features they
contain** — each feature sized for exactly one `/add-feature` run, with acceptance criteria and a
ready-to-run command. **Milestone 01 is always "App Shell Generation"**: it scaffolds the initial
app from the approved design (theme from tokens, one screen per blueprint entry, routes, reusable
components — no feature logic) plus the Playwright smoke spec; there is no separate generate-app
step. Phase 1 delivers the MVP; later phases build on it by priority and dependency.

### Step 6 — Implement the milestones

Two ways to work through the plan:

**Option A — execute a phase file: `/execute-milestones <phase-file>`**
Requires the phase file to execute, e.g. `/execute-milestones phase1-milestones.md`. Runs that
phase's milestones **one by one, autonomously**. For each milestone it creates a **separate
steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the milestone's
features into concrete tasks grouped by feature, implements them all, validates, tests,
reconciles the docs, and marks the milestone completed — then immediately starts the next
milestone in the file. When the phase completes, run it again with the next phase file.

**Option B — one feature at a time: `/add-feature <feature>`**
A fully autonomous loop, one feature per run. Each run:

1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
2. Reads the feature's entry in its phase file and the design spec first — and updates the design first if the feature changes the UI
3. Implements every task in `tasklist.md`, checking items off as it goes
4. Validates quality with the `implementation-validator` subagent
5. Writes Playwright E2E tests for the feature's acceptance criteria, then runs `npm test`, `npm run lint`, `npm run typecheck`, and `npm run test:e2e` until green
6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its phase file

### Step 7 — Repeat and maintain
- Remaining phases → `/execute-milestones <next phase file>`, or feature by feature with `/add-feature <feature>`
- UI changes → `/update-design <change>` first, then `/add-feature`
- Re-planning → re-run `/plan-milestones` or edit `docs/milestones/` in conversation
- Document quality checks → `/review-docs <path>`

**A feature is "done" when**: all tasks in its tasklist are `[x]`, validation passes,
test/lint/typecheck and the Playwright E2E suite succeed, and the persistent documents are back
in sync with the code.

## E2E Testing (Playwright)

Every verification step in this boilerplate includes end-to-end tests. The standard verification
sequence — used by `/add-feature` and `/execute-milestones` — is:

```bash
npm test           # unit tests
npm run lint
npm run typecheck
npm run test:e2e   # Playwright E2E
```

How it works (defined in the `e2e-testing` skill):

- **Setup is automatic**: on the first verification, if Playwright is missing, the agent installs
  `@playwright/test`, creates `playwright.config.ts` (dev-server integration, trace/screenshot on
  failure), and adds the `test:e2e` script.
- **Tests are derived from acceptance criteria**: each feature gets `e2e/[feature].spec.ts` with
  one test per acceptance criterion, written before verification runs.
- **The app shell has a smoke spec**: the App Shell milestone (milestone 01) creates `e2e/app-shell.spec.ts`, which
  checks that the shell renders and every route in `ui-blueprint.json` navigates.
- **Blueprint-driven locators**: tests navigate by the blueprint's routes and use semantic
  locators (`getByRole`, `getByLabel`) — no CSS/XPath tied to implementation details, no fixed waits.
- **No green-washing**: a failing E2E test is fixed, never skipped or deleted; milestone gates in
  `/execute-milestones` do not pass without a green E2E suite.

```
e2e/
├── app-shell.spec.ts        # smoke: shell renders, all blueprint routes navigate
├── [feature-name].spec.ts   # one spec per feature (acceptance criteria)
└── helpers/                 # shared fixtures (only when duplicated 3+ times)
```

Playwright covers the `web` target; for `flutter` the equivalent is `integration_test`, and for
`winui3` the platform's UI automation — with the same acceptance-criteria mapping.

## Notes

The content of this repository may be changed to improve prompt performance based on feedback from readers. Differences will be reflected in the book as needed, but please be aware that there may be discrepancies with the edition you have on hand.

## Usage

### 1. Clone the repository

```bash
git clone [this repository] claude-code-book-chapter8
cd claude-code-book-chapter8
```

### 2. Open via Dev Container

When you select "Reopen in Container" in Visual Studio Code, the environment is automatically set up as follows.

- Building a Node.js LTS environment
- Running npm install
- Installing the latest version of Claude Code

* When using Dev Container, you need to install Docker in advance.

### 3. Start Claude Code and follow the workflow

```bash
claude
> /setup-project
> /define-design
> /update-design [refinement]      # repeat until the design is approved
> /plan-milestones                  # milestone 01 = app shell generation
> /execute-milestones phase1-milestones.md   # one phase at a time, or:
> /add-feature [feature name]                # one feature at a time
```

See [Development Workflow (Step by Step)](#development-workflow-step-by-step) above for what each step does.

## Commands Reference

| Command | Description | Example |
|---|---|---|
| `/setup-project` | Create the six persistent documents automatically | `/setup-project` |
| `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
| `/update-design` | Refine the design before generation, or update it when a feature changes the UI | `/update-design add a profile screen` |
| `/plan-milestones` | Plan phases and milestones; generates one `phase[N]-milestones.md` per phase (milestone 01 = App Shell Generation) | `/plan-milestones 2 phases, MVP first` |
| `/execute-milestones` | Execute one phase file: its milestones one by one, with separate steering documents per milestone (file argument required) | `/execute-milestones phase1-milestones.md` |
| `/add-feature` | Implement a feature end-to-end (autonomous) | `/add-feature User profile editing` |
| `/review-docs` | Detailed document review via subagent | `/review-docs docs/architecture.md` |