The Artifact Creation Pipeline

Step 1: Set up the project

This is where the build starts. Open a terminal, navigate to ~/dev, launch Claude Code, and paste this setup prompt:

Create the folder ~/dev/web-dev/p2. Download the project materials from https://learnbydirectingai.dev/materials/webdev/p2/materials.zip and extract them into that folder. Read CLAUDE.md — it's the project governance file. Open VS Code in the project directory. Install the Claude Code extension and the Live Server extension if they aren't already installed.

Claude will create the project folder, download and extract the materials, read the governance file, and open VS Code. Wait for it to finish. You should see the project directory in VS Code's sidebar with a materials/ folder containing templates, Yasmine's email, product data, and photos.

Step 2: Tour the materials

Before you create anything, look at what you have.

Open materials/first-contact.md. This is Yasmine's follow-up email from Unit 1. It stays open throughout this unit because every planning document you create draws from it.

Open materials/templates/. Three templates live here:

• prd-template.md -- the structure for a Product Requirements Document
• design-decisions-template.md -- where you record what tools you chose and why
• ticket-template.md -- the format for breaking work into directed tasks

Each template has section headings and brief descriptions of what goes in each section. They are structures, not answers. You fill them with content derived from Yasmine's email.

Open materials/product-data.json. Eight products across four categories: bags, wallets, belts, and a custom piece. Each entry has a name, category, leather type, price range, photo paths, and alt text. This data feeds the components you'll build in later units.

Open materials/custom-work-brief.md. Details about Yasmine's custom leather work process: what she makes, how long it takes, what materials she uses, how someone starts the process. You'll need this in a later unit, but knowing it exists shapes how you write the PRD.

Step 3: Draft the PRD

Open materials/templates/prd-template.md. It has six sections: Project Overview, Client Background, Requirements, User Stories, Technical Constraints, and Success Criteria. Read each section heading and its description. This is the same document structure that was provided for you in P1. Now you create one from scratch.

Direct Claude to draft the PRD using Yasmine's email as the source material. Be specific about what you want:

Read materials/first-contact.md. Using the PRD template in materials/templates/prd-template.md, draft a PRD for this project. Fill in each section based on what Yasmine describes in her email. For Requirements, capture all three features she asks for: product detail views, category filtering, and a custom work section. For Technical Constraints, note that the site needs to work on phones — Yasmine's customers browse on mobile. Save the completed PRD as planning/prd.md.

When Claude finishes, open planning/prd.md and read it against Yasmine's email. Go section by section:

• Project Overview: Does it describe what's being built without adding features Yasmine didn't ask for?
• Client Background: Does it capture who Yasmine is and what her business does? Not a generic artisan bio, but the specific person who showed her site to Nadia and watched how customers browse.
• Requirements: Are all three features present? Detail views with close-up photos. Category filtering for bags, wallets, belts, and custom pieces. A custom work information section.
• User Stories: Do they reflect real behavior? "As a collector browsing on my phone, I want to see close-up details of the stitching" is grounded. "As a user, I want to filter products" is generic.
• Technical Constraints: Does it mention mobile responsiveness? Does it reference the existing site (this is an upgrade, not a new build)?
• Success Criteria: Are the criteria things you can actually check? "The site looks good" is not checkable. "Every product card links to a detail view with at least two additional photos" is.

If any section is thin or adds assumptions Yasmine's email doesn't support, fix it now. The PRD is the foundation for everything that follows. Gaps here become bugs later.

Step 4: Self-review the PRD

This is the first time you'll direct Claude to review its own output. The quality of the review depends entirely on how you ask for it.

Direct Claude with a specific review prompt:

Review the PRD you just created against Yasmine's email in materials/first-contact.md. List every requirement mentioned in Yasmine's email and state whether the PRD addresses it. Then list anything the PRD includes that Yasmine's email does not mention. Be specific — quote the relevant parts of the email.

Read what Claude produces. A good self-review identifies specific gaps: "Yasmine mentions 'the stitching, the clasp, different angles' but the PRD's detail view requirement only says 'additional photos' without specifying what the photos should show." A weak self-review says "The PRD covers all requirements from the email" without citing evidence.

If the review is vague, redirect. Ask Claude to be more specific. The habit you're building here matters more than whether the PRD is perfect. "Review your work" produces reassurance. "List every requirement and whether the PRD addresses it" produces findings. That distinction applies to every piece of work Claude generates.

Fix any gaps the review surfaces before moving on.

Step 5: Record design decisions

Open materials/templates/design-decisions-template.md. Four decisions to record: Framework Choice, Styling Approach, Build Tooling, and Deployment Target.

The choices for this project are guided. You're using React with TypeScript for the interactive components, Tailwind CSS for styling, Vite as the build tool, and Vercel for deployment. The value of recording them isn't choosing differently. It's understanding why these tools fit.

