Working conventions
The gate, feature codes, recorded decisions, and comments that explain why.
On this page
These rules come from CLAUDE.md, which is identical in both repositories. Code cites it by section (CLAUDE.md §5), and the section numbers never change.
The gate
Before every commit, in every repository you touched:
pnpm typecheck && pnpm lint && pnpm test
All three pass. Not "they will pass after the next commit".
Features have permanent codes
Work is organised as numbered features, F01 upward, listed in ikazebot-server/docs/ROADMAP.md with their status.
- One feature is one branch, one pull request and one deployable increment.
- Codes are permanent and always two digits (
F04, notF4). They are cited in comments, migration names and commit messages, so a line of code can be traced to the feature that wanted it. - Do not build the next feature early. If something depends on unbuilt work, make the gap loud: throw an error naming the feature that owns it. Silent stubs become production bugs.
Decisions are recorded in the code
When the maintainer answers a design question, write the answer next to the code it constrains, in the form already used:
/**
* A workspace's credits. The allowance is spent first and expires at `periodEnd`; granted credits
* do not expire (F15, answer 3).
*/
The two forms are F15, answer 3 (an answer to a feature's numbered design question) and Decided with the maintainer, F03, 2026-09-17.
A decision that only lives in a chat will be reversed by the next person who does not know about it.
Comments explain why, not what
This codebase documents its reasoning: the trap avoided, the alternative rejected. Match it:
// Bad: restates the code.
// Set the tenant id.
// Good: records the trap (from tenant-context.service.ts, abridged).
// Why set_config and not SET LOCAL: Postgres does not accept bind parameters in SET,
// and interpolating the tenant id into SQL would be an injection hole aimed at the
// value the whole isolation model depends on. is_local = true makes it act like
// SET LOCAL: it is discarded when the transaction ends.
One definition, one place
Roles, permissions, plan limits, error codes, the model catalog and credit multipliers each have exactly one home, such as shared/roles.ts, auth/ability.factory.ts and shared/plans.schema.ts. A value copied into a second file will drift. (The deliberate exception is the mirrored contracts, which are copied verbatim.)
Honest data
- Never invent data. No seeded customers that look real, and no placeholder metrics shown as if measured. If something is not measured yet, the UI says so.
- Test fixtures announce themselves. Names start
ikazebot-rls-test …, and emails use@example.invalid, which can never be a real mailbox. - Report results as they are. A failing test is reported failing, with its output.
Naming
| Thing | Style | Example |
|---|---|---|
| Tables | plural snake_case | document_chunks |
| Columns / TS fields | snake_case / camelCase | organization_id / organizationId |
| Files | kebab-case, Nest suffixes kept | tenant-context.service.ts |
| Types, classes | PascalCase | TenantContextService |
| Error codes | SCREAMING_SNAKE, stable (they are API) | SEAT_LIMIT_REACHED |
Prettier and ESLint settle formatting; formatting is not argued in review.