# Coding Standards Rules for working with source code. Explicit project instructions and established repository conventions take precedence. Skip rules that do not apply to the language at hand. ## Context first - Search for existing functionality before implementing new helpers or utilities; Reuse or extend suitable existing code. - Obtain confirmation before making destructive or irreversible operations to existing work; A push needs confirmation, a local commit does not. - When explaining or referring to existing code, always support factual claims with `path:line` references. ## Scope & Changes - Make the smallest change that satisfies the request; Avoid unrelated modifications. - Preserve behavior outside the requested change, including existing edge cases. - Separate structural refactoring from behavioral changes: When both are needed, make the structural change first where practical and keep the two in separate commits. - Remove code rendered obsolete by a change, but do not perform unrelated cleanup. - Commit locally in small, self-contained steps; each commit must pass the checks. ## Design & Clarity - Give each function, class, and module one cohesive responsibility. - Order *new* code you write top-down: public and high-level functions first, the helpers they call below them. Where the language requires definition before use, follow the language. - Extract a named function when a block could use a comment to explain what it does, or has more lines than can be grasped quickly. - Extract conditionals with Boolean logic into functions with domain-specific names to make them easier to understand. - Prefer explicit control flow and guard clauses over clever expressions and deep nesting. - Encapsulate implementation details behind minimal interfaces at meaningful boundaries. - Keep business logic free of direct infrastructure, I/O, and framework calls, ideally at module level. - Keep business logic in modules that import no infrastructure, I/O, or framework code. Dependencies point inward: outer layers (transport, persistence, UI) depend on the domain, never the reverse. - When business logic needs an external capability, define the interface in the domain and implement it in an outer layer. - Avoid `any`, unchecked casts, and type-checker suppressions; when one is unavoidable, state the reason in an adjacent comment. - Introduce abstractions only when they solve a concrete, present problem. - Briefly report code you touched that violates these principles; do not fix it unasked. ## Correctness & Testing - Annotate public function signatures and exported declarations with types; rely on inference for local variables. - Test observable behavior through public interfaces rather than implementation details. - Do not call, patch, or assert on private members in tests, and do not widen visibility to make something testable. - Add or update focused tests for changed behavior and relevant edge cases. If testing is infeasible, report why. - Never weaken, skip, or remove tests merely to make checks pass; Update obsolete tests when requirements change. ## Errors & Observability - Never silently discard errors or add fallbacks that conceal failures. - Handle expected failures explicitly; catch specific exceptions where recovery, translation, or contextual reporting is possible. - Define custom exception types for domain-specific failures; use built-in types for argument and programming errors. When wrapping an error, preserve the original cause. - Log events that cannot be reconstructed from code and inputs: external calls and queries, state changes, consequential runtime decisions, and handled errors. - Log each error once, where it is handled, with enough context to act on. - Never log secrets or personal data. - Follow the project's existing logging conventions; where none exist, use structured logging (key-value fields, not interpolated strings). - If the project uses tracing, instrument new external calls and request handlers consistently. - For short stand-alone scripts, plain output to stdout and stderr is sufficient. ## Dependencies & Imports - Use the standard library or existing dependencies when sufficient. - Add external dependencies only when they provide a concrete benefit that outweighs implementation and maintenance costs. - Place imports at file scope. Use local imports only for a technical reason (circular, optional, or deferred dependencies) and note the reason beside the import. - Always report if you added a new dependency, explaining the rationale. ## Verification & Checks - Before a commit, run all unit tests, the linter, and type checker. - If checks fail, investigate whether the changes caused the failure; Do not modify unrelated code solely to make checks pass. - Report which checks passed, failed, or could not be run; Never claim verification that was not performed.