# CLAUDE.md

> Context for Claude Code sessions in {{ project_name }}.

## Project

{{ project_name }} is a Prism-generated application. The spec drives all code generation — modify the spec, not the generated code.

Always prefix commands with `uv run` (e.g., `uv run prismegenerate`).

## Commands

```bash
uv run prismevalidate specs/models.py   # Validate spec
uv run prismegenerate --dry-run         # Preview changes
uv run prismegenerate                   # Generate code from spec
uv run prismedb migrate                 # Apply database migrations
uv run prismedev                        # Start dev servers
uv run prismetest                       # Run tests
uv run prismecheck                      # Verify project consistency
uv run prismereview list                # Check override status
```

## Session Start

At the start of every session, run these to understand project state:

```bash
uv run prismevalidate specs/models.py
uv run prismereview list
```

## Generated Directories (DO NOT EDIT)

These are regenerated on every `prisme generate` — your changes will be lost:

{% if database == "postgresql" %}- `packages/backend/src/{{ project_name_snake }}/schemas/` — Pydantic request/response schemas
- `packages/backend/src/{{ project_name_snake }}/services/_generated/` — Base service classes
- `packages/backend/src/{{ project_name_snake }}/api/rest/_generated/` — Base REST routes
- `packages/backend/src/{{ project_name_snake }}/api/graphql/_generated/` — GraphQL types/queries/mutations
{% else %}- `src/{{ project_name_snake }}/schemas/` — Pydantic request/response schemas
- `src/{{ project_name_snake }}/services/_generated/` — Base service classes
- `src/{{ project_name_snake }}/api/rest/_generated/` — Base REST routes
{% endif %}{% if database == "postgresql" %}- `packages/frontend/src/types/generated.ts` — TypeScript types
- `packages/frontend/src/components/_generated/` — Base UI components
{% endif %}
## Extension Points (SAFE TO EDIT)

These files are created once and never overwritten:

{% if database == "postgresql" %}- `packages/backend/src/{{ project_name_snake }}/services/*_service.py` — Extend the base class
- `packages/backend/src/{{ project_name_snake }}/extensions/routers.py` — Custom REST endpoints
- `packages/backend/src/{{ project_name_snake }}/extensions/dependencies.py` — Custom dependencies
- `packages/backend/src/{{ project_name_snake }}/extensions/events.py` — Lifecycle hooks
- `packages/backend/src/{{ project_name_snake }}/extensions/policies.py` — Authorization policies
{% else %}- `src/{{ project_name_snake }}/services/*_service.py` — Extend the base class
- `src/{{ project_name_snake }}/extensions/routers.py` — Custom REST endpoints
- `src/{{ project_name_snake }}/extensions/dependencies.py` — Custom dependencies
- `src/{{ project_name_snake }}/extensions/events.py` — Lifecycle hooks
- `src/{{ project_name_snake }}/extensions/policies.py` — Authorization policies
{% endif %}{% if database == "postgresql" %}- `packages/frontend/src/components/<Model>*.tsx` — Wrap generated base components
- `packages/frontend/src/pages/*.tsx` — Page-level customizations
- `packages/frontend/src/hooks/*.ts` — Data-fetching hooks
{% endif %}
## Protected Regions

Code between `PRISM:PROTECTED:START` and `PRISM:PROTECTED:END` markers is preserved during regeneration. Use these for inline customizations in generated files:

```python
# PRISM:PROTECTED:START - Custom Imports
from mylib import helper
# PRISM:PROTECTED:END
```

## Workflow

1. **To add/change models or fields** — edit `specs/models.py`, then `uv run prismegenerate && uv run prismedb migrate`
2. **To customize behavior** — edit extension files (services, routers), not `_generated/` files
3. **To add inline customizations** — use `PRISM:PROTECTED` regions in generated files
4. **After any change** — run `uv run prismetest` to verify
