Code Discipline

Code Discipline

A coding methodology for production systems that must last. Not a communication standard. Not an honesty protocol. Purely: how to write code well.

Tradeoff: This discipline biases toward correctness and simplicity over speed and cleverness. For throwaway scripts, apply judgment. For production code — apply everything.

Priority Order

Every technical decision is evaluated in this order:

1. Stability
2. Reliability
3. Readability
4. Maintainability
5. Scalability
6. Performance
7. Elegance

The goal is not "it works" — it is "it works correctly and reliably one year from now."

1. Think Before Coding

Don't assume. Surface tradeoffs. Map blast radius.

Before writing any code, present all four:

1. Working assumptions — what are you assuming to be true?
2. Constraints and risks — what could go wrong?
3. Multiple valid solutions? — if yes, stop and present options; do not choose independently
4. Dependencies and blast radius — what else is affected by this change?

Rules:

• If uncertain — ask, don't assume and proceed
• If multiple interpretations exist — present them, don't pick silently
• If a simpler approach exists — say so and push back
• If information is missing — stop and ask; do not proceed without answers

2. Verify Reality Before Acting

Don't code from memory. The codebase is the source of truth.

Before writing or changing code:

• Read the actual files involved. Don't work from a remembered shape.
• Don't invent APIs, function names, type names, field names, environment variables, configuration keys, or imports.
• Don't assume a pattern, helper, or utility exists unless you verified it in the repository.
• Don't assume a third-party library behaves a certain way without checking its documentation or signature.
• If you cannot find evidence in the codebase, say so explicitly: "I couldn't find this in the code" — and stop. Do not fill the gap from memory.

The test: Every function call, import, type, and field in your code must trace to a verified source — an actual file, an actual signature, or documentation you read.

Evidence standard for claims: When stating that code works, that a test passes, or that a file does something specific, cite file:line and the quoted code or output. Paste actual command output rather than summarizing it. "It should work" and "I believe" are not evidence.

3. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked
• No abstractions for single-use code
• No "flexibility" or "configurability" that wasn't requested
• No error handling for impossible scenarios
• If you write 200 lines and it could be 50, rewrite it

All code must be modular, readable, testable, and defensible in a code review. There must be no magic numbers, hidden state, overly clever constructs, or silent failures.

Ask: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

4. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting
• Don't refactor things that aren't broken
• Match existing style, even if you'd do it differently
• If you notice unrelated dead code, mention it — don't delete it
• Remove only imports/variables/functions that YOUR changes made unused

Required steps:

BEFORE — Read the file completely. Map dependencies and blast radius. Identify affected tests. Check if a suitable solution already exists in the project.

DURING — Change only what's needed. No unrelated refactoring. Preserve working behavior. No duplication.

AFTER — Run affected tests. Run full test suite. Verify zero regressions. Verify tests assert real-world behavior, not just mock matches. Document in changelog with facts, not narrative.

BEFORE COMMIT — Get explicit approval. Show exactly what's being committed. No hidden files.

The test: Every changed line should trace directly to the request.

5. Respect Existing Contracts

Public surfaces are commitments. Treat them as such.

Before changing behavior, identify the contracts your change touches. Contracts include:

• Function and method signatures (parameters, return types, thrown errors)
• API request and response shapes
• Database schemas and column types
• Event names and payloads
• CLI flags and command names
• Configuration keys and environment variables
• Error codes and error formats
• File formats your code reads or writes

Rules:

• Don't change a contract silently. A silent rename, removal, or reshape is a breaking change disguised as cleanup.
• If a contract must change, surface the impact: who consumes it, what breaks, what migration looks like.
• Prefer additive changes (new field, new endpoint, new flag) over breaking changes (rename, remove, restructure).
• When in doubt about who depends on a surface, search the codebase and ask before changing.

The test: If your change crosses a system boundary, you must name the boundary and the consumers before changing it.

6. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Checkpoint between steps: Complete and verify each step before starting the next. Do not chain steps without confirming the previous one succeeded. Catching divergence at step 2 is much cheaper than catching it at step 5.

Testing principles:

• Every change must include tests, or a clear explanation of why not
• Tests must verify real behavior — not just match mocks
• A passing suite means the tests think it works — verify they test the right thing
• State certainty level explicitly when uncertain about an API or behavior

Strong success criteria let you work independently. Weak criteria ("make it work") require constant clarification.

Mandatory Prohibitions

Mandatory Review Questions

Before each step, answer all four:

1. Is this the most professional and simplest solution?
2. Does this change preserve what already works?
3. Is this a reasonable production-grade solution?
4. Would this pass code review at a top-tier engineering organization?

Only if all four answers are positive — proceed.

These guidelines are working if: changes are smaller and more focused, no unrequested features appear in diffs, every task has a verifiable definition of done before work begins, and contracts are preserved unless an explicit migration is agreed upon.