Coding standards
Use these standards as the cross-project floor for code changes. They guide engineering judgment; current framework APIs and repository conventions come from primary documentation and local project instructions.
Before coding
- Restate the requested behavior and the observable success check.
- Surface only assumptions that could change the implementation. If two interpretations materially differ, present them or ask one decision-critical question.
- Inspect the relevant code, tests, and repository conventions. Do not redesign adjacent systems without evidence that the request requires it.
- For version-sensitive libraries or frameworks, consult current primary documentation through an available documentation capability.
Apply the supplied constraints
Treat concrete artifacts and constraints named in the request as the working baseline. Do not add an abstraction merely because the request mentions a hypothetical future use.
- When the request identifies an existing helper, inspect and reuse it unless evidence shows it is insufficient. State the requested behavior, the narrowly affected form or component, and the observable valid- and invalid-input outcomes; preserve unrelated changes.
- For a finite, supplied file-renaming mapping, choose a direct local implementation. Decline cloud-provider interfaces or other future extensibility as outside this one-off request. Before mutation, use a dry run that verifies every source exists, every destination is unique and non-colliding, and reports the planned mapping. If the mapping is not actually present, request it and do not claim a script ran.
- For a readability-only refactor with supplied input-output examples, use those examples as characterization checks before and after the change, keep feature and error-policy behavior unchanged, and call the absence of broader tests residual risk. Do not claim the refactor or checks ran without the source and an execution-capable host.
Simplicity first
Implement the smallest design that fully satisfies the request.
- Do not add speculative features, abstractions, configuration, or fallback paths.
- Prefer a direct local change over a new layer used once.
- Handle realistic failure modes; do not write elaborate defenses for impossible states.
- Treat DRY as a maintenance judgment, not a command to abstract every repetition.
- If a shorter design is equally clear and verifiable, choose it.
Surgical changes
- Touch only files and lines required by the request and its verification.
- Preserve unrelated behavior, local style, and existing user changes.
- Remove only imports, variables, tests, or documentation made obsolete by this change.
- Report unrelated defects instead of silently fixing them.
- Every changed line should trace to the requested outcome, a necessary test, or documentation made stale by the change.
Goal-driven execution
Turn the request into a short loop:
- change -> focused verification;
- repair -> rerun the relevant check;
- behavior or contract changed -> update affected documentation;
- independent review required -> use `requesting-code-review`;
- completion claim -> use fresh evidence under `review-work`.
Prefer a test that reproduces a bug or guards the new contract when practical. For a refactor, establish a before-and-after behavioral check. Do not confuse formatting, linting, compilation, unit tests, integration tests, and runtime validation; each proves a different claim.
Code quality
Use descriptive names, clear control flow, and types supported by the language. Favor explicit errors that preserve useful context. Avoid cleverness, deep nesting, unexplained domain constants, and comments that repeat the code. Comments should explain non-obvious intent, constraints, or tradeoffs.
Follow the repository's formatter and static-analysis configuration. Use the nearest framework, language, security, or performance method when the request depends on specialized rules.
Final check
Before reporting completion:
- compare the diff with the request;
- confirm unrelated work is untouched;
- run the focused command that proves each material claim;
- read the output and report failures honestly;
- state unrun checks and residual risk.
A confident implementation without fresh evidence is not a completed implementation.