egkz Disciplined Code Changes
Guardrails against the ways code assistance commonly goes wrong. Apply them while the work happens, not as a post-hoc review.
Before you start
- Restate the requested change in one sentence. If your restatement is broader than the request, you have already scoped-crept.
- Name the assumptions the implementation depends on — about requirements, APIs, existing behavior, architecture. Verify the ones that would change the design.
- If the requirements are ambiguous in a way that changes what you build, ask now. One question beats a rewrite.
The rules
Prefer small, verifiable changes
Make the smallest change that satisfies the request, in a form where you can demonstrate it works.
Violation looks like: a large diff landing all at once with no intermediate point where behavior was checked.
Keep changes scoped to the requested task
No unrelated refactors, cleanup, renames, or stylistic edits. Note them separately if they matter; do not fold them in.
Violation looks like: the diff touches files the request never mentioned, or reformats lines you only happened to read.
Validate behavior, not just compilation
Run the relevant tests and checks. A build that succeeds is not evidence that the requested behavior works.
Violation looks like: "this should work now" with no command run and no output shown.
Check assumptions
When an assumption materially affects the implementation, verify it against the code, the docs, or the running system rather than proceeding on confidence.
Violation looks like: calling an API with a signature you remember rather than one you looked up.
Prefer the simplest correct solution
Reject unnecessary abstractions, layers, interfaces, configuration options, and dependencies. If a substantially simpler implementation satisfies the requirements, that is the implementation.
Violation looks like: a factory, a strategy interface, or a new config flag introduced for a single call site with one caller.
Preserve unrelated code
Do not remove or rewrite comments, error handling, or behavior merely because you consider them unnecessary or prefer another approach. Existing code usually encodes a reason you cannot see.
Violation looks like: deleting this comment because the code "reads fine":
// Fall back to the default timeout because the configured value can be null for
// newly created environments, and OkHttp requires a positive timeout value.
val timeout = config.requestTimeout ?: DEFAULT_TIMEOUT
Keep the codebase clean
Remove scaffolding, debug output, and scratch files introduced during the work. Leave behind no dead code, unused abstractions, or unnecessary dependencies.
Never leave comments that narrate the editing session — no "updated to handle the new case", "removed the old approach", "refactored per request". Comments explain the code as it stands, to a reader who was not there.
Surface uncertainty and tradeoffs
When requirements are ambiguous, or when multiple approaches carry meaningful tradeoffs, say so and either ask or state the tradeoff plainly. Do not pick one silently and present it as the only option.
Violation looks like: choosing between two storage designs without mentioning that a choice existed.
Do not optimize prematurely
Get it correct first. Optimize only when there is a demonstrated need or an explicit performance requirement, and verify the optimization preserves correctness.
Violation looks like: caching, batching, or hand-unrolling something nobody has measured.
Do not overdo documentation
Generated documentation is cheap to produce and expensive to keep true. Write what carries real information and will stay accurate. Prefer clear code and precise names over prose restating them.
Violation looks like: a docstring on every trivial getter, or an architecture document nobody asked for.
Work from success criteria
Prefer explicit, testable outcomes over step-by-step instructions. When given a desired outcome, choose how to reach it — while staying inside the project's existing conventions and constraints. When you are the one specifying work, state the criteria rather than the steps.
Before you hand back
- The relevant tests and checks were actually run, and you can show the output.
- No temporary code, debug statements, or scratch files remain.
- Every file in the diff is one the task required touching.
- No comment refers to the editing process or to prior versions of the code.
- Any assumption you could not verify, or tradeoff you chose between, is stated explicitly in your response.