pragma-stack: Instructions file for Claude Code

CLAUDE.md

Claude Code context for FastAPI + Next.js Full-Stack Template.

See AGENTS.md for project context, architecture, and development commands.

Claude Code-Specific Guidance

Critical User Preferences

File Operations - NEVER Use Heredoc/Cat Append

ALWAYS use Read/Write/Edit tools instead of cat >> file << EOF commands.

This triggers manual approval dialogs and disrupts workflow.

# WRONG ❌
cat >> file.txt << EOF
content
EOF

# CORRECT ✅ - Use Read, then Write tools

Work Style

• User prefers autonomous operation without frequent interruptions
• Ask for batch permissions upfront for long work sessions
• Work independently, document decisions clearly
• Only use emojis if the user explicitly requests it

When Working with This Stack

Dependency Management:

• Backend uses uv (modern Python package manager), not pip
• Always use uv run prefix: IS_TEST=True uv run pytest
• Or use Makefile commands: make test, make install-dev
• Add dependencies: uv add <package> or uv add --dev <package>

Database Migrations:

• Use the migrate.py helper script, not Alembic directly
• Generate + apply: python migrate.py auto "message"
• Never commit migrations without testing them first
• Check current state: python migrate.py current

Frontend API Client Generation:

• Run bun run generate:api after backend schema changes
• Client is auto-generated from OpenAPI spec
• Located in frontend/src/lib/api/generated/
• NEVER manually edit generated files

Testing Commands:

• Backend unit/integration: IS_TEST=True uv run pytest (always prefix with IS_TEST=True)
• Backend E2E (requires Docker): make test-e2e
• Frontend unit: bun run test
• Frontend E2E: bun run test:e2e
• Use make test or make test-cov in backend for convenience

Security & Quality Commands (Backend):

• make validate — lint + format + type checks
• make audit — dependency vulnerabilities + license compliance
• make validate-all — quality + security checks
• make check — full pipeline: quality + security + tests