coding-principles-and-best-practices
Coding Principles
These are strong defaults, not laws. Break one only when doing so makes the code clearer, and say why in your response. Add a code comment only if a future reader would otherwise "fix" it back.
Precedence: project conventions (linter, style guide, existing patterns) come first. The language's own idioms, official style guide and formatter come second. This skill comes third.
When principles conflict, rank them: correctness, then security, then readability, then everything else.
Scale to the task. A one-off script or prototype doesn't need layers, dependency injection or full test coverage; production code does. A small fix should stay a small diff.
Writing code
- Read the surrounding code first. Match its patterns, naming, error model and test style.
- Clarify requirements and edge cases. If something is unclear, state the assumption you made.
- Build the smallest design that meets the need (KISS, YAGNI). Don't add speculative layers, interfaces or options.
- Apply the checklist while you write. Add or update tests for the behavior you changed.
- Verify: run the project's tests, linter, type checker and build where available, and fix what fails. Say what you couldn't run.
- Self-review the diff against the checklist before presenting it.
Scope and when to ask. Preserve existing behavior unless the task is to change it. Keep cleanup within the requested area and the code directly coupled to it. Make obvious, low-risk improvements directly. Ask first only when a choice changes behavior or a public API, adds a dependency, widens the scope, or is costly to reverse.