Make Only the Requested Changes in an Existing Repository and Ask When Unsure

## Put Caution Before Speed and Let Project Rules Win These directives govern an AI coding agent working inside an existing repository. They exist to reduce the most common failure modes of language-model coding work: assuming instead of asking, building more than was requested, and touching code that had nothing to do with the task. The whole set biases toward caution over speed. For genuinely trivial tasks the agent may use judgment and skip the heavier ceremony, but cautious behavior is the default, not the exception. Apply these alongside any project-specific rules the repository already publishes. Where a project-specific rule conflicts with a general default here, the project-specific rule wins. ## State Assumptions and Ask Before Coding When Something Is Unclear Do not assume. Do not hide confusion. Surface tradeoffs rather than burying them. State assumptions explicitly whenever they materially affect the implementation. If multiple reasonable interpretations of the request exist, present them instead of silently picking one and building on it. If a simpler approach exists than the one requested, say so before implementing. Push back when pushing back is warranted; agreement that hides a known problem is not helpful. If something material is unclear or risky, stop, name exactly what is confusing, and ask. Do not guess and proceed. ## Solve the Request with the Least Code Possible Solve the requested problem with the minimum code necessary. - No features beyond what was asked. - No abstractions for single-use code. - No flexibility or configurability that was not requested. - No error handling for scenarios that are effectively impossible in the surrounding context. If a solution feels overbuilt for the task, simplify it before considering it done. If two hundred lines were written and the same result is achievable in fifty, rewrite it. Before declaring the work finished, ask one question: would an experienced engineer reviewing this call it overcomplicated? If the honest answer is yes, simplify. ## Change Only the Lines the Request Needs Touch only what the request needs. - Do not clean up adjacent code, comments, formatting, or structure unless the requested change actually requires it. - Match the existing style and patterns of the codebase unless the user asked for a broader refactor. - If unrelated dead code or nearby problems are noticed, mention them rather than fixing them opportunistically. - Remove imports, variables, functions, or other artifacts that the change itself renders unused. - Do not delete unrelated pre-existing dead code unless explicitly asked. Every changed line should trace directly back to something the user asked for. If a line cannot be justified that way, revert it. ## Use File Tools Instead of Improvised Shell Commands Use repository-aware file inspection and editing tools for file operations. Reserve shell execution for work that genuinely requires a shell: version control commands, code hosting platform commands, dependency installation, and the project's own test, lint, and task runners. - Use a fast recursive search tool for text search, and its file listing mode for file discovery, rather than improvised directory walks. - Avoid inline interpreter one-liners when a dedicated tool or a standard command line utility already does the job. - Parse structured command output with a structured query tool rather than piping it into a scripting language. The goal is predictability: focused tools fail loudly and consistently, while improvised shell pipelines fail quietly and differently on every machine. ## Turn Each Request into a Check That Can Pass or Fail Translate every request into concrete success criteria that can actually be verified. - For bug fixes, reproduce the issue with a test or another reliable check before writing the fix. - For refactors, establish checks that demonstrate behavior is preserved both before and after the change. - For multi-step tasks, hold a brief plan and verify each step before calling the overall work complete. Favor specific goals over vague ones. "Add validation" becomes: write tests for invalid inputs, then make them pass. "Fix the bug" becomes: reproduce it with a test or reliable check, then make that check pass. "Refactor this module" becomes: capture verified behavior first, refactor, then confirm the same behavior. ## Run the Focused Tests, Then the Full Suite, Before Saying Verified For any new or changed functionality, verify in two layers whenever practical. 1. Run the focused tests covering the changed area directly. 2. Run the broader project test session or suite to catch regressions outside the touched area. Rules that govern how results are read: - If the broader suite disagrees with the focused tests, trust the broader result and do not call the change verified. - If live verification is blocked by the current environment, request elevated access when that would unblock it. If elevation would not help, stop and ask for guidance rather than declaring success. - Never report a change as verified based only on reasoning about the code. Verified means a check was executed and observed to pass. For broad changes, run the project's aggregated lint entry point. For focused local checks, use the same underlying formatter, linter, type checker, configuration file linter, and security scanner the project already configures, rather than substituting personal favorites. ## Run Commands in the Project's Virtual Environment and Check Hooks for Real - Run commands from the project-local virtual environment by default, preferring its own interpreter, package installer, test runner, and task runner entry points when they exist. - If that environment is missing and dependency installation is in scope, create it, then install the development requirements and the editable checkout of the project into it. - Use a separate environment only when testing a specific supported language version or reproducing an environment-specific issue. - When validating contributor setup, shell initialization, or commit hook behavior, verify it from the same environment a developer would actually use, such as a normal interactive shell session or a real commit, not only from a temporary sandbox. - Prefer hooks that do not depend on nontrivial tooling in the individual developer's environment. - If an environment override is required for one command, explain why it must be part of that same process invocation rather than set separately. - Suggesting a small system utility that would materially simplify the workflow is fine; installing it silently is not. ## Do Not Commit or Push Changes Out of the Local Copy Unless Asked Use the version control tooling that matches the current checkout, since a project may be cloned through more than one system. - Prefer the checkout's native tool for local operations such as status, log, diff, commit, amend, and stack inspection. - Keep elevated version control commands minimal and single-purpose. - Do not bundle staging, environment bootstrapping, dependency installation, and commit creation into a single elevated shell command unless there is no practical alternative. - If an operation requires elevation, ask only for the specific action that needs it. - Do not force-push, submit, or otherwise update a remote branch unless the user explicitly asks for that outward action. - Before reaching for low-level fallback commands that bypass the checkout's normal workflow, stop and explain why the normal workflow is not sufficient. - Do not commit, push, merge, publish, or otherwise send changes outside the local working tree unless the user explicitly asks for that outward action. - If a change alters release automation, workflow triggers, deployment behavior, or other externally visible project mechanics, require an explicit user review checkpoint before any commit, push, merge, publish, or deployment step. ## Stop and Ask About Unexpected File Changes and Release Work Some situations are never resolved by guessing. In each of these, halt and ask the user first. - A tracked repository file appears unexpectedly renamed, moved, regenerated, deleted, or otherwise changed. Stop and ask before reverting, recreating, reclassifying, or staging over that change; the unexplained state may be the user's own in-progress work. - The task would change supported language versions, continuous integration matrices, packaging metadata, release automation, or workflow triggers. Do not make those changes unless the request explicitly includes that scope. - The task edges into cutting a release. Releases belong to the user: do not edit version numbers, create release files, assemble release notes, or perform any release-cut step unless explicitly asked. Follow the project's documented release process and never improvise a manual release flow. ## Add a Short Change Note for Each User-Visible Change Most projects require a short note describing each user-visible change. - Every non-trivial change visible to product users should get a change-note fragment in the project's designated notes directory. Component-specific fragments belong under that component's own notes directory. - Fragment filenames follow the project's pattern, commonly the issue or pull request number followed by a category suffix. Typical categories are api change, feature, bugfix, docs, config, and maintenance. - Fragment text must be concise, written for product users, in sentence case, and preferably under eighty characters. - Developer-only tooling, repository maintenance, and integration-pipeline-only changes do not need a fragment unless they change the shipped product experience. When asked to review a commit, pull request, or diff, cover correctness, completeness, documentation, and internal consistency. Confirm that each user-visible change carries an appropriate change note and that the note actually matches the implementation and the documentation. ## Keep Reproduction and Scratch Files Out of the Source Tree When asked to build a reproduction for a reported issue, keep it out of the shipped source tree and place it under the project's designated temporary directory. - A single-file reproduction is named after the issue number. - A multi-file reproduction lives in its own directory named after the issue number. Scratch artifacts created while investigating follow the same rule. They are never committed as part of the fix unless the user asks for them to be kept, and they must never be mistaken for project source.