My Agent Rules

This post distills my principles for working with coding agents into a set of concrete rules. It builds on my earlier writings about RSVG and validation systems, and complements my thinking on simple agent architectures.

# 1. Treat the Context Window as a Scarce Resource

Principle Context is precious; spend it deliberately.

Rationale An agent’s context window is its working memory. Output quality degrades as the window fills, yet autonomous value increases with longer uninterrupted runs. Every instruction, file, tool output, and error competes for the same limited space. Repository structure, workflows, and tooling must therefore optimize for maximum usable working memory, not maximal information upfront.

# 2. Prefer Learning Through the Loop Over Front-Loading Instructions

Principle Let agents learn by failing fast, not by memorizing rules.

Rationale Agents run tools in a loop: act → observe → adjust. Deterministic failures (lint errors, type errors, test failures) provide precise, high-signal feedback that teaches the agent immediately. Front-loading large instruction sets wastes context and relies on probabilistic recall. A failed validator is more effective than pages of guidance.

# 3. Every Rejection Is a Missing or Weak Rule

Principle No rejection is allowed to be “just a judgment.”

Rationale Any rejection (test failure, review comment, manual veto, or automated block) must trigger explicit analysis. The first question is always why the change was rejected. The second question must always follow: which rule was violated? (Tests are rules.) If no rule can be named, the system is incomplete. If a rule exists but failed late or unclearly, validation must be tightened or pushed earlier. Every rejection must flow back into clearer rules, stronger validators, or earlier gates.

# 4. Prefer Deterministic Validation Over Probabilistic Judgment

Principle Determinism beats interpretation.

Rationale Hard validators (linters, type checkers, tests, static analysis) produce binary, unambiguous signals that are cheap, fast, and easy for agents to learn from. Soft validators (LLM or human-based judgment) are slower, noisier, and harder to reason about. Use them only where determinism is impossible, and aim to eliminate them over time. See Good Validation Enables Good Agents for a practical walkthrough.

# 5. Push Failure Left

Principle Catch problems as early as possible.

Rationale Earlier failures mean tighter feedback loops and cheaper corrections. Validation should run progressively:

• onSave: formatting (non blocking)
• onStop: linting, type checks
• onCommit: type checks, unit tests
• onPR: integration tests, full verification

Early feedback enables faster learning within the same context window and prevents expensive downstream rewrites.

# 6. Define Clear Scopes with High Fences

Principle Limit what an agent must understand to act safely.

Rationale Scopes define where an agent can operate autonomously, which rules apply, and what context is required. Clear boundaries prevent context explosion and unsafe assumptions. Well-defined scopes also enable parallel execution: agents working in separate scopes can run concurrently with minimal interference or merge conflicts. Feature-based, colocated structures are therefore strongly preferred.

# 7. Co-Locate Context with Code

Principle Context should live where it is needed.

Rationale Rules, documentation, and instructions should be colocated with the code they govern. This reduces discovery cost and enables scoped understanding without loading global knowledge. Colocation is a structural prerequisite for safe autonomy.

# 8. Use Gradual Disclosure Everywhere

Principle Load context incrementally, based on relevance.

Rationale All gradual-disclosure techniques should be employed: directory-based AGENTS.md or CLAUDE.md files, scoped instruction files, skill systems (such as Claude Skills), and dynamic loading of task-relevant resources. The goal is universal: avoid global context dumps and ensure agents ingest only what is necessary for the current scope and task.

# 9. Isolate Token-Expensive Work Using Sub-Agents

Principle Delegate discovery, not responsibility.

Rationale Search, exploration, deep reasoning, and verification are token-expensive. These tasks should run in isolated sub-agent contexts with fresh windows. Only compressed, high-signal results flow back to the coordinator. This preserves the main agent’s context and prevents pollution from failed attempts or dead ends. However, see The Case for Simple Agent Structures for when simple loops outperform complex multi-agent systems.²2Research shows single-agent loops beat multi-agent coordination on sequential reasoning by 39-70%.

# 10. Separate Planning from Execution

Principle Compress before you act.

Rationale Unstructured agent runs accumulate context until quality collapses. Work should be structured into phases that intentionally compress context:

• Research → compressed findings
• Plan → explicit steps and constraints
• Execute → implementation without rediscovery

Each phase refreshes the context window with signal instead of noise.

# 11. Use RSVG as the Validation Backbone

Principle Structure validation around Rules, Scopes, Validators, and Gates.

Rationale RSVG defines what must hold (Rules), where it applies (Scopes), how it is enforced (Validators), and when it is checked (Gates). This structure decouples correctness from any specific model or agent implementation, making the repository agent-agnostic by design. See My Principles for Successful Coding Agents for a detailed explanation of the RSVG mental model.

# 12. Favor Clarity Over Flexibility

Principle Be opinionated.

Rationale Ambiguity is a bug in agent-driven systems. Explicit rules, strict validation, and clear boundaries outperform flexible but implicit conventions. Constraints reduce cognitive load, shrink context needs, and produce more reliable outcomes for humans and agents alike.

- Jan Willem