Requirements → System Design → Implementation → Integration/Testing → Operations/Maintenance

Requirements Analysis ─────────── Acceptance Testing
  System Design ─────────────── System Testing
    Architecture Design ───────── Integration Testing
      Detailed Design ───────────── Unit Testing
              Implementation (Coding)

Backlog | Ready | In Progress (WIP: 3) | Review | Done
--------|-------|----------------------|--------|------
Task 5  |Task 4 |  Task 3              |Task 2  |Task 1
Task 6  |       |  Task 7              |        |
        |       |  Task 8              |        |

As a [role], I want [feature], so that [benefit].

Write User Stories from the following business requirement:
"Customers of an online shop want product recommendations based on purchase history"

Format:
- User Story (As/I want/So that)
- Acceptance Criteria (Given/When/Then)
- Story Points estimation
- 5 potential edge cases

User Story: Personalized Product Recommendations
As a repeat customer,
I want to see product recommendations based on my purchase history on the home screen,
So that I can quickly discover products I am interested in.

Acceptance Criteria:
- Given a customer with 3+ purchases
- When they access the home screen
- Then the top 10 recommendations based on purchase history are displayed
- And each recommendation shows "why it was recommended"
- And a "not interested" button hides that recommendation

Step 1: Identify Domain Events (orange sticky notes)
→ Ask Claude: "List all domain events in the e-commerce order domain"

Step 2: Identify Commands (blue sticky notes)
→ "What commands trigger each event?"

Step 3: Identify Actors (yellow sticky notes)
→ "Who (user/system) executes each command?"

Step 4: Identify Aggregates (large yellow sticky notes)
→ "What aggregates group related events and commands?"

Step 5: Define Bounded Contexts
→ "Group aggregates into logical boundaries"

Run an Event Storming for the order processing domain.
Output format:

Domain Events (past tense):
- OrderPlaced
- PaymentProcessed
...

For each event:
1. Triggering command
2. Preconditions
3. Postconditions
4. Related aggregate

# Project Context

## Project Overview

E-commerce platform backend service (Node.js + TypeScript)

## Tech Stack

- Runtime: Node.js 20, TypeScript 5.3
- Framework: NestJS 10
- Database: PostgreSQL 16 (TypeORM), Redis 7
- Message Queue: RabbitMQ
- Testing: Jest, Supertest

## Architecture Decisions

- DDD (Domain-Driven Design)
- CQRS pattern
- Event Sourcing (Order aggregate)

## Coding Conventions

- Prefer functional programming
- Use immutable data structures
- Error handling: Result type pattern (neverthrow library)

## Forbidden Patterns

- No 'any' type usage
- Use winston logger instead of console.log
- No direct DB queries (use Repository pattern)

## Test Requirements

- Unit test coverage 90%+
- Integration tests required for all public APIs
- E2E tests: core payment flow

## Current Sprint Context

Sprint 3: Recommendation system implementation

- User Story: US-123 Purchase history-based recommendations
- Tech debt: Legacy ProductService needs refactoring

# ADR-001: Database Selection

## Status

Approved (2026-03-17)

## Context

A database is needed for the recommendation system.
Requirements:

- Handle 10,000 read requests per second
- Graph queries between products
- Real-time updates

## Decision

Select PostgreSQL + pgvector extension

## Alternatives

1. MongoDB: Flexible schema but weak at complex relationship queries
2. Neo4j: Graph DB but team lacks experience, operational complexity
3. Redis + PostgreSQL: Added caching layer for performance

## Consequences

- Positive: pgvector enables vector similarity search
- Positive: Leverages team's PostgreSQL experience
- Negative: Performance limits with very large graph queries
- Negative: Learning required for pgvector setup and indexing

Write an ADR for our message queue selection.
Requirements:
- Process 50,000 messages per second
- At-least-once delivery guarantee
- Message reprocessing capability
- Team size: 5 people

Candidates: Kafka, RabbitMQ, AWS SQS
Recommend the optimal choice for our situation with pros/cons of each.

Review the following class diagram:
[paste diagram]

Check for:

