AI Code Style Rules

When editing an existing codebase, the codebase's conventions outrank your personal preferences every time — consistency across the whole codebase is worth more than any single file being marginally "better" in isolation.

Match existing style over personal preference

• Before writing new code, read enough of the surrounding file(s) to identify the existing patterns (naming conventions, quote style, import ordering, error handling approach) and match them exactly, even when a different pattern is technically preferable.
• If the codebase is inconsistent between files, match the style of the specific file/module being edited rather than picking a personal favorite from among the inconsistent options — local consistency beats global consistency when they conflict.
• Never introduce a new pattern (a new state management approach, a new utility library for something already handled elsewhere) into a codebase that already has an established way of doing it, even if the new pattern is objectively newer or more popular.

No drive-by refactors

• Change only what the task requires. Resist reformatting untouched code, renaming unrelated variables, or "improving" adjacent functions while completing a narrow task — unrequested changes inflate the diff and make it harder for a human reviewer to see what actually matters.
• If a genuine improvement to unrelated code is spotted while working, mention it as a suggestion in the response rather than silently including it in the change — let the human decide whether it's worth a separate change.
• Never let an IDE's auto-format-on-save rewrite whitespace or formatting across an entire file when only a few lines were logically changed — scope the diff to the actual edit.

Minimal diffs

• Produce the smallest diff that correctly accomplishes the task — prefer editing existing code over rewriting a whole file, and prefer a small targeted function over restructuring the surrounding module.
• When a larger refactor is genuinely necessary to accomplish the task correctly, say so explicitly and explain why the minimal version isn't sufficient, rather than silently expanding scope.

Comments only where code can't speak

• Write a comment only when the code's intent isn't obvious from reading it (a non-obvious business rule, a workaround for an external bug, a deliberately unusual approach) — comments that restate what the code obviously does add noise and go stale as the code changes.
• Never leave comments narrating the editing process itself ("added this function," "changed from X to Y") — that belongs in a commit message, not in the source.
• Prefer a clearer variable/function name over a comment explaining an unclear one, when both are options — the name is always visible at every call site; the comment is only visible at the definition.

No placeholder or TODO code in deliverables

• Never hand back code containing // TODO: implement this, stub functions that throw not implemented, or fake data standing in for a real integration, presented as if the task were complete — an unfinished deliverable must be labeled unfinished, not disguised as done.
• If part of a task genuinely can't be completed (missing credentials, an ambiguous requirement, a dependency not yet available), say so explicitly and describe exactly what's missing, rather than shipping placeholder code silently.

Respect the project's stack choices

• Use the language, framework, and libraries the project already uses for a given concern, even if a different tool is generally considered better — introducing a second solution for something already solved (a second HTTP client, a second date library) creates ongoing maintenance cost for marginal benefit.
• Match the project's existing architecture (file structure, module boundaries, layering conventions) rather than introducing a personally preferred structure for new code.

Ask before adding dependencies

• Never add a new external dependency to solve a problem that could reasonably be solved with existing project dependencies or a small amount of first-party code, without flagging it first — every dependency is an ongoing maintenance, security, and bundle-size cost that the project owner should approve, not something to introduce silently.
• When a new dependency is genuinely the right call, state which one, why, and what it replaces or adds, and let the human confirm before committing it.