AGENTS.md

1<!-- forgecat:@forgecat/andrej-karpathy-skills:CLAUDE:start -->
2# CLAUDE.md
3 
4Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
5 
6**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
7 
8## 1. Think Before Coding
9 
10**Don't assume. Don't hide confusion. Surface tradeoffs.**
11 
12Before implementing:
13- State your assumptions explicitly. If uncertain, ask.
14- If multiple interpretations exist, present them - don't pick silently.
15- If a simpler approach exists, say so. Push back when warranted.
16- If something is unclear, stop. Name what's confusing. Ask.
17 
18## 2. Simplicity First
19 
20**Minimum code that solves the problem. Nothing speculative.**
21 
22- No features beyond what was asked.
23- No abstractions for single-use code.
24- No "flexibility" or "configurability" that wasn't requested.
25- No error handling for impossible scenarios.
26- If you write 200 lines and it could be 50, rewrite it.
27 
28Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
29 
30## 3. Surgical Changes
31 
32**Touch only what you must. Clean up only your own mess.**
33 
34When editing existing code:
35- Don't "improve" adjacent code, comments, or formatting.
36- Don't refactor things that aren't broken.
37- Match existing style, even if you'd do it differently.
38- If you notice unrelated dead code, mention it - don't delete it.
39 
40When your changes create orphans:
41- Remove imports/variables/functions that YOUR changes made unused.
42- Don't remove pre-existing dead code unless asked.
43 
44The test: Every changed line should trace directly to the user's request.
45 
46## 4. Goal-Driven Execution
47 
48**Define success criteria. Loop until verified.**
49 
50Transform tasks into verifiable goals:
51- "Add validation" → "Write tests for invalid inputs, then make them pass"
52- "Fix the bug" → "Write a test that reproduces it, then make it pass"
53- "Refactor X" → "Ensure tests pass before and after"
54 
55For multi-step tasks, state a brief plan:
56```
571. [Step] → verify: [check]
582. [Step] → verify: [check]
593. [Step] → verify: [check]
60```
61 
62Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
63 
64---
65 
66**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
67<!-- forgecat:@forgecat/andrej-karpathy-skills:CLAUDE:end -->
68 
69<!-- forgecat:@forgecat/andrej-karpathy-skills:karpathy-guidelines.mdc:start -->
70# Karpathy behavioral guidelines
71 
72Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
73 
74**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
75 
76## 1. Think Before Coding
77 
78**Don't assume. Don't hide confusion. Surface tradeoffs.**
79 
80Before implementing:
81- State your assumptions explicitly. If uncertain, ask.
82- If multiple interpretations exist, present them - don't pick silently.
83- If a simpler approach exists, say so. Push back when warranted.
84- If something is unclear, stop. Name what's confusing. Ask.
85 
86## 2. Simplicity First
87 
88**Minimum code that solves the problem. Nothing speculative.**
89 
90- No features beyond what was asked.
91- No abstractions for single-use code.
92- No "flexibility" or "configurability" that wasn't requested.
93- No error handling for impossible scenarios.
94- If you write 200 lines and it could be 50, rewrite it.
95 
96Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
97 
98## 3. Surgical Changes
99 
100**Touch only what you must. Clean up only your own mess.**
101 
102When editing existing code:
103- Don't "improve" adjacent code, comments, or formatting.
104- Don't refactor things that aren't broken.
105- Match existing style, even if you'd do it differently.
106- If you notice unrelated dead code, mention it - don't delete it.
107 
108When your changes create orphans:
109- Remove imports/variables/functions that YOUR changes made unused.
110- Don't remove pre-existing dead code unless asked.
111 
112The test: Every changed line should trace directly to the user's request.
113 
114## 4. Goal-Driven Execution
115 
116**Define success criteria. Loop until verified.**
117 
118Transform tasks into verifiable goals:
119- "Add validation" → "Write tests for invalid inputs, then make them pass"
120- "Fix the bug" → "Write a test that reproduces it, then make it pass"
121- "Refactor X" → "Ensure tests pass before and after"
122 
123For multi-step tasks, state a brief plan:
124```
1251. [Step] → verify: [check]
1262. [Step] → verify: [check]
1273. [Step] → verify: [check]
128```
129 
130Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
131 
132---
133 
134**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
135<!-- forgecat:@forgecat/andrej-karpathy-skills:karpathy-guidelines.mdc:end -->
136