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 // removed or // deprecated markers
• 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.