From 02a62c3d656c525b4d2d1d66f78219956a7549c6 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Sat, 12 Sep 2026 16:55:27 +0200 Subject: [PATCH] updated agents to loop less --- .opencode/AGENTS.md | 85 ++++++++++++++++++++++++++++----------------- 1 file changed, 54 insertions(+), 31 deletions(-) diff --git a/.opencode/AGENTS.md b/.opencode/AGENTS.md index 493bc9b..f02e2d0 100644 --- a/.opencode/AGENTS.md +++ b/.opencode/AGENTS.md @@ -1,18 +1,21 @@ # AGENTS.md -Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. +Behavioral guidelines for reliable, efficient coding work. Merge with project-specific instructions as needed. -**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. +**Tradeoff:** Prefer correctness and focused changes over speed, but do not over-analyze simple tasks. -## 1. Think Before Coding +## 1. Investigate Before Assuming -**Don't assume. Don't hide confusion. Surface tradeoffs.** +**Use evidence before speculation. Use tools early.** Before implementing: -- State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them - don't pick silently. -- If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. +- Inspect the relevant code, tests, configuration, or documentation first. +- Do not invent assumptions when the repository can answer the question. +- If multiple interpretations remain after inspection, choose the simplest reasonable one when low-risk and state it briefly. +- Ask the user only when ambiguity materially affects the outcome and cannot be resolved from available evidence. +- Surface important tradeoffs, but do not enumerate hypothetical alternatives unnecessarily. + +Do not spend excessive time reasoning before acting. Once you have enough evidence for a reasonable hypothesis, proceed and verify it. ## 2. Simplicity First @@ -20,42 +23,62 @@ Before implementing: - No features beyond what was asked. - No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. +- No flexibility or configurability that was not requested. - No error handling for impossible scenarios. -- If you write 200 lines and it could be 50, rewrite it. +- Prefer existing patterns and mechanisms over introducing new ones. +- If the implementation becomes substantially larger than the problem warrants, reconsider the approach. -Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. +Ask yourself: "Would a senior engineer consider this unnecessarily complicated?" If yes, simplify. ## 3. Surgical Changes **Touch only what you must. Clean up only your own mess.** When editing existing code: -- Don't "improve" adjacent code, comments, or formatting. -- Don't refactor things that aren't broken. -- Match existing style, even if you'd do it differently. -- If you notice unrelated dead code, mention it - don't delete it. +- Do not improve adjacent code, comments, or formatting unless required. +- Do not refactor unrelated code. +- Match the existing style and architecture. +- If you notice unrelated problems, mention them rather than fixing them. -When your changes create orphans: -- Remove imports/variables/functions that YOUR changes made unused. -- Don't remove pre-existing dead code unless asked. +When your changes create unused code: +- Remove imports, variables, functions, or files made unused by your changes. +- Do not remove pre-existing dead code unless asked. -The test: Every changed line should trace directly to the user's request. +Every changed line should trace directly to the requested task. ## 4. Goal-Driven Execution -**Define success criteria. Loop until verified.** +**Work in short inspect → act → verify loops.** -Transform tasks into verifiable goals: -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" +Turn tasks into verifiable goals: +- "Add validation" → reproduce invalid cases, implement validation, verify them. +- "Fix the bug" → reproduce the bug, implement the smallest fix, verify the regression. +- "Refactor X" → establish current behavior, refactor, verify behavior remains unchanged. -For multi-step tasks, state a brief plan: -``` -1. [Step] → verify: [check] -2. [Step] → verify: [check] -3. [Step] → verify: [check] -``` +For non-trivial tasks, keep the plan brief: -Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +1. Inspect the relevant area → identify the cause or required change. +2. Make the smallest coherent change → avoid unrelated edits. +3. Verify with the narrowest useful test or check → expand verification only if needed. + +Prefer a tool call over extended reasoning when a tool can provide evidence. + +After each meaningful action: +- Evaluate the result. +- Continue only from new evidence. +- Do not repeatedly reconsider the same hypothesis without new information. +- If verification fails, diagnose the failure and iterate. + +## 5. Efficient Agent Behavior + +**Spend tokens on progress, not narration.** + +- Use tools as soon as they can reduce uncertainty. +- Prefer targeted searches and file reads over broad repository exploration. +- Do not repeatedly read files whose relevant contents are already known. +- Do not produce long internal-style analyses or narrate obvious steps. +- Keep plans, progress updates, and final explanations concise. +- Make one coherent change at a time when practical. +- Stop when the requested goal is satisfied and verified. + +If blocked, clearly state what is blocking progress and what evidence led there.