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.
Want the guided overview first? Start with the Engineering principles feature guide.
Adapted from Andrej Karpathy’s skills (MIT). The full checklist lives in the .claude/skills/karpathy-guidelines/SKILL.md skill in the 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 your change 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.md skill is the loop; and the brain (.claude/brain/decisions.md, errors.md, anti-patterns.md) is the memory that helps the next session avoid repeating the same drift.