Skip to content

Commit ac29c0c

Browse files
committed
feat(agents): absorb Karpathy LLM coding guidelines into AGENTS.md and skills
Absorb behavioral patterns from andrej-karpathy-skills project to reduce common agent coding mistakes, without changing core workflow. AGENTS.md: - Add 'Behavioral Guidelines' section with 4 principles: - Think Before Coding: surface assumptions, ask before assuming - Simplicity First: anti-overengineering, YAGNI for abstractions - Surgical Changes: no drive-by refactoring, match existing style - Goal-Driven Execution: vague-to-verifiable task transformation skills/pb-build/SKILL.md: - Add anti-pattern quick reference table (6 patterns) for Evaluator skills/pb-test-driven-development/SKILL.md: - Add 'Bug Fix: Reproduce First' example (RED exposes bug, GREEN fixes) skills/pb-systematic-debugging/SKILL.md: - Add concrete Phase 1 example: wrong (symptom patch) vs right (root cause)
1 parent acfe207 commit ac29c0c

4 files changed

Lines changed: 125 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,70 @@ cachetools >= 7.0.5
194194
- Mixing unrelated changes: keep one logical change per commit.
195195
- Using `# type: ignore` without a specific error code and justification comment.
196196

197+
## Behavioral Guidelines
198+
199+
Adapted from [Karpathy's LLM coding observations](https://x.com/karpathy/status/2015883857489522876). These reduce common agent coding mistakes.
200+
201+
### Think Before Coding
202+
203+
Don't assume. Don't hide confusion. Surface tradeoffs.
204+
205+
- State assumptions explicitly. If uncertain, ask.
206+
- If multiple interpretations exist, present them — don't pick silently.
207+
- If a simpler approach exists, say so. Push back when warranted.
208+
- If something is unclear, stop. Name what's confusing. Ask.
209+
210+
**Self-check:** "Did I list my assumptions before coding?"
211+
212+
### Simplicity First
213+
214+
Minimum code that solves the problem. Nothing speculative.
215+
216+
- No features beyond what was asked.
217+
- No abstractions for single-use code.
218+
- No "flexibility" or "configurability" that wasn't requested.
219+
- No error handling for impossible scenarios.
220+
- If you write 200 lines and it could be 50, rewrite it.
221+
222+
**Self-check:** "Would a senior engineer say this is overcomplicated?"
223+
224+
### Surgical Changes
225+
226+
Touch only what you must. Clean up only your own mess.
227+
228+
When editing existing code:
229+
230+
- Don't "improve" adjacent code, comments, or formatting.
231+
- Don't refactor things that aren't broken.
232+
- Match existing style, even if you'd do it differently.
233+
- If you notice unrelated dead code, mention it — don't delete it.
234+
235+
When your changes create orphans:
236+
237+
- Remove imports/variables/functions that YOUR changes made unused.
238+
- Don't remove pre-existing dead code unless asked.
239+
240+
**Self-check:** "Does every changed line trace to the user's request?"
241+
242+
### Goal-Driven Execution
243+
244+
Define success criteria. Loop until verified.
245+
246+
Transform tasks into verifiable goals:
247+
248+
- "Add validation" → "Write tests for invalid inputs, then make them pass"
249+
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
250+
- "Refactor X" → "Ensure tests pass before and after"
251+
252+
For multi-step tasks, state a brief plan:
253+
```
254+
1. [Step] → verify: [check]
255+
2. [Step] → verify: [check]
256+
3. [Step] → verify: [check]
257+
```
258+
259+
**Self-check:** "Can I verify this change succeeded without asking the user?"
260+
197261
## Development Workflow
198262

199263
When fixing failures, identify root cause first, then apply idiomatic fixes instead of suppressing warnings or patching symptoms.

skills/pb-build/SKILL.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -551,6 +551,21 @@ Use `- [ ]` and `- [x]` inside the task block as evidence checkboxes, not as a s
551551

552552
---
553553

554+
## Anti-Pattern Quick Reference
555+
556+
The Evaluator should watch for these common agent mistakes:
557+
558+
| Anti-Pattern | Example | Correct Behavior |
559+
|---|---|---|
560+
| **Drive-by refactoring** | Fixing a bug but also reformatting adjacent code, adding type hints nobody asked for | Only change lines that fix the reported issue |
561+
| **Over-abstraction** | Strategy pattern + ABC + config class for a single `calculate_discount()` function | One function until complexity is actually needed |
562+
| **Silent assumptions** | Implementing "export users" without clarifying scope, format, fields | List assumptions, ask for clarification |
563+
| **Speculative features** | Adding caching, validation, notifications to a "save preferences" request | Build only what was asked; add later when needed |
564+
| **Vague success criteria** | "I'll review and improve the code" | "Write test for bug X → make it pass → verify no regressions" |
565+
| **Style drift** | Changing quote style, whitespace, or return logic while adding logging | Match existing code style exactly |
566+
567+
---
568+
554569
## Key Principles
555570

556571
1. **Small, focused, sequential, independent.** Each task is self-contained.

skills/pb-systematic-debugging/SKILL.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,21 @@ You MUST complete each phase before proceeding to the next.
130130
- Keep tracing up until you find the source
131131
- Fix at source, not at symptom
132132

133+
**Example — Wrong vs Right:**
134+
135+
```
136+
User reports: "Empty emails crash the validator"
137+
138+
Wrong: Immediately patches validate_user() to handle empty strings.
139+
→ May fix symptom, may not fix root cause.
140+
141+
Right:
142+
1. Reproduce: call validate_user({'email': ''}) → confirms crash
143+
2. Trace: empty string → splits on '@' → IndexError
144+
3. Root cause: no guard before string operation
145+
4. Minimal fix: add empty check before split
146+
```
147+
133148
### Phase 2: Pattern Analysis
134149

135150
**Find the pattern before fixing:**

skills/pb-test-driven-development/SKILL.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,37 @@ Vague name, tests mock not code.
102102
- Clear name
103103
- Real code (no mocks unless unavoidable)
104104

105+
### Bug Fix: Reproduce First
106+
107+
For bugs, the RED phase doubles as a reproducer. Don't fix without confirming the bug exists.
108+
109+
**User reports:** "Sorting breaks when there are duplicate scores"
110+
111+
**Wrong:** Immediately changes sort logic.
112+
113+
**Right:**
114+
```python
115+
# 1. RED: Write test that exposes the bug
116+
def test_sort_with_duplicate_scores():
117+
scores = [
118+
{'name': 'Alice', 'score': 100},
119+
{'name': 'Bob', 'score': 100},
120+
{'name': 'Charlie', 'score': 90},
121+
]
122+
result = sort_scores(scores)
123+
assert result[0]['score'] == 100
124+
assert result[1]['score'] == 100
125+
assert result[2]['score'] == 90
126+
127+
# Verify RED: run 10 times → inconsistent ordering → bug confirmed
128+
129+
# 2. GREEN: Fix with stable sort
130+
def sort_scores(scores):
131+
return sorted(scores, key=lambda x: (-x['score'], x['name']))
132+
133+
# Verify GREEN: test passes consistently
134+
```
135+
105136
### Verify RED - Watch It Fail
106137

107138
**MANDATORY. Never skip.**

0 commit comments

Comments
 (0)