CLAUDE.md file of each area, and those files win if anything here disagrees:
Across the codebase
- Search before you build. Before writing a helper, type, hook or service, look for one that already exists. Shared code goes in
libs/shared/pyorlibs/shared/ts, never copied between apps. - Fail loudly. Don’t swallow errors with a broad
exceptor a silent default. Let them reach a place that can handle them. - No magic values. A literal that means something becomes a named constant, grouped by domain (for example
app/constants/in the API). - Organise by feature. A feature keeps its components, hooks, types and API calls together.
- Delete what you replace. No commented-out code, no unused imports, no old versions left “just in case”.
- Comments say why, not what. Names explain what the code does. A comment is one line of reasoning at the point of surprise.
Python
- Ruff lints and formats, mypy checks types. Run
mise run lint:pyandmise run type-check. - Every function has full type annotations. Don’t add
Anyor baredict/listto a file that has none. - Imports go at the top of the file, never inside a function.
- A docstring is one imperative summary line, plus only what the signature doesn’t already say. No
Args:entry that repeats a parameter’s name or type. - Routes are thin: record what the request is about with
log.set(...), call a service, return a Pydantic model. Services are plain async functions, not classes, and reach MongoDB only through a repository inapp/db/repositories/.
TypeScript
- Biome lints and formats instead of ESLint and Prettier. Run
mise run lint, ormise run lint:fixto fix and sort imports. - Never use
any. Imports go at the top of the file. - API request and response types come from
@gaia/shared/api/generated, which is generated from the API. Never write a type that copies an API model by hand. After changing an API route or model, runmise run api:types. - UI primitives come from HeroUI:
<Button>,<Input>,<Modal>and so on, never a raw<button>or a home-made spinner. Icons come from@icons, never Unicode symbols such as arrows or check marks. - Global state uses Zustand stores.
Commits
Commit messages and pull request titles follow Conventional Commits.Next
Commit messages
The format, the allowed types and examples.

