164 lines
5.3 KiB
Markdown
164 lines
5.3 KiB
Markdown
# 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):
|
|
|
|
```markdown
|
|
# 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
|