🍃 Tellia / 🥷🏿 Engineering

Appearance

Convention over Configuration ​

Popularised by Ruby on Rails, the idea is simple: sensible defaults beat explicit configuration. When a system follows predictable conventions, you only need to express what's unusual — everything else just works.

The payoff isn't just fewer lines of config. It's that the system becomes legible: to a new engineer, to a code reviewer, and to the AI agents that read and generate code in the codebase.

The pattern in this codebase ​

The property type system is the clearest example. Adding a new field type means: create the schema file, add it to two lists. The UI picker, the discriminated union, the field validator, and the AI tooling all pick it up — no further changes. The convention is the extension point.

The same logic runs throughout:

  • Queue names follow domain.action — you can infer what a queue does before opening its code
  • Every NestJS domain has a controller, a service, DTOs, a Mongoose schema — navigating a new domain is the same motion every time
  • createPropertySchema derives the type literal from .meta() — correct by construction, nothing to configure

When a new module follows these conventions, it fits. When it doesn't, it stands out immediately in review.

Why it matters ​

A predictable codebase is machine-readable. An AI agent navigating the repo doesn't need to be told where things are — it predicts the structure because the structure is consistent.

This goes beyond navigation. The workspace assistant works because every property type registers its metadata in the same place. The agent reads the convention rather than a hardcoded list in a prompt. The moment that convention breaks, the list has to be maintained manually — in the prompt, forever.

Conventions that are well-defined enough for a human to follow are well-defined enough for an AI to use.

TIP

If adding a feature requires updating more than two or three places, it's worth asking whether a convention could reduce that to one.

Further reading ​