# Prompt for Claude Code - Spec-Driven Development

Create a complete personal portfolio project with a tech blog using a **Specification-Driven Development approach**. First define specifications, then implement code that meets these specs.

## Development Process - REQUIRED ORDER

### PHASE 1: Specifications and Documentation (start here!)
Before writing any production code, create:

1. **Technical Specification Document** (`docs/TECHNICAL_SPEC.md`):
   - Architecture Decision Records (ADRs)
   - Why Astro? Why Tailwind? Why Vitest?
   - Data flow diagrams
   - Component hierarchy
   - Type system design

2. **API Specifications** (`docs/API_SPEC.md`):
   - Content Collections schema (Zod schemas with examples)
   - Types for blog posts, tags, categories
   - Utility functions signatures
   - Expected input/output for each function

3. **Component Specifications** (`docs/COMPONENT_SPEC.md`):
   - List of all components with props interface
   - Behavior specifications
   - Accessibility requirements
   - Usage examples

4. **Test Specifications** (`docs/TEST_SPEC.md`):
   - Test scenarios for each component
   - E2E user flows
   - Edge cases and error scenarios
   - Expected coverage targets (>80% for utils)

5. **User Stories** (`docs/USER_STORIES.md`):
   ```
   As a blog reader
   I want to filter posts by tags
   So that I can find content that interests me
   
   Acceptance Criteria:
   - [ ] Clicking a tag redirects to /tags/[tag-name]
   - [ ] Page shows all posts with that tag
   - [ ] Displays post count
   - [ ] Dark mode works
   ```

### PHASE 2: Type Definitions (Types-First Approach)
Based on specs, create:

1. **`src/types/index.ts`** - All TypeScript interfaces/types:
   ```typescript
   // Example structure - expand this!
   export interface BlogPost {
     slug: string;
     title: string;
     // ... full definition
   }
   
   export interface BlogPostFilters {
     tag?: string;
     category?: string;
     // ...
   }
   ```

2. **Zod Schemas** (`src/schemas/`):
   - Runtime validation for Content Collections
   - Aligned with TypeScript types (type inference)

### PHASE 3: Tests (Test-First!)
Write tests **BEFORE** implementation:

1. **Unit Tests** (`src/test/unit/`):
   - Tests for all utility functions (specs from docs/TEST_SPEC.md)
   - Tests should **fail** initially (red phase)
   ```typescript
   // example
   describe('calculateReadingTime', () => {
     it('should calculate reading time for 200 words as 1 minute', () => {
       expect(calculateReadingTime('...')).toBe(1);
     });
   });
   ```

2. **Component Tests** (`src/test/unit/components/`):
   - Testing Library for Astro components
   - According to COMPONENT_SPEC.md

3. **E2E Tests** (`src/test/e2e/`):
   - Playwright tests for user stories
   - Scenarios from TEST_SPEC.md

### PHASE 4: Implementation
Only now implement code to **pass the tests**:

1. Utilities and helpers (to pass unit tests)
2. Components (to pass component tests)
3. Pages and routing (to pass E2E tests)
4. Styling and polish

### PHASE 5: Documentation Update
After implementation, update:
- README.md with actual project state
- Add inline documentation (JSDoc)
- Architecture diagrams (if they changed)

## Tech Stack
- **Framework**: Astro (latest version)
- **Language**: TypeScript in strict mode
- **Styling**: Tailwind CSS
- **Testing**: Vitest (unit) + Playwright (E2E)
- **Content**: Markdown + Content Collections API
- **Validation**: Zod
- **Deployment**: Vercel

## Project Structure
```
├── docs/                          # START HERE!
│   ├── TECHNICAL_SPEC.md
│   ├── API_SPEC.md
│   ├── COMPONENT_SPEC.md
│   ├── TEST_SPEC.md
│   ├── USER_STORIES.md
│   └── ADR/                       # Architecture Decision Records
│       ├── 001-why-astro.md
│       ├── 002-content-strategy.md
│       └── 003-testing-approach.md
├── src/
│   ├── types/                     # Type definitions FIRST
│   ├── schemas/                   # Zod schemas
│   ├── test/                      # Tests BEFORE implementation
│   │   ├── unit/
│   │   ├── e2e/
│   │   └── fixtures/
│   ├── lib/                       # Utilities (implement after tests)
│   ├── components/                # Components (implement after tests)
│   ├── layouts/
│   ├── pages/
│   └── content/
├── .specs/                        # Generated specs artifacts
│   └── coverage-report.md         # Test coverage mapped to specs
└── README.md
```

## Required Features (Specs in USER_STORIES.md)

### Blog System
- [ ] Post list with pagination
- [ ] Single post view
- [ ] Tag system (filtering)
- [ ] Category system
- [ ] Reading time
- [ ] Table of contents
- [ ] MDX support

### UI/UX
- [ ] Dark mode (localStorage + system preference)
- [ ] Responsive design (mobile-first)
- [ ] Accessibility (WCAG 2.1 AA)
- [ ] SEO (meta, OG, sitemap, robots.txt)

### Portfolio
- [ ] About section
- [ ] Projects showcase
- [ ] Contact form/links

## Configuration & Tooling

### package.json scripts (spec-driven):
```json
{
  "scripts": {
    "spec:validate": "Check if code meets specs",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "test:e2e": "playwright test",
    "type-check": "tsc --noEmit",
    "lint": "eslint . --ext .ts,.astro",
    "format": "prettier --write .",
    "validate": "npm run type-check && npm run lint && npm run test"
  }
}
```

### Required quality tools:
- **TypeScript**: strict mode, all checks enabled
- **ESLint**: Astro + TypeScript + a11y rules
- **Prettier**: with Tailwind plugin
- **Husky + lint-staged**: validate before commit
- **Vitest**: with coverage reporting
- **Playwright**: with visual regression (optional)

## Key Spec-Driven Development Principles

1. **Specs First, Code Last**
   - No line of code without specification
   - Tests are "executable specifications"

2. **Red-Green-Refactor**
   - Red: Write a failing test (spec)
   - Green: Minimal code to pass the test
   - Refactor: Improve code while keeping tests green

3. **Living Documentation**
   - Specs = documentation
   - Update specs when requirements change
   - Tests confirm that code meets specs

4. **Traceability**
   - Every function has a spec
   - Every spec has a test
   - Every test maps to a user story

## Deliverables - Creation Order

1. ✅ Complete specs documentation (docs/)
2. ✅ TypeScript type definitions
3. ✅ Complete tests (failing)
4. ✅ Implementation (tests passing)
5. ✅ README with guide on using this workflow
6. ✅ Sample content (3-4 blog posts)

## Educational Goal

This project demonstrates:
- **Spec-Driven Development workflow** used in enterprise teams
- How specs reduce bugs and misunderstandings
- Type-safe development in TypeScript
- Test-first mentality
- Professional documentation practices
- Decision tracking (ADRs)

Code must be **production-ready** with full traceability from spec → test → implementation.

## 🎯 Special Request to Claude Code

1. **START WITH DOCS/** - create full specifications before code
2. **Show TDD cycle**: write several failing tests, then implementation
3. **Add comments** explaining spec-driven approach for a developer at 3/10 level in TypeScript
4. **Create an example ADR** (Architecture Decision Record) for a key decision
5. **Include traceability matrix**: table mapping User Stories → Tests → Implementation