Self-documenting
A wiki page goes stale. A comment drifts. A type cannot lie.
The goal is code that explains itself — where reading the codebase answers the question, rather than hunting down whoever wrote it.
Examples
Types as specification
TypeScript strict mode is on across the monorepo. The function signature tells you what goes in and what comes out. If it compiles, the contract holds. The compiler is a better spec than a README.
Schemas as the source of truth
Every domain object's shape is declared in packages/schemas. Frontend, backend, and AI tooling all read from the same definition. You don't need to run the app or read a Notion page to know what a workspace record looks like — you open the schema. → Schemas & Records
Module declarations
A NestJS module's imports, providers, and exports list its dependencies explicitly. Reading WorkspaceModule tells you everything it needs and everything it exposes, with no hidden coupling.
Naming things
Names are documentation. A queue named audio.transcribe tells you more than queue3. A file named company-auth.guard.ts tells you its role before you open it.
This is worth thinking about when adding something new. Should this follow an existing pattern? Does the name make the intent clear without a comment? If the name requires explanation, the name is probably wrong. → Convention over Configuration
Where the line is
Types document what. Comments document why — the non-obvious decision, the workaround, the constraint that isn't obvious from the code. If a comment restates what the type already says, delete it.
External documentation (this site) covers onboarding, architecture decisions, and cross-cutting guides. It should never be the primary reference for what a function accepts or what a module does.
TIP
A self-documenting codebase is also machine-readable. AI agents navigating the repo don't need to be told where things are or what they do — they infer it from types, schema declarations, and consistent naming. Every shortcut that obscures intent (loose types, ambiguous names, undeclared dependencies) makes the AI less effective, not just the next human engineer.
TIP
If you find yourself writing a comment to explain what a piece of code does, consider whether a better name or a more precise type would make the comment unnecessary.
CAUTION
AI-generated code that lacks types, uses any, or ignores the shared schema package adds hidden knowledge — it makes the next engineer's job harder and breaks the machine-readability that the rest of the codebase depends on.