code-standards

Code Standards

Language-agnostic defaults. Language-specific skills override where they conflict. These are the Chef's taste stated as directives: apply them as written, and do not substitute your own or your provider's defaults where they differ.

Core Philosophy

• Modular: small, focused, reusable components.
• Functional first: pure functions, immutability, composition. A house choice, not a suggestion.
• Maintainable: self-documenting, testable, predictable.
• Single source of truth: one authoritative owner per fact; no drifting duplicates.
• Separate by rate of change: don't weld a fast-changing concern into a slow-changing one; couple the layers loosely so each moves at its own pace.
• Docs are part of the system: incorrect documentation is a bug. When a change alters docs that describe the system's behavior, verify them against the code as it stands, not just for prose. (OpenBSD.)

Golden Rule: If you can't easily test it, refactor it.

Laziness (the YAGNI ladder)

The best code is the code you never wrote. Before writing any, stop at the first rung that holds:

1. Does this need to exist? Speculative need = skip it, say so in one line.
2. Stdlib does it? Use it.
3. Native platform feature covers it? (<input type="date"> over a picker lib; a DB constraint over app code.) Use it.
4. An already-installed dependency solves it? Use it. Never add one for what a few lines do.
5. One line? One line.
6. Only then: the minimum code that works.

• Order speed after subtraction: Accelerate only after the design is validated as minimal or to remove an observed bottleneck; automate only a stable, understood process with understood failure modes and deterministic verification signals. Neither may trade away safety, accessibility, data protection, rollback, or verification.

• Question every addition, including your own and the system's own docs and process: "do you need X, or does Y already cover it?" The lazy lens applies hardest to your own work, not just to feature code; ceremony, prose, and citations are over-build too.

• Lazy means less code, not the flimsier choice: when two correct approaches are the same size, take the more edge-case-correct one.

• No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.

• Deletion over addition. Boring over clever. Fewest files, shortest working diff.

• Mark a deliberate shortcut with a kiss: comment naming its ceiling and upgrade path (# kiss: O(n^2) scan, index it if the list grows). Simple should read as intent, not ignorance.

• Laziness governs the process too, but selectively; this is the harder cut. Separate the function a step protects from the ceremony that only resembles it. To drop a step, name the outcome it protects and show that outcome is covered elsewhere or no longer at risk. If you can't name it, it's load-bearing: keep it. (See skills/code-standards/reference/load-bearing-vs-liturgy.md for the test and worked examples.)

• Never cut the steering or the safety carve-outs. Validation at trust boundaries, error handling that prevents data loss, and security; plus the verification that stops you declaring done when it isn't: tests with meaningful coverage (they steer you and catch a premature "done"), independent review, the done-gate. For an agent this is asymmetric: completion bias pushes you to cut the steering and keep the ritual, so weight against both.