coding-best-practiceslisted

# Coding Best Practices Universal rules for all developer agents. Language-specific guidance lives in each agent's own instructions. ## Workflow Discipline Steps 3-5 of every developer workflow (after build environment and prior art check): 3. **TDD — tests first**: define test scenarios (including edge cases and error paths) BEFORE implementation; write test stubs/cases first, then implement to make them pass. - **Assert the contract, not the code**: tests assert intended behavior (name/docs/spec), never merely restate what the code currently does — a test that passes only by mirroring current behavior is tautological and locks in bugs. - **Repro tests go RED first**: a regression/repro test for a known bug must assert the correct/documented behavior and be confirmed FAILING against the buggy code, THEN fixed to green. Green-from-the-start proves nothing. - **A mismatch is a bug**: behavior disagreeing with its name/docs/spec is itself a defect (code bug or doc bug) — never silently accept it or codify the wrong side in a passing test. Resolve which side is correct, fix it, test the correct side. 4. **Implement**: write the production code to satisfy the tests. 5. **Self-review**: before considering code complete, check correctness, edge cases, naming, error handling, and adherence to the architectural design. ## Code Quality Tool Timing Run formatting, linting, and tests only right before committing (or when the user explicitly asks) — not after every edit; t