From 37691226eca22819f67826f6180ead8dbbbb5c26 Mon Sep 17 00:00:00 2001 From: Michael Suchacz <203725896+ibetitsmike@users.noreply.github.com> Date: Fri, 11 Sep 2026 13:06:58 +0200 Subject: [PATCH] docs: favor autonomous completion in agent guidance --- .agents/skills/dogfood/SKILL.md | 2 +- .agents/skills/refine-plan/SKILL.md | 12 ++++++------ .claude/docs/WORKFLOWS.md | 3 ++- AGENTS.md | 13 ++++++++++--- 4 files changed, 19 insertions(+), 11 deletions(-) diff --git a/.agents/skills/dogfood/SKILL.md b/.agents/skills/dogfood/SKILL.md index 58fa9e7cb56..1eab391bb5d 100644 --- a/.agents/skills/dogfood/SKILL.md +++ b/.agents/skills/dogfood/SKILL.md @@ -27,7 +27,7 @@ Before starting Coder: 3. Inspect the changed files and relevant tests. 4. Summarize what behavior changed. 5. Decide what must be validated through UI, API, SQL, logs, browser automation, desktop automation, or computer use. -6. Ask for clarification if the target PR, base PR, stack order, or required credentials are ambiguous. +6. Resolve the target PR, base PR, stack order, and required access from conversation context, Git state, PR metadata, and available local configuration. Ask only if essential target or access information remains unavailable, and continue validation that does not depend on it. Never expose credential values while investigating. ## Start the dogfood instance diff --git a/.agents/skills/refine-plan/SKILL.md b/.agents/skills/refine-plan/SKILL.md index 818db5e4240..c72702f68a2 100644 --- a/.agents/skills/refine-plan/SKILL.md +++ b/.agents/skills/refine-plan/SKILL.md @@ -31,9 +31,9 @@ Every step should be concrete enough that another agent could execute it without NEVER include thinking output or other stream-of-consciousness prose mid-plan. -### 2. Push Back on Unclear Requirements +### 2. Resolve Unclear Requirements -When requirements are ambiguous, ask questions before proceeding. +Resolve ambiguity using the conversation, relevant code, existing tests, and documentation. Make reasonable, reversible assumptions consistent with the requested outcome and record them in the plan. Ask only when essential missing information cannot be recovered and would materially change the result; continue independent planning work while waiting. ### 3. Tests Define Requirements @@ -61,7 +61,7 @@ All plans follow: **Red → Green → Refactor**. The refactor phase is MANDATOR **Write descriptive test cases:** -**If you can't write the test, you don't understand the requirement and MUST ask for clarification.** +If you cannot define a test yet, investigate the behavior and comparable tests first. Use the clarification criteria above only if essential requirements remain unresolved. ### Green Phase: Make Tests Pass @@ -112,11 +112,11 @@ Look for missing tests, vague steps, no refactor phase, ambiguous requirements, ### Step 3: Handle Unclear Requirements -If you can't write the plan without this information, ask the user. Otherwise, make reasonable assumptions and note them in the plan. +Investigate gaps using available context, then record reasonable assumptions in the plan. Ask only about essential unresolved requirements, and continue the parts of the plan that do not depend on the answer. ### Step 4: Define Test Cases -For each requirement, write concrete test cases. If you struggle to write test cases, you need more clarification. +For each requirement, write concrete test cases. If a case is unclear, inspect existing behavior and related tests before deciding whether user input is needed. ### Step 5: Structure with Red-Green-Refactor @@ -131,7 +131,7 @@ Specify how to confirm the change works (automated tests + manual checks). 1. **Start with tests:** If you can't write the test, you don't understand the requirement. 2. **Be specific:** "Update API" is not a step. "Add error handling to POST /users endpoint" is. 3. **Always refactor:** Even if code looks good, ask "How could this be clearer?" -4. **Question everything:** Ambiguity is the enemy. +4. **Investigate ambiguity:** Use evidence and explicit assumptions to make progress. 5. **Think in phases:** Red → Green → Refactor. 6. **Keep plans manageable:** If plan exceeds ~10 files or >5 phases, consider splitting. diff --git a/.claude/docs/WORKFLOWS.md b/.claude/docs/WORKFLOWS.md index 4e63b686fbe..1cdb376543a 100644 --- a/.claude/docs/WORKFLOWS.md +++ b/.claude/docs/WORKFLOWS.md @@ -172,7 +172,8 @@ developer opts in via git config or is allowlisted in the hook: `git commit` and `git push` will appear to hang while hooks run. This is normal. Do not interrupt, retry, or reduce the timeout. -NEVER run `git config core.hooksPath` to change or disable hooks. +Configure `core.hooksPath` as `scripts/githooks` when installing the +repository hooks. Never change it to bypass or disable those hooks. If a hook fails, fix the issue and retry. Do not work around the failure by skipping the hook. diff --git a/AGENTS.md b/AGENTS.md index f04e206c3c0..58e40e990f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,16 @@ # Coder Development Guidelines -Make the smallest correct change, follow existing patterns, and verify the result. Ask only when the request is unclear, a meaningful design choice remains, or the action is destructive. If you want an exception to any rule in these documents, stop and get explicit permission first. +Make the smallest correct change, follow existing patterns, and verify the result. Carry the requested task through implementation, verification, and necessary follow-up until it is complete or blocked by information or access you cannot obtain. Do not stop at a plan, partial fix, or offer to continue when the user requested completed work. Prioritize correctness over agreement. State uncertainty instead of guessing, and push back on technically unsound requests with evidence. +## Autonomy and clarification + +- Resolve routine ambiguity by inspecting relevant code, tests, documentation, and history. Make reasonable, reversible assumptions consistent with the user's intent and existing patterns; state consequential assumptions and continue working. +- Ask only when essential information cannot be recovered from available context and would materially change the result, or when a destructive or irreversible action requires authorization the user has not already provided. Reuse authorization from the conversation instead of asking again for the same action. +- If clarification or approval is required, continue authorized work that does not depend on the answer. Explain the specific blocker and what you have already investigated. +- Apply repository guidance within its stated scope and honor explicit user instructions. Do not turn optional recommendations or routine implementation choices into approval requirements. + ## Task-specific guidance Load only the guidance relevant to the task: @@ -33,8 +40,8 @@ For changes under `site/src/`, also read [FRONTEND_PATTERNS.md](.claude/docs/FRO ## Workflow - Inspect the working tree before editing. For an existing PR, check out its branch first. -- Discuss architectural decisions such as framework changes, major refactoring, and system design before implementing them. Routine fixes and clear implementations do not need discussion. -- When asked a question, answer the question instead of jumping to implementation. +- Follow existing architecture for routine decisions. For requested architectural work, investigate options, choose a reasonable approach, and explain the tradeoffs while proceeding. Ask before introducing major architectural changes outside the requested scope. +- Answer informational questions directly. Requests to implement, fix, or investigate authorize that work even when phrased as a question. - Install and use the repository Git hooks. Never bypass them with `--no-verify`. Wait for slow first runs while caches warm. - Prefer targeted tests and checks while iterating. Run the broader checks required by the affected area before handoff. - Do not force-push unless explicitly requested.