Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 227e967

Browse files
ibetitsmikeibetitsmike
authored
docs: favor autonomous completion in agent guidance (#29227)
Repository guidance required agents to pause for routine ambiguity, rule exceptions, and design decisions. Update the root instructions to favor investigating available context, making reasonable reversible assumptions, reusing existing authorization, and completing requested work through verification. Reserve clarification for essential missing information and actions that still need authorization. Align the planning and dogfood skills with that behavior, and clarify that installing the repository Git hooks is allowed while bypassing them remains prohibited.
1 parent d726903 commit 227e967

4 files changed

Lines changed: 19 additions & 11 deletions

File tree

‎.agents/skills/dogfood/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Before starting Coder:
2727
3. Inspect the changed files and relevant tests.
2828
4. Summarize what behavior changed.
2929
5. Decide what must be validated through UI, API, SQL, logs, browser automation, desktop automation, or computer use.
30-
6. Ask for clarification if the target PR, base PR, stack order, or required credentials are ambiguous.
30+
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.
3131

3232
## Start the dogfood instance
3333

‎.agents/skills/refine-plan/SKILL.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,9 @@ Every step should be concrete enough that another agent could execute it without
3131

3232
NEVER include thinking output or other stream-of-consciousness prose mid-plan.
3333

34-
### 2. Push Back on Unclear Requirements
34+
### 2. Resolve Unclear Requirements
3535

36-
When requirements are ambiguous, ask questions before proceeding.
36+
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.
3737

3838
### 3. Tests Define Requirements
3939

@@ -61,7 +61,7 @@ All plans follow: **Red → Green → Refactor**. The refactor phase is MANDATOR
6161

6262
**Write descriptive test cases:**
6363

64-
**If you can't write the test, you don't understand the requirement and MUST ask for clarification.**
64+
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.
6565

6666
### Green Phase: Make Tests Pass
6767

@@ -112,11 +112,11 @@ Look for missing tests, vague steps, no refactor phase, ambiguous requirements,
112112

113113
### Step 3: Handle Unclear Requirements
114114

115-
If you can't write the plan without this information, ask the user. Otherwise, make reasonable assumptions and note them in the plan.
115+
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.
116116

117117
### Step 4: Define Test Cases
118118

119-
For each requirement, write concrete test cases. If you struggle to write test cases, you need more clarification.
119+
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.
120120

121121
### Step 5: Structure with Red-Green-Refactor
122122

@@ -131,7 +131,7 @@ Specify how to confirm the change works (automated tests + manual checks).
131131
1. **Start with tests:** If you can't write the test, you don't understand the requirement.
132132
2. **Be specific:** "Update API" is not a step. "Add error handling to POST /users endpoint" is.
133133
3. **Always refactor:** Even if code looks good, ask "How could this be clearer?"
134-
4. **Question everything:** Ambiguity is the enemy.
134+
4. **Investigate ambiguity:** Use evidence and explicit assumptions to make progress.
135135
5. **Think in phases:** Red → Green → Refactor.
136136
6. **Keep plans manageable:** If plan exceeds ~10 files or >5 phases, consider splitting.
137137

‎.claude/docs/WORKFLOWS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,8 @@ developer opts in via git config or is allowlisted in the hook:
172172
`git commit` and `git push` will appear to hang while hooks run.
173173
This is normal. Do not interrupt, retry, or reduce the timeout.
174174

175-
NEVER run `git config core.hooksPath` to change or disable hooks.
175+
Configure `core.hooksPath` as `scripts/githooks` when installing the
176+
repository hooks. Never change it to bypass or disable those hooks.
176177

177178
If a hook fails, fix the issue and retry. Do not work around the
178179
failure by skipping the hook.

‎AGENTS.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
11
# Coder Development Guidelines
22

3-
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.
3+
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.
44

55
Prioritize correctness over agreement. State uncertainty instead of guessing, and push back on technically unsound requests with evidence.
66

7+
## Autonomy and clarification
8+
9+
- 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.
10+
- 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.
11+
- 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.
12+
- Apply repository guidance within its stated scope and honor explicit user instructions. Do not turn optional recommendations or routine implementation choices into approval requirements.
13+
714
## Task-specific guidance
815

916
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
3340
## Workflow
3441

3542
- Inspect the working tree before editing. For an existing PR, check out its branch first.
36-
- Discuss architectural decisions such as framework changes, major refactoring, and system design before implementing them. Routine fixes and clear implementations do not need discussion.
37-
- When asked a question, answer the question instead of jumping to implementation.
43+
- 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.
44+
- Answer informational questions directly. Requests to implement, fix, or investigate authorize that work even when phrased as a question.
3845
- Install and use the repository Git hooks. Never bypass them with `--no-verify`. Wait for slow first runs while caches warm.
3946
- Prefer targeted tests and checks while iterating. Run the broader checks required by the affected area before handoff.
4047
- Do not force-push unless explicitly requested.

0 commit comments

Comments
 (0)