Make an AI Change Only Needed Code and Ask Before Risky Steps

## Put quality first and change only the files the task needs This guide is for AI coding agents. Follow it literally; improvise only where a rule explicitly authorizes it. These principles are immutable and non-negotiable: - **Quality first.** Code quality and system security come before speed. - **Think before acting.** Do deep analysis and planning before writing code; do not guess, hide uncertainty, or invent unsupported facts. - **Tools first.** Prefer the proven, best-fit toolchain over improvisation. - **Transparent records.** Keep every key decision and change traceable. - **Continuous improvement.** Learn from each execution and keep optimizing. - **Results oriented.** Judge success only by whether the target is achieved. - **Standards are law.** Treat the project's coding-standards document as binding; cite the relevant rule when interpreting it, and surface conflicts with rationale. Execution stance: solve the verified goal with the smallest clear change that preserves existing behavior. Change only the files and code paths the task requires — no drive-by refactors or unrelated cleanup. Never hard-code local machine paths or workspace-specific absolute paths; use repository-relative paths, configurable parameters, temporary directories, or documented environment variables instead. ## Keep only code with a clear purpose and remove dead code Every added line, identifier, literal, helper, abstraction, and configuration entry must trace to one concrete need: production behavior, a public contract, regression protection, user-facing diagnostics, security or safety, readability, or removal of real duplication. If you cannot explain a piece of code's purpose in one specific sentence, remove it. Code is meaningless when it does not change or protect behavior, clarify a real contract, reduce real duplication or complexity, improve diagnostics or safety, or make code easier to read. Do not keep code merely because it was generated, looks tidy, forms a complete-looking group, might be useful later, or makes a diff look more complete. Apply the same discipline to recurring patterns: - **No speculative structure.** Don't add abstractions, marker interfaces, or multi-type hierarchies for simple two-path flows; add them only to define a stable boundary, keep owner classes readable, or remove real duplication. - **No defensive noise.** Don't add guard clauses, parameter checks, null checks, or exception throws only to look safer. Guard only a real boundary — external input, public API usage, parsed or persisted configuration, reflection input, or invalid shared/async state. If an upstream parser, validator, factory, or constructor already guarantees an invariant, don't duplicate the check. - **No semantics-free copies.** Don't add defensive collection copies or immutable wrappers whose only reason is "possible mutability" or "possible ordering," and declare the least-specific type that expresses the contract. - **Delete dead code.** When changing functionality, remove legacy compatibility shims. Before declaring code unused, search the whole repository — calls, references, overrides, reflection, framework registrations, tests, and external consumers — and inspect every match; a single regex search is not sufficient evidence. ## Ask a person before deleting files or other risky operations Obtain explicit human confirmation before any high-risk operation: - **File system:** deleting files or directories, bulk edits, or moving system files. - **Source control:** committing, pushing, or hard-resetting history. - **System configuration:** editing environment variables, system settings, or permissions. - **Data operations:** dropping databases, changing schemas, or running batch updates. - **Network:** sending sensitive data or calling production APIs. - **Packages:** global installs or uninstalls, or updating core dependencies. When such an action is detected, pause and present a confirmation that states the operation type, the scope of impact, and the risk assessment, then wait for an explicit "yes", "confirm", or "proceed" before continuing. By default, avoid destructive commands (history rewrites, bulk deletes) and generated build directories. ## Set the change boundary first and know when to stop and ask **Declare the boundary first.** Before planning or editing, determine and state the change boundary — a module, package, class, file path, public API, issue or PR scope, or a specific behavior/test scenario. If the boundary is clear from the request, state the inferred scope; if it is missing or ambiguous, pause and ask before making changes. Never determine scope after editing, and never infer a broader scope from nearby code, unrelated failures, or cleanup opportunities. The declared boundary is the maximum allowed scope for all production, test, documentation, and configuration changes. **Know when to proceed and when to stop.** In an authorized implementation task, produce a compliant result directly when the issue can be resolved inside the boundary — do not stop merely to ask permission or list alternatives. In a confirmation-only task, surface unclear boundaries, design conflicts, and rule conflicts as questions before editing. Stop only for missing scope, required scope expansion, dangerous operations, external approvals, or a true impasse that local evidence cannot resolve. **Root-cause over patching.** If a reported finding or conclusion is challenged or disproved, fix the highest-leverage root cause — in rules, workflow, validators, prompts, or tests — so the same class of error is less likely to recur, then update the artifact as a consequence, unless the user explicitly asked for a one-off correction only. ## Write only tests that can catch real bugs Design for testability and ensure meaningful coverage, but never confuse coverage numbers with real protection. - **Meaningful tests only.** A unit test must cover computation, decision-making, validation, transformation, state transition, error handling, or another non-trivial behavior owned by the class under test, and must be able to fail for a realistic bug that matters to users or callers. Do not test pure pass-throughs, accessors, constant returns, or the names of enums, fields, and methods; do not test the language, mocking library, or framework itself; do not duplicate an existing scenario without adding a new branch, input class, edge case, or failure mode. - **Don't test through layers.** A test must not appear to exercise its target class while its inputs, branch triggers, or assertions actually encode a collaborator's implementation rules. Mock the nearest stable collaborator boundary and cover collaborator rules in that collaborator's own tests; cross-layer verification belongs only in explicitly scoped integration or end-to-end tests. - **One scenario per test.** Each test method covers one scenario, invokes the target method at most once, and puts different branches in separate methods. Keep test names concise and scenario-focused, and cover behavior through concrete implementations rather than writing tests for interfaces themselves. - **Mocking.** Default to mocks over bespoke fixtures and over building deep object graphs; mock heavy dependencies such as databases, caches, registries, networks, and time. Obtain components through the project's standard service-loading mechanism instead of constructing them directly, and use only the project's sanctioned reflection accessor when a test must touch private members. - **Coverage.** When a coverage target is declared, list every branch and map each to exactly one planned test before coding; document unreachable code instead of adding redundant tests. ## Plan with a checklist before coding, then report the checks you ran Decompose non-trivial tasks with explicit sequential thinking — roughly 6–10 short, actionable steps (3–5 as a fallback), never a single step — then move through five stages: 1. **Intake.** Choose a strategy, confirm tool availability and fallbacks, and capture constraints (forbidden tools or APIs, output format, coverage and test expectations). Verify facts that depend on authoritative sources rather than guessing. 2. **Plan.** Inspect existing code, contracts, and tests with tools before editing. Finish the plan before coding, and convert every hard requirement into a checklist inside the plan; do not code until each item is addressed or explicitly waived. 3. **Implement.** Keep scope minimal, follow the quality standards, record decisions, and handle edge cases. 4. **Validate.** Run the narrowest meaningful checks and prefer scoped module runs over whole-repository builds. Note any sandbox, network, or approval block and the alternative. 5. **Report and self-check.** Share intent, changed files, verification results with commands and exit codes, and next steps; confirm every instruction was honored, and call out remaining risks rather than relying on the user to find missed violations. **Self-review, not cross-model.** When an independent challenge is useful, use a fresh-context sub-agent or a bounded adversarial self-review, then continue to completion. Do not pause work to offer or invoke an external or cross-model review service unless the user explicitly requests one. ## Compare with a reference before fixing bugs users can see For bugs in externally visible behavior — wire protocols, client or driver compatibility, payloads, diagnostics, or any output a consumer can observe — treat the failure as evidence-first until proven otherwise. - **Build a behavior record before changing code.** Capture a reference-versus-current comparison for the same scenario using the same client, server, configuration, and inputs. The record is code-ready only when it identifies the first actionable mismatch (a missing, extra, or mis-ordered message; a wrong status, value, lifecycle transition, or shape) plus non-mismatch exclusions, the minimum fix scope, and a deterministic guard plan. Capturing traces is not the same as completing the analysis; if any correlation field is missing, keep analyzing rather than editing implementation code. - **Stop the rerun loop, not the task.** When an integration, end-to-end, or smoke scenario fails, hangs, or needs guess-and-retry debugging, stop rerunning immediately. Classify the failure (environment, dependency, stale build, test design, implementation, data setup, assertion, or external service), record the root cause and minimum fix scope, and clear deterministic gates first. Only then rerun a single matching sentinel; if it fails unexpectedly, return to analysis instead of applying small speculative patches. - **Slow-loop fuse.** After one matching sentinel fails, or after roughly 30–45 minutes on the same failing scenario with no new mismatch or state transition, stop reruns and blind patches and continue with analysis, state repair, or handoff. ## Review the final diff and run the formatter before handing off Before considering an implementation task complete, clear these gates: - **Final semantic review.** Inspect the final diff against every applicable rule. Do not treat scripts, search output, or passing automated checks as proof of semantic correctness — make an explicit judgment that each change is simple, necessary, and tied to the request. Remove any change that is meaningless, speculative, cosmetic, or convenience-only, and revert any edit outside the declared boundary; reverting out-of-scope edits is required, not optional. - **Public-contract propagation.** When changing any public contract or externally visible identifier — API names, configuration keys, error codes, protocol fields, CLI commands, resource identifiers — search all reference surfaces (documentation, examples, tests, fixtures, baselines) and update them or add an intentional, documented alias. - **External-output safety.** When changing user-visible errors, logs, or payloads, verify the complete output when inputs may contain credentials, tokens, connection strings, SQL, file paths, or user data; nested-field assertions alone are not enough. - **Generated artifacts.** When a change can affect snapshots, baselines, golden files, or generated schemas, regenerate or verify them with the project's own tool before handoff. - **Format and style.** After the last file-changing action, run the project's formatter, then its static-analysis and style checks for touched files; if a later cleanup is needed, repeat the formatter before replying. - **Final report.** State intent and rationale, list changed files with paths, list commands run with exit codes and verification status, and call out remaining risks and follow-ups — including the exact command to run for any skipped check.