Code Discipline
Rules for writing clean, minimal, production-grade code. These apply to every code change — no exceptions.
1. Change Only What's Asked
Touch only the code necessary to complete the request. Do not:
- Refactor surrounding code that "could be better"
- Add docstrings, type annotations, or comments to untouched code
- Rename variables you didn't introduce
- "Improve" imports, formatting, or style outside your change
If existing code has problems, mention them — don't fix them silently.
2. No Speculative Code
Write code for current requirements, not hypothetical futures. Do not:
- Add error handling for scenarios that cannot occur
- Build abstractions for a single use case
- Add feature flags, configuration options, or extension points that weren't asked for
- Create helper functions for one-time operations
- Add backwards-compatibility shims when you can just change the code
Three similar lines of code are better than a premature abstraction.
3. Match Existing Patterns
Before proposing any change, read the files you intend to modify. Then:
- Match existing naming conventions (camelCase, snake_case, etc.)
- Follow established code organization and file structure
- Use the same patterns for similar operations — do not introduce a new style
- Adopt the project's existing approach to error handling, logging, and testing
When in doubt, imitate what's already there.
4. Delete Completely
When removing code, remove it. Do not:
- Comment it out
- Rename unused variables with a
_prefix - Add
// removedor// deprecatedmarkers - Re-export removed items for backwards compatibility
- Leave empty blocks or placeholder comments
If you're certain something is unused, delete it entirely.
5. Comments Explain Why
Only add comments where the logic isn't self-evident. Comments must explain why, not what. Do not add:
- Comments that restate the code (
// increment counter) - Temporal markers (
// added in v2,// phase 1) - AI attribution (
// generated by Claude) - Section dividers or decorative comments
- TODO comments unless the user asked for them
No comment is better than a redundant comment.
6. Clarity Over Cleverness
Write code that reads naturally. Prefer:
- Explicit logic over compact one-liners
- Named variables over inline expressions
- Early returns over deep nesting
- Simple conditionals over nested ternaries
If a reader needs to pause to parse it, rewrite it more clearly.
7. Validate at Boundaries
Handle errors where untrusted data enters your system:
- User input, API responses, file I/O, environment variables
Trust internal code and framework guarantees. Do not:
- Defensively null-check values that are never null
- Wrap internal calls in try/catch "just in case"
- Validate function arguments from your own codebase
- Add fallback defaults for values guaranteed by the type system
8. Verify Your Work
After implementation, run the existing test suite. Do not assume tests pass. If tests break, fix them before moving on. If there is no test suite, check that the code at least compiles/parses without errors.
Per-Change Checklist
Before finishing any code change, verify:
- Every modified line is necessary for the request
- No speculative features, abstractions, or error handling was added
- Existing code style and conventions are matched
- Removed code is fully deleted, not commented out
- Comments (if any) explain why, not what
- Code reads clearly without requiring mental gymnastics
- Error handling is only at system boundaries
- Tests pass (or code compiles if no tests exist)
For concrete examples of these principles, read references/examples.md.