1. SOLID principle violations
2. Circular dependencies
3. Interface segregation opportunities
4. Aggregate boundary appropriateness from DDD perspective
5. Improvement suggestions

1. Explain requirements to Claude
2. Claude generates failing test code
3. Developer reviews and adjusts tests
4. Claude generates minimal implementation to pass tests
5. Developer and Claude refactor together

// Step 1: Failing tests generated by Claude
describe('RecommendationService', () => {
  describe('getPersonalizedRecommendations', () => {
    it('should return top 10 recommendations based on purchase history', async () => {
      // Arrange
      const userId = 'user-123'
      const purchaseHistory = [
        { productId: 'prod-1', category: 'Electronics', purchasedAt: new Date() },
        { productId: 'prod-2', category: 'Electronics', purchasedAt: new Date() },
      ]
      mockPurchaseRepository.findByUserId.mockResolvedValue(purchaseHistory)
      mockProductRepository.findSimilar.mockResolvedValue(generateMockProducts(15))

      // Act
      const result = await service.getPersonalizedRecommendations(userId)

      // Assert
      expect(result).toHaveLength(10)
      expect(result[0]).toMatchObject({
        productId: expect.any(String),
        score: expect.any(Number),
        reason: expect.any(String),
      })
      expect(mockPurchaseRepository.findByUserId).toHaveBeenCalledWith(userId)
    })

    it('should return popular products when no purchase history exists', async () => {
      mockPurchaseRepository.findByUserId.mockResolvedValue([])
      mockProductRepository.findPopular.mockResolvedValue(generateMockProducts(10))

      const result = await service.getPersonalizedRecommendations('new-user')

      expect(result).toHaveLength(10)
      expect(mockProductRepository.findPopular).toHaveBeenCalled()
    })

    it('should exclude already purchased products from recommendations', async () => {
      const purchasedProductId = 'prod-already-bought'
      mockPurchaseRepository.findByUserId.mockResolvedValue([
        { productId: purchasedProductId, category: 'Books' },
      ])
      const recommendations = generateMockProducts(12)
      recommendations[0].productId = purchasedProductId
      mockProductRepository.findSimilar.mockResolvedValue(recommendations)

      const result = await service.getPersonalizedRecommendations('user-123')

      expect(result.map((r) => r.productId)).not.toContain(purchasedProductId)
    })
  })
})

Review the following PR:
[paste code]

Review criteria:

1. Bugs and edge cases
2. Performance issues (N+1 queries, memory leaks)
3. Security vulnerabilities (SQL injection, XSS, auth/authz)
4. Coding conventions (per CLAUDE.md)
5. Test coverage
6. Readability and maintainability

For each issue:

- Severity: Critical/Major/Minor
- Improved code example
- Explanation of why

Generate comprehensive test cases for the following function:

function calculateShippingFee(weight: number, distance: number, isPremium: boolean): number

Business rules:

- Weight 0-1kg: base fee $3
- Weight 1-5kg: add $0.50/kg
- Weight over 5kg: 20% surcharge on total
- Distance over 100km: add $1
- Premium member: 10% discount
- Free shipping: premium + under 10kg

When generating test cases:

- Apply boundary value analysis
- Identify equivalence partition classes
- Include negatives, zero, extreme values
- Include compound condition tests
- Write in Jest format

{
  "mutate": ["src/**/*.ts", "!src/**/*.spec.ts"],
  "testRunner": "jest",
  "reporters": ["html", "clear-text", "progress"],
  "thresholds": {
    "high": 80,
    "low": 60,
    "break": 50
  }
}

Analyze the following mutation testing results and add tests to kill surviving mutants:

Surviving mutants:
1. Line 45: Changed '>' to '>=' — tests did not detect
2. Line 72: Changed '&&' to '||' — tests did not detect

Current test code:
[paste test code]

import fc from 'fast-check'

