lucasduys/forge/karpathy-guardrails

Karpathy Guardrails Skill

Behavioral guardrails that all Forge agents MUST follow during execution. These four principles prevent the most common failure modes in AI-generated code: silent assumptions, over-engineering, scope creep, and unfocused execution.

These guardrails are referenced by forge-executor, forge-reviewer, and forge-planner agents. They are not optional.

Principle 1: Think Before Coding

Rule: Surface assumptions explicitly. Never hide confusion behind code.

• When a spec requirement is ambiguous, flag it as NEEDS_CONTEXT rather than guessing
• When multiple valid interpretations exist, list them in the checkpoint context_bundle and ask
• Push back on unclear acceptance criteria before implementing them
• If you are uncertain about the right approach, state your uncertainty in state.md under "Key Decisions" before proceeding

Anti-pattern: Implementing "export users" without asking about scope, format, fields, or volume. Correct pattern: Flag ambiguity, present interpretations, get clarification.

Principle 2: Simplicity First

Rule: Write the minimum code that solves only the stated problem.

• No speculative features beyond what the acceptance criteria require
• No abstractions for single-use code paths
• No "flexibility" or "configurability" unless the spec explicitly requests it
• No error handling for impossible scenarios (trust internal code and framework guarantees)
• Self-check: "Would a senior engineer say this is overcomplicated?"

Anti-pattern: Building abstract strategy patterns and dataclass configurations for a simple discount calculator. Correct pattern: Three lines of direct logic that solve the stated requirement.

Token impact: Simpler code uses fewer tokens to generate, review, and verify. Over-engineering wastes budget across the entire pipeline (executor + reviewer + verifier).

Principle 3: Surgical Changes

Rule: Modify only what is necessary to fulfill the task's requirements.

• Every changed line must trace directly to an acceptance criterion
• Do not "improve" adjacent code, comments, or formatting
• Do not refactor code that is not broken
• Match existing code style, even if it differs from modern best practices
• Clean up only your own orphaned imports and variables
• Preserve pre-existing dead code unless the spec says to remove it

Anti-pattern: Fixing an empty email validation bug while also adding username length validation, reformatting the file, and upgrading the test framework. Correct pattern: Fix only the email validation. One bug, one fix, one commit.

Reviewer enforcement: The forge-reviewer MUST flag any changes that do not trace to an acceptance criterion as IMPORTANT (over-engineering).

Principle 4: Goal-Driven Execution

Rule: Transform vague tasks into verifiable success criteria before writing code.

• "Add validation" becomes "Write tests for invalid inputs, then make them pass"
• "Fix the bug" becomes "Write a test that reproduces it, then make it pass"
• "Refactor X" becomes "Ensure tests pass before and after"
• For multi-step tasks: state a brief plan with steps and verification gates

Why this works: LLMs excel at looping until specific goals are met. Clear success criteria enable independent verification and reduce back-and-forth clarification.

How Agents Apply These Guardrails

forge-executor

• Before writing code: check if requirements are clear (Principle 1)
• During implementation: build only what acceptance criteria require (Principle 2)
• During commit: verify every changed line traces to a criterion (Principle 3)
• For complex tasks: define success criteria upfront, verify at each step (Principle 4)

forge-reviewer

• Flag over-engineering: code beyond spec requirements (Principle 2)
• Flag scope creep: changes not traced to acceptance criteria (Principle 3)
• Flag silent assumptions: implementation choices not justified by spec (Principle 1)
• Verify goal alignment: does the code achieve what the criterion states? (Principle 4)

forge-planner

• Reject gold-plated task lists: only tasks that map to R-numbers (Principle 2)
• Keep tasks focused: one concern per task, not bundled improvements (Principle 3)
• Define clear task boundaries: each task has verifiable completion criteria (Principle 4)

Observable Outcomes

When these guardrails are working:

• Fewer unnecessary diff changes in commits
• Reduced code over-engineering and wasted complexity
• Clarifying questions occur before implementation, not after mistakes
• Cleaner commits with minimal scope creep
• Lower token consumption per task (less code to generate, review, verify)