Docs · Engineering principles
The four principles for disciplined AI coding
AI agents fail in predictable ways: they pick one interpretation silently and run with it; they over-engineer single-use code; they “improve” adjacent code that wasn’t broken; they declare victory without verifying. RepoOps applies four engineering principles to every code-writing turn to keep that drift in check. Each principle has a named test - the question that decides whether the change passed or failed.
Adapted from Andrej Karpathy’s skills (MIT). The full checklist lives in the .claude/skills/karpathy-guidelines/SKILL.md file shipped with every RepoOps repo; this page is the user-facing summary.
1. Think Before Coding
Don’t assume. Don’t hide confusion. Surface tradeoffs.
- State assumptions explicitly - if uncertain, ask rather than guess.
- Present multiple interpretations when the request is ambiguous; lay out the options and the tradeoff instead of silently picking one.
- Push back when a simpler approach exists.
- Stop when confused - name what’s unclear and ask, instead of producing confident-sounding output you can’t defend.
The test: did the agent surface its uncertainty, or did it pick silently and run?
2. Simplicity First
The 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 200 lines could be 50, rewrite it.
The test: would a senior engineer call this overcomplicated? RepoOps house rule - three similar lines beat a premature abstraction.
3. Surgical Changes
Touch only what you must. Clean up only your own mess.
- Don’t “improve” adjacent code, comments, or formatting.
- Don’t refactor things that aren’t broken.
- Match the existing style, even if you’d do it differently.
- Remove imports / variables / functions that yourchange made unused; leave pre-existing dead code alone (flag it, don’t delete it).
The test:every changed line traces directly to the user’s request. The mechanical guardrail in RepoOps: stage by explicit path, never git add -A.
4. Goal-Driven Execution
Define success criteria. Loop until verified.
Transform imperative tasks into verifiable goals:
| Instead of… | Transform to… |
|---|---|
| “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 the tests pass before and after.” |
The test: can the agent point at a concrete verification (a test, a CI gate, a boot smoke check) that confirms the change works?
How RepoOps applies these
Every shipped feature follows the same orient → plan → build → verify → PR loop. The principles above set the posture; the .claude/skills/ship-feature/SKILL.mdskill is the loop; the brain —.claude/brain/decisions.md, errors.md, anti-patterns.md— is the memory that prevents the same drift twice.