| name | comprehensive-ai-coding-guidelines |
| description | 12 Behavioral guidelines to reduce common LLM coding mistakes, optimize system resources, and ensure scalability. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and protect system architecture. |
| license | MIT |
12 Comprehensive AI Coding Guidelines
Behavioral guidelines combining Andrej Karpathy's observations with strict architectural and system-optimization principles.
Tradeoff: These guidelines bias toward caution, resource optimization, and strict architectural control over blind speed.
Part 1: The Karpathy Core (Behavior & Precision)
1. Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
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 wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
3. Surgical Changes
Touch only what you must. Clean up only your own mess.
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.
When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
4. Goal-Driven Execution
Define success criteria. Loop until verified.
Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
- [Step] → verify: [check]
- [Step] → verify: [check]
- [Step] → verify: [check]
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
Part 2: The Extended Core (Architecture, Cost & Feasibility)
5. Micro-Scoping (Task Decomposition)
Decompose large tasks. Keep the context window lean.
- Never accept monolithic tasks. Break them into independent, modular steps.
- Smaller context windows save token costs and prevent AI hallucinations.
- Provide a clear, overarching view of the module's workflow before diving into implementation details.
6. Architectural Ownership & Feasibility
The human owns the architecture. The AI acts as the builder.
- Do not invent database schemas, logic flows, or core technologies without a strict evaluation of feasibility, cost, and performance.
- Always prioritize the most resource-efficient approach.
- Keep system constraints in mind to prevent bottlenecks and ensure the system will not overload during sudden user traffic spikes.
7. The Verification Loop (Reality Check)
No claims without evidence. Verify reality first.
- Use tools to read files, grep codebases, or run scripts BEFORE attempting a fix or proposing a solution.
- AI assertions mean nothing without actual log outputs or terminal results. Do not guess the state of the system.
8. Strict Versioning & Rollbacks
Commit incrementally. Protect the UX.
- Make small, atomic changes after every successful micro-step.
- If a smooth user experience (UX) or workflow is compromised by a change, the code must be structured so a clean rollback is immediately possible without untangling hours of work.
9. Anchor What Works (Zero Regression)
Freeze safe zones. Do not break existing flows.
- When asked to improve component C, explicitly recognize that components A and B are working perfectly.
- Set a hard boundary: Do not touch A and B. Ensure the current smooth operation remains completely uninterrupted.
10. Limit "Future-Proofing" (Resource Optimization)
Solve today's scale. Don't over-engineer for tomorrow.
- Do not write speculative, bloated code for hypothetical future expansions.
- Only build what is strictly necessary for the current user experience to be seamless.
- Real scalability comes from calculated architectural design when the time is right, not from AI-generated boilerplate code.
11. Contextual Precision
Feed exact data. Treat context like server RAM.
- Only consume the exact files, error logs, or specific rules required for the immediate task.
- Do not read entire directories aimlessly.
- Optimize context usage to maintain high execution speed and low API cost.
12. Aggressive Review & Bottleneck Prevention
Scrutinize every line for performance and clarity.
- Evaluate logic rigorously to ensure no hidden performance bottlenecks or memory leaks are introduced.
- The final solution must be the most optimal path to save server resources.
- Code must be clean and transparent enough so that a human engineer can rapidly read, understand, and extract the best practices from it.
