CLAUDE.md - BMAD v6 Project Memory

Project Identity

Project Name: [Your Project Name] Tech Stack: Node.js 20+, Express, TypeScript, PostgreSQL, Jest Status: Active Development Last Updated: 2026-01-11

🎯 BMAD Agents & Their Roles (Never Deviate)

Phase 1: Planning (Agentic Planning)

These agents create the PRD and Architecture documents:

Analyst Agent (/analyst)
- INPUT: User brief, business goals
- OUTPUT: docs/prd.md (complete product requirements)
- Role: Deep requirements analysis, user stories gathering
PM Agent (/pm)
- INPUT: PRD from Analyst
- OUTPUT: Epic backlog + prioritized stories
- Role: Refine PRD, create backlog for SM
Architect Agent (/architect)
- INPUT: PRD + tech preferences
- OUTPUT: docs/architecture.md (system design, ADRs, constraints)
- Role: Technical decisions, architecture patterns, tech stack alignment

Phase 2: Development (Context-Engineered Development)

These agents consume Story Files (created by SM):

Scrum Master Agent (/sm)
- INPUT: Backlog from PM + Architecture from Architect
- OUTPUT: docs/stories/X.Y.story-name.md (implementation-ready)
- CRITICAL: SM embeds full context into each story:
  - Architecture Decision References (ADRs)
  - Acceptance Criteria (exact, testable)
  - Implementation Guidance
  - Dependencies & testing requirements
- Role: Create stories that Dev agent can execute with zero ambiguity
Dev Agent (/dev)
- INPUT: A single Story File + referenced Architecture
- OUTPUT: Code implementation + tests + PR
- CRITICAL: Dev agent should ONLY read:
  1. The current story file (reference with @docs/stories/X.Y.story-name.md)
  2. Architecture from docs/architecture.md (or specific ADR)
  3. Tech Stack patterns from /src code
- Role: Execute, don't invent
QA Agent (/qa)
- INPUT: Dev's implementation + story file
- OUTPUT: Validation checklist, defect list or verification
- Role: Validate against acceptance criteria

📂 Context Locations (Where Each Agent Reads/Writes)

Agent Reads

Agent	Reads From	Purpose
Analyst	Business brief (input by you)	Understand requirements
PM	Analyst's PRD	Create backlog
Architect	PRD + tech preferences	Design system
SM	Backlog + Architecture + code patterns	Create story specs
Dev	Story file + Architecture refs	Implement feature
QA	Story file + Dev output	Validate

Agent Writes

Agent	Writes To	Format
Analyst	`docs/prd.md`	Markdown
PM	Backlog (in chat or `docs/epics.md`)	Markdown
Architect	`docs/architecture.md`	Markdown (with ADR sections)
SM	`docs/stories/X.Y.description.md`	Markdown (detailed specs)
Dev	`src/`, `tests/`	Code + Test files
QA	Validation in chat + update story status	Markdown checklist

🏗️ Architecture Constraints (MUST NOT BREAK)

These are decided once, NEVER change mid-project without team review:

API Design Pattern

Gateway Pattern: Single entry point (/api)
Routes: RESTful /api/v1/[resource]/[action]
Authentication: JWT at Gateway level (not per-route)
Error responses: Standardized JSON with code, message, details

Database Layer

ORM: Prisma (never raw SQL)
Migrations: One per feature, committed to git
Schema: Timestamps (createdAt, updatedAt) on all tables
Transactions: Always wrap multi-step operations

Async Processing

Queue Library: Bull
Message Broker: Redis
Pattern: Email sends, notifications, heavy computation → queued
Retry policy: 3 attempts, exponential backoff

Authentication & Security

Password hashing: bcrypt (library: bcryptjs)
JWT signing key: Stored in .env, never in code
CORS: Whitelist explicit domains
Rate limiting: 100 req/minute per IP

Testing

Framework: Jest
Coverage minimum: 80%
Tests near code: *.test.ts in same folder as source
Test data: Use fixtures in tests/fixtures/

Code Style

Language: TypeScript (strict mode always)
Linter: ESLint + Prettier
Commit format: feat(module): description or fix(module): description
Branch strategy: Feature branches only, PR + review before merge

📝 Story File Structure (How SM Formats Each Story)

When SM creates a story, it MUST include ALL of this (Dev relies on it):

# Story X.Y: [Feature Name]

## Objective
[One sentence: What we're building and why]

## Acceptance Criteria (Gherkin Format)
Given [context]
When [action]
Then [result]

[Repeat for each criterion]

## Architecture References
- See: docs/architecture.md → "API Design Pattern" section
- See: docs/architecture.md → "Authentication" ADR
- Pattern used: [Specific pattern name]

## Implementation Guidance
- Files to create: [list]
- Files to modify: [list]
- Patterns to follow: [reference code examples]
- Tests required: [specific test cases]

## Dependencies
- Depends on: Story X.Y (must be DONE first)
- Blocks: Story X.Z (cannot start until this is merged)

## Definition of Done
- [ ] Code passes linter (ESLint)
- [ ] Tests written & passing (Jest, >80% for this file)
- [ ] Database migration added (if needed)
- [ ] Story status updated in docs/stories/
- [ ] PR created with reference to this story

5.3 KiB Raw Blame History