Skip to content
Documentation

ADR-024: Engineering Standards

Decision

Every project holds the same engineering floor — small files and functions, injected dependencies, a strict TDD cycle, and Taskfile as the task runner — and organizes its documentation domain-first with exactly one canonical home per fact.

Key rules

  • File size is 150 lines or fewer; function size is 70 lines or fewer.
  • Dependencies are always injected — never new Foo() inside business logic.
  • Config comes from env vars or a config file (Go: Viper; TS: process.env parsed by Zod at startup).
  • Follow the TDD cycle: RED (write a failing test) then GREEN (make it pass) then REFACTOR.
  • Use Taskfile as the task runner — not Make, not npm scripts. Standard targets: dev, lint, test, test-cover, build.
  • Apply these standards incrementally when touching existing files — never big-bang rewrite a file to conform.
  • Apply the gut check on every change: “Would the next engineer thank me for this?”
  • Documentation is domain-primary, activity-secondary: the domain is the parent and the activity is the child — git/branch-naming, never naming/git/branch-naming.
  • A new facet of a domain becomes a new sibling file inside that domain folder — never a second competing home for the domain.
  • Cross-cutting concerns (naming, security) get one canonical home; every other page links in and never restates the content.
  • Numbered-prefix files set navigation order; a 00-overview file is a hub that points outward — it does not hold all the content.
  • A fact has exactly one canonical page; indexes aggregate links, never content.

Why

A shared floor — line limits, dependency injection, env-or-config, TDD, and one task runner — keeps every service legible and testable, so any engineer can move between repos without relearning the basics. Documentation rules apply the same single-source-of-truth discipline to prose: one canonical page per fact, domain-first folders, and link-only indexes prevent the drift that kills docs. This record consolidates the documentation taxonomy from ADR-024, which it supersedes; ADR-024’s stray storybook tag was dropped because its actual rules govern docs information architecture, not Storybook hierarchy (that lives in ADR-016). Wide-events logging stays in ADR-023 and the default stack in ADR-027, referenced rather than restated.

Applies when

You are writing new code, reviewing a PR, scaffolding a service, setting up a Taskfile, or deciding where a new documentation page lives and whether a topic earns its own folder.

  • ADR-023 — wide-events logging (referenced from the engineering checklist).
  • ADR-027 — default tech stack.
  • ADR-016 — Storybook information architecture.
  • ADR-016 — 00-prefix landing pages.
  • ADR-020 — docs IA canonical decision map.
  • ADR-017 — Storybook documentation truthfulness.