SRA: Instructions file for Claude Code

CLAUDE.md

What this is

SRA (Smart Requirements Analyzer) — a pnpm monorepo that turns stakeholder text into requirements specs (IEEE 830, ISO 29148, Volere, Agile PRD) via a multi-agent LLM pipeline, plus a CLI that traces generated specs back to source code. Workspaces: frontend (Next.js 16), backend (Node/Express API + worker), cli (@sra-srs/sra-cli).

Commands

Package manager is pnpm. Run from repo root.

pnpm install                      # install all workspaces
pnpm run dev:all                  # backend + frontend concurrently
pnpm run lint:all                 # eslint across all workspaces (pre-commit hook)
pnpm test:all                     # backend + CLI Jest suites

# Single workspace
pnpm --filter backend test        # MOCK_AI=true, native ESM
pnpm --filter @sra-srs/sra-cli test
pnpm --filter frontend test       # vitest, jsdom

# Backend single file/name
pnpm --filter backend exec jest tests/unit/<file>
pnpm --filter backend exec jest -t "test name"

# Prisma
pnpm --filter backend exec prisma generate
pnpm --filter backend exec prisma migrate dev

Backend tests: native ESM — use jest.unstable_mockModule at the top, then await import(...). Not jest.mock. CLI tests: mock network only; file handling uses real temp dirs. Reset process.exitCode in afterAll. Frontend tests: vitest + jsdom. Don't configure a JSX transform (vitest 4/oxc handles it). Dev env flags: MOCK_AI=true skips Gemini; MOCK_QSTASH=true (or NODE_ENV=development) runs worker in-process.

Architecture rules

• routes/ → controllers/ → services/ — agents are invoked only from analysisService.js and chatService.js.
• Extend BaseAgent for new agents — retry, timeout, JSON repair live there.
• Generation config is centralized in llmGenerationConfig.js, not per-agent.
• Prompt versions live in utils/versions/ — old versions kept for reproducibility. Check which is active before editing.
• Do not call model providers directly from routes/controllers.
• Do not reintroduce the removed self-hosted model track. Provider adapters under backend/src/services/providers/ are the supported extension point.
• The sleep() between DeveloperAgent sectional calls throttles Gemini rate limits — not dead code.
• Analysis.rootId/parentId form a version tree, not mutable history.