coder-system-design-testable-code

<when_to_use> Designing modules, services, or boundaries that must stay easy to test Refactoring hard-to-test legacy code paths Establishing test strategy for new architecture components </when_to_use>

<input_requirements> Critical business paths and failure modes Current test stack and CI constraints External dependencies and integration boundaries Determinism risks (time, randomness, concurrency, network) </input_requirements>

<design_principles> Use dependency inversion and dependency injection for replaceable collaborators Create explicit seams at IO, time, random, and external service boundaries Favor deterministic execution in tests with controllable clocks and inputs Prefer many fast unit and component tests with targeted integration coverage Use contract tests for service boundaries to prevent integration drift Make failures diagnosable with structured test logs and trace correlation </design_principles>

<testability_checklist> Business logic can run without network or real infrastructure in core tests External calls are abstracted through interfaces/ports Tests do not depend on execution order or shared mutable state Flaky signals are tracked and have explicit remediation ownership Boundary contracts are validated in CI before deployment </testability_checklist>

<quality_rules> No critical change is complete without tests that prove behavior No unstable test should be silently ignored; quarantine requires owner and timeline No hidden dependency should bypass injection seam on critical path No long-running broad test should replace missing fast deterministic tests </quality_rules>

<do_not> Do not hardcode infrastructure clients in business logic Do not use sleep-based timing guesses when deterministic sync is possible Do not over-mock internals instead of validating behavior contracts Do not hide flaky failures by indiscriminate retries </do_not>

<output_requirements> Design boundaries and seams introduced or validated Test strategy per layer (unit/component/integration/contract) Determinism controls and flaky-risk mitigation Evidence from CI/local checks and remaining risks </output_requirements>