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", 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 → /generate-app → /plan-milestones → /execute-milestones (phase by phase)

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

Creates the design specification under docs/design/: design brief, design tokens, ui-blueprint.json (the source of truth for UI generation), 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 — Generate the initial app: /generate-app web | flutter | winui3

Scaffolds the app shell from the approved design: theme (from tokens), routes, screens, and reusable components. No feature logic yet.

Step 6 — 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. Phase 1 delivers the MVP; later phases build on it by priority and dependency.

Step 7 — 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. Runs npm test, npm run lint, npm run typecheck until green
6. Records a retrospective, reconciles all six docs/ documents, and checks the feature off in its phase file

Step 8 — 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 succeed, and the persistent documents are back in sync with the code.

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

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

claude
> /setup-project
> /define-design
> /update-design [refinement]      # repeat until the design is approved
> /generate-app web                 # or flutter | winui3
> /plan-milestones
> /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) 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
/generate-app	Scaffold the initial app for a target platform	/generate-app web
/plan-milestones	Plan phases and milestones; generates one phase[N]-milestones.md per phase	/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