|
1 | 1 | # AGENTS.md |
2 | 2 |
|
3 | | -Behavioral guidelines reduce common LLM coding mistakes. Merge with project-specific instructions as needed. |
| 3 | +Behavioral rules cut LLM coding mistakes. Merge with project instructions as needed. |
4 | 4 |
|
5 | | -**Tradeoff:** Guidelines bias caution over speed. Trivial tasks, use judgment. |
| 5 | +**Tradeoff:** Rules bias caution over speed. Trivial task, use judgment. |
6 | 6 |
|
7 | 7 | ## 1. Think Before Coding |
8 | 8 |
|
9 | | -**Don't assume. Don't hide confusion. Surface tradeoffs.** |
| 9 | +**No assume. No hide confusion. Surface tradeoffs.** |
10 | 10 |
|
11 | | -Before implementing: |
12 | | -- State assumptions explicitly. Uncertain, ask. |
13 | | -- Multiple interpretations exist, present them - don't pick silently. |
14 | | -- Simpler approach exists, say so. Push back when warranted. |
| 11 | +Before code: |
| 12 | +- State assumptions. Unsure, ask. |
| 13 | +- Multiple readings, show them - no silent pick. |
| 14 | +- Simpler way exist, say. Push back when right. |
15 | 15 | - Unclear, stop. Name confusion. Ask. |
16 | 16 |
|
17 | 17 | ## 2. Simplicity First |
18 | 18 |
|
19 | | -**Minimum code solves problem. Nothing speculative.** |
| 19 | +**Min code solve problem. Nothing speculative.** |
20 | 20 |
|
21 | 21 | - No features beyond ask. |
22 | 22 | - No abstractions for single-use code. |
23 | 23 | - No "flexibility" or "configurability" unrequested. |
24 | | -- No error handling for impossible scenarios. |
25 | | -- Write 200 lines, could be 50, rewrite. |
| 24 | +- No error handling for impossible cases. |
| 25 | +- Wrote 200 lines, could be 50, rewrite. |
26 | 26 |
|
27 | | -Ask: "Would senior engineer say overcomplicated?" If yes, simplify. |
| 27 | +Ask: "Would senior engineer call overcomplicated?" Yes, simplify. |
28 | 28 |
|
29 | 29 | ## 3. Surgical Changes |
30 | 30 |
|
31 | | -**Touch only what you must. Clean up only own mess.** |
| 31 | +**Touch only what must. Clean only own mess.** |
32 | 32 |
|
33 | 33 | Editing existing code: |
34 | | -- Don't "improve" adjacent code, comments, formatting. |
35 | | -- Don't refactor unbroken things. |
| 34 | +- No "improve" adjacent code, comments, formatting. |
| 35 | +- No refactor unbroken things. |
36 | 36 | - Match existing style, even if you'd differ. |
37 | | -- Notice unrelated dead code, mention - don't delete. |
| 37 | +- Spot unrelated dead code, mention - no delete. |
38 | 38 |
|
39 | | -Changes create orphans: |
| 39 | +Changes make orphans: |
40 | 40 | - Remove imports/variables/functions YOUR changes made unused. |
41 | | -- Don't remove pre-existing dead code unless asked. |
| 41 | +- No remove pre-existing dead code unless asked. |
42 | 42 |
|
43 | | -Test: Every changed line traces directly to user request. |
| 43 | +Test: every changed line trace to user request. |
44 | 44 |
|
45 | 45 | ## 4. Goal-Driven Execution |
46 | 46 |
|
47 | | -**Define success criteria. Loop until verified.** |
| 47 | +**Define success. Loop until verified.** |
48 | 48 |
|
49 | | -Transform tasks into verifiable goals: |
| 49 | +Turn tasks into verifiable goals: |
50 | 50 | - "Add validation" → "Write tests for invalid inputs, then make them pass" |
51 | 51 | - "Fix the bug" → "Write a test that reproduces it, then make it pass" |
52 | 52 | - "Refactor X" → "Ensure tests pass before and after" |
53 | 53 |
|
54 | | -Multi-step tasks, state brief plan: |
| 54 | +Multi-step task, state brief plan: |
55 | 55 | ``` |
56 | 56 | 1. [Step] → verify: [check] |
57 | 57 | 2. [Step] → verify: [check] |
58 | 58 | 3. [Step] → verify: [check] |
59 | 59 | ``` |
60 | 60 |
|
61 | | -Strong success criteria enable independent loop. Weak criteria ("make it work") require constant clarification. |
| 61 | +Strong criteria = independent loop. Weak criteria ("make it work") = constant clarification. |
62 | 62 |
|
63 | 63 | ## 5. Coding Standards |
64 | 64 |
|
65 | | -- Follow TDD: failing test precedes production logic (red → green → refactor). |
66 | | -- Apply SOLID; can't articulate why change doesn't violate one of five, probably does. |
| 65 | +- TDD: failing test before production logic (red → green → refactor). |
| 66 | +- Apply SOLID; can't say why change no violate one of five, probably does. |
67 | 67 |
|
68 | 68 | --- |
69 | 69 |
|
70 | | -**Guidelines working if:** fewer unnecessary changes in diffs, fewer rewrites from overcomplication, clarifying questions precede implementation, every behavior change ships with passing test. |
| 70 | +**Rules working if:** fewer needless changes in diffs, fewer rewrites from overcomplication, clarifying questions before code, every behavior change ships with passing test. |
0 commit comments