85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
# 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.
|