Direct Claude to fill in the design decisions template:

Using the template in materials/templates/design-decisions-template.md, record the design decisions for this project. For each section, state what was chosen, what alternatives exist, and why this choice fits Yasmine's project. Save as planning/design-decisions.md.

Review what Claude produces. The rationale should connect tools to the project, not recite marketing copy. "React because it's popular" is not a rationale. "React because the product showcase needs interactive filtering and detail views that update without page reloads, and React's component model maps directly to those UI pieces" connects the tool to the work.

Check the alternatives too. Claude should mention real alternatives, not straw men. Vanilla JavaScript is a real alternative for a site this size. Vue is a real alternative framework. If Claude only lists obviously worse options, the decisions section isn't honest.

Step 6: Draft the architecture

The PRD says what to build. The design decisions say what tools to use. Architecture says how the pieces fit together.

Direct Claude to draft the component architecture:

Based on the PRD in planning/prd.md and the design decisions in planning/design-decisions.md, draft the component architecture for this project. Define: what components exist, what data each component receives (props), where state lives (which component owns the "selected category" and "selected product" state), and how components compose together. Save as planning/architecture.md.

Review the architecture against the PRD. Every requirement in the PRD should map to at least one component or feature in the architecture. The filtering requirement needs a filter component and a state that tracks the active category. The detail view requirement needs a detail component and a state that tracks which product is selected. The custom work section is a content component with no complex state.

Pay attention to where Claude puts the state. If the filter state lives inside the filter component but the product grid also needs to know the active category, the state is in the wrong place. State needs to live in a component that can pass it down to everything that needs it. This is a design decision with real consequences for how the code grows.

Step 7: Create CLAUDE.md

CLAUDE.md is the governance file. In P1, it was provided for you. Now you create one that synthesizes everything you've built: the PRD, design decisions, architecture, and the ticket breakdown you'll create next.

Direct Claude to generate it:

Create a CLAUDE.md file for this project. It should contain: the project name (Atelier Khelifi Interactive Showcase), the client (Yasmine Khelifi), a one-line description, the tech stack (React + TypeScript, Vite, Tailwind CSS, Vitest, Vercel), the file structure, references to the planning documents, and placeholder sections for tickets and verification targets. Save as CLAUDE.md in the project root.

This file is what Claude reads at the start of every session. When you open Claude Code tomorrow and start working on a ticket, CLAUDE.md tells Claude everything it needs to know: who the client is, what the tech stack is, what the tickets are, what the acceptance criteria look like. If CLAUDE.md is incomplete, Claude will ask questions you've already answered or make assumptions that contradict your planning documents.

Step 8: Create the ticket breakdown

Open materials/templates/ticket-template.md. Each ticket has a T-prefix ID, a title, 2-3 acceptance criteria, and a scope that fits one directing session.

Direct Claude to create the ticket breakdown:

Using the template in materials/templates/ticket-template.md and the architecture in planning/architecture.md, create a ticket breakdown for this project. Six tickets: T1 (project setup and scaffold), T2 (product card component), T3 (category filter with state management), T4 (product detail view), T5 (custom work section and security), T6 (deployment to Vercel). Each ticket needs a clear title and 2-3 acceptance criteria that are specific enough to verify. Save as planning/tickets.md.

Review each ticket. The acceptance criteria should be checkable. "Component works correctly" is not checkable. "Product card displays the product name, leather type, price range, and an image with descriptive alt text" is. Every criterion should describe something you can see, run, or measure.

Check the sequence. T1 creates the project structure. T2 builds the first visible component. T3 adds interactivity. T4 adds the second major feature. T5 handles content and security. T6 deploys. Each ticket builds on the one before it. If T3 depends on something T4 creates, the order is wrong.

Now update CLAUDE.md with the complete ticket list and verification targets. Direct Claude:

Update CLAUDE.md to include the full ticket list from planning/tickets.md with all acceptance criteria. Add verification targets: html-validate 0 errors, Lighthouse >= 90 in all categories, all Vitest tests passing, keyboard accessibility on interactive components. Add the commit convention: conventional commits, one ticket per commit.

Step 9: Verify the pipeline

You've run the artifact creation pipeline: Yasmine's email became a PRD, the PRD informed design decisions, design decisions shaped the architecture, and everything was synthesized into CLAUDE.md with a ticket breakdown. Each document fed the next.

Direct Claude to verify the chain is complete:

Review the planning artifacts in this project. Check: Does the PRD capture all three features from Yasmine's email? Do the design decisions reference the PRD's technical requirements? Does the architecture map to every PRD requirement? Does CLAUDE.md include every ticket with acceptance criteria? List any gaps.

Read the findings. If Claude identifies a gap, fix it. The pipeline is only as strong as its weakest link. A missing requirement in the PRD means a missing component in the architecture means a missing ticket in the breakdown.