Coding Conventions

---
name: coding-conventions
description: Workforce coding conventions — read existing patterns, prefer narrow types, leave the surface area smaller than you found it.
tags: [engineering, coding, style]
---

# Coding conventions

Generic guardrails for any agent that writes or modifies code. Load this skill when you're about to touch a codebase you don't fully own.

## Read before you write

Read the file you're about to modify. Read its callers. Read the test that covers it. The shape that already exists is the shape — match it. Don't introduce a new file layout, a new abstraction, or a new dependency just because it feels cleaner to you in isolation.

## Smallest viable change

The diff should answer the request and nothing else. If the request says "fix bug X," your diff fixes bug X — it does not also reformat the file, rename three identifiers, extract a helper, or upgrade a dependency. Each of those is a separate decision the user has not made yet.

Three similar lines beats a premature abstraction. Wait for the fourth before factoring.

## Comments

Default: don't write one. Names and types do the explaining. Add a comment only when the *why* is genuinely non-obvious — a hidden invariant, a subtle ordering constraint, a workaround for a specific upstream bug. Keep it one line. Don't explain *what* the code does; the reader can see that.

Never write multi-paragraph docstrings. Never reference the current ticket or the caller list — both rot.

## Types

Prefer narrow types over `any` / `unknown` / wide unions. Make illegal states unrepresentable when it's cheap.

When validating data crossing a boundary (HTTP, files, env vars), validate once at the boundary and trust the type inside. Don't re-validate in every internal function.

## Errors

Throw `Error` with a clear, specific message. Don't swallow. Don't wrap in `try/catch` just to log-and-rethrow.

Don't add error handling for cases that can't happen. Trust internal invariants; only validate at boundaries.

## Dependencies

Don't add a dependency for something you can write in 20 lines. Don't add a dependency that pulls in 200 transitive packages for one helper.

When you do add one, prefer the standard already in use in this repo over a "better" alternative. Consistency beats individual optimization.

## Ask before guessing

When the requirement is ambiguous, ask. Don't infer the user's intent from one example and ship the inferred behavior. A two-sentence question saves a re-do.

## Tests

A bug fix gets a test that would have caught the bug. A new feature gets at least one happy-path test. If a function has no tests today and you're adding new behavior, add the test for the new behavior — don't backfill the existing surface.

Tests live next to their code (the `test/` dir in this package, or alongside the file in others — match the local convention).