describe('ShippingFee property-based tests', () => {
  it('premium members always pay less than or equal to regular members', () => {
    fc.assert(
      fc.property(
        fc.float({ min: 0.1, max: 100 }),
        fc.integer({ min: 1, max: 1000 }),
        (weight, distance) => {
          const regularFee = calculateShippingFee(weight, distance, false)
          const premiumFee = calculateShippingFee(weight, distance, true)
          return premiumFee <= regularFee
        }
      )
    )
  })

  it('shipping fee is always non-negative', () => {
    fc.assert(
      fc.property(
        fc.float({ min: 0, max: 1000 }),
        fc.integer({ min: 0, max: 10000 }),
        fc.boolean(),
        (weight, distance, isPremium) => {
          return calculateShippingFee(weight, distance, isPremium) >= 0
        }
      )
    )
  })
})

# ProjectName — Claude Context File

## Project Overview

- Purpose: [one sentence]
- Stage: [MVP/Beta/Production]
- Team size: [n people]
- Domain: [e-commerce/fintech/healthcare etc.]

## Tech Stack

### Backend

- Language: TypeScript 5.3 (strict mode)
- Runtime: Node.js 20 LTS
- Framework: NestJS 10
- ORM: TypeORM 0.3
- Database: PostgreSQL 16

### Frontend

- Framework: Next.js 14 (App Router)
- Styling: Tailwind CSS 3.4
- State: Zustand 4

### Infrastructure

- Container: Docker + Kubernetes
- CI/CD: GitHub Actions
- Cloud: AWS (EKS, RDS, ElastiCache)

## Architecture

- Pattern: DDD + CQRS + Event Sourcing
- Service separation: Modular monolith
- API: REST + WebSocket (real-time notifications)

## Coding Rules

### Must Follow

- TypeScript strict mode: no 'any' type ever
- Function length: keep under 30 lines
- Nesting depth: 3 levels max
- Error handling: Result pattern (neverthrow)
- Logging: winston logger (no console.log)

### Naming Conventions

- Classes: PascalCase
- Functions/variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Files: kebab-case.ts
- Test files: \*.spec.ts

## Test Strategy

- Unit tests: Domain logic (90% coverage)
- Integration tests: API endpoints (80% coverage)
- E2E: 3 core business flows
- Mutation testing: mutant survival rate under 20%

## Current Sprint Context

Sprint 3 (2026-03-10 to 2026-03-24)
Goal: Recommendation system v1 launch

In progress:

- US-123: Purchase history recommendation API
- US-124: Real-time recommendation updates via WebSocket

Technical debt:

- Legacy ProductService refactoring needed
- UserRepository test coverage improvement needed

## Forbidden Patterns

- Direct SQL queries (use Repository pattern)
- Synchronous file I/O (fs.readFileSync etc.)
- Hardcoded secrets (use environment variables)
- Indiscriminate try-catch (specify error types)

# Step 1: Create project
npx create-next-app@latest my-shop --typescript --tailwind --app

# Step 2: Create CLAUDE.md (first Claude prompt)

Starting a Next.js 14 App Router-based e-commerce project.
Generate CLAUDE.md with these requirements:

- Product listing, detail, cart, checkout features
- TypeScript strict mode
- Tailwind CSS + shadcn/ui
- Zustand state management
- React Query v5 for server state
- Prisma + PostgreSQL
- NextAuth.js authentication
- Vitest + Testing Library

Team conventions:
- Components: atomic design with shadcn/ui base
- Server components by default, minimize client components
- Error boundary + Suspense patterns

US-001: Add Product to Cart
As a shopper
I want to add a product to my cart from the product detail page
So that I can purchase multiple items at once later

Acceptance Criteria:
- Given I am on a product detail page
- When I click "Add to Cart"
- Then the product with selected options and quantity is added to cart
- And the cart icon updates with the new count
- And if already in cart, quantity is incremented

Implement the above User Story.

Technical requirements:
- Add cartSlice to Zustand store
- Server Action for cart server sync
- Apply Optimistic Update
- Real-time inventory check (useQuery)
- Error handling: out of stock, network error
- Animation: cart icon bounce effect

File structure:
- store/cartStore.ts
- components/product/AddToCartButton.tsx
- app/actions/cart.ts
- hooks/useCart.ts

Write tests for the above implementation:
1. cartStore unit tests (Vitest)
2. AddToCartButton component tests (Testing Library)
3. cart Server Action integration tests
4. Property-based tests (inventory constraints)