assessment-model/CLAUDE.md

Claude guidance for this project

React

• Avoid useEffect and useMemo. Derive values inline, use Server Components + Route Handlers, event handlers, or useSyncExternalStore instead. If a hook is genuinely the only option, flag it and ask before using it.

Next.js 15 route handlers

• params is a Promise — type as { params: Promise<{ ... }> } and await params before destructuring.

Task tracking — Backlog.md

• Project uses Backlog.md for manual/human todos (CLI backlog, web UI on port 6420).
• MCP server is wired via .mcp.json — tools exposed under the backlog server. Use those tools instead of shelling out when possible.
• Tasks live as markdown under backlog/tasks/. Committed to git. Read them for context on outstanding manual work (env vars, IAM, infra) owed by humans.
• To start the web UI during development: backlog browser (port 6420, forwarded by devcontainer).
• Do NOT mirror Backlog.md tasks into Claude's internal todo system. Use one or the other — Backlog for durable cross-session work, internal todos for within-turn progress tracking.

Development workflow (spec-driven)

Follow this loop for all feature work:

1. Decompose — split user request into small Backlog tasks with acceptance criteria. One task = one PR = one session.
2. Plan first — before writing code, research codebase and write implementation plan inside the task. Stop and wait for user approval.
3. Implement — only after plan approved. One task at a time.
4. Verify — run tests/lint, confirm output matches acceptance criteria.

Hard rules:

• Never start coding without an approved plan in the task.
• Never work on multiple tasks in one session.
• If task too big to finish in one session, split it first.