Skip to content

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:

bash
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, not F4). 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:

ts
/**
 * 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:

ts
// 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

ThingStyleExample
Tablesplural snake_casedocument_chunks
Columns / TS fieldssnake_case / camelCaseorganization_id / organizationId
Fileskebab-case, Nest suffixes kepttenant-context.service.ts
Types, classesPascalCaseTenantContextService
Error codesSCREAMING_SNAKE, stable (they are API)SEAT_LIMIT_REACHED

Prettier and ESLint settle formatting; formatting is not argued in review.

Get started free — 50 credits a month