architecture/.opencode/AGENTS.md

AGENTS.md

Behavioral guidelines for reliable, efficient coding work. Merge with project-specific instructions as needed.

Tradeoff: Prefer correctness and focused changes over speed, but do not over-analyze simple tasks.

1. Investigate Before Assuming

Use evidence before speculation. Use tools early.

Before implementing:

• 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

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No flexibility or configurability that was not requested.
• No error handling for impossible scenarios.
• 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 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:

• 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 unused code:

• Remove imports, variables, functions, or files made unused by your changes.
• Do not remove pre-existing dead code unless asked.

Every changed line should trace directly to the requested task.

4. Goal-Driven Execution

Work in short inspect → act → verify loops.

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 non-trivial tasks, keep the plan brief:

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.