Agent-Era Codebase Principles

Below an updated list of principles I try to follow when working with coding agents, sharpened and regrouped from my earlier post.

# What to optimize for

# 1. Human attention is scarce

The repo should reduce what the human has to inspect manually. Review should focus on judgment, not rediscovering whether basic requirements were met.

# 2. Agent context is scarce

Do not spend the context window on instructions that can be enforced elsewhere. Keep context small, scoped, and relevant.

# 3. System stability is scarce

Models, tools, dependencies, harnesses, and best practices churn quickly. The codebase must survive change by making its contracts explicit and portable.

# 4. Code is cheap; trust is expensive

The bottleneck is no longer producing code, but knowing whether generated code is correct, aligned, maintainable, and safe to merge.

# 5. The deliverable is code, proof, and harness alignment

A diff is incomplete without evidence that it works and evidence that the validation harness still matches the codebase it claims to protect.

# 6. Code, docs, plans, and validator output are written for both humans and agents

Everything important should be legible to both readers. Neither audience should be optimized for at the expense of the other.

# Structure (Boundaries)

# 7. Consistency of code is a first-class goal

The same problem should be solved the same way across files, projects, and languages unless there is an explicit reason not to.

# 8. Architecture is code

Structural constraints, import boundaries, scopes, and conventions should be enforced by checked code where possible, not by memory or prose alone.

# 9. Clear boundaries make autonomy possible

Modules, scopes, entrypoints, runtimes, and handovers need names and edges that humans and agents can understand.

# 10. Modularity makes strictness affordable

Strict rules are easier to enforce, adjust, or remove when they apply to small scopes. Global strictness becomes slow, noisy, and brittle.

# 11. Use thin entrypoints around reusable core logic

CLI, API, package, UI, or agent surfaces should stay thin. The core should remain reusable and testable across entrypoints.

# Validation (RSVG)

# 12. Conventions only matter when they are explicit

Hidden preferences do not guide agents. A convention exists when it can be represented as RSVG: rule, scope, validator, gate.

# 13. Prefer deterministic over probabilistic over human validation

Push every check as far down that ladder as the domain allows, while accepting that some validators will remain probabilistic.

# 14. Rules are what, scopes are where, validators are how, gates are when

Validators can be deterministic or probabilistic. Gates are lifecycle moments. Strictness is a property of enforcement, not of whether RSVG exists.

# 15. Push failure left, but respect gate budgets

Catch problems at the earliest affordable gate. Earlier is better only when the check is fast, clear, and worth the loop cost.

# 16. All code modifications go through gates

The exact gate timeline is project-dependent, but no change should reach main without validation.

# 17. Validation output should serve both the agent loop and human review

A failed check should teach the agent what to fix and give the human a compact, trustworthy review artifact.

# Process (enforcement of alignment)

# 18. Configuration is code

Agent config, hooks, skills, sub-agents, tool config, and infrastructure config belong in version control alongside the code they affect.

# 19. The codebase owns the harness contract

Rules, scopes, validators, gates, and proof obligations should live in the repo. Agent-specific systems are adapters, not the source of truth.

# 20. Manifests describe the repo’s operating contract

A project should record its composition, scopes, rules, validators, gates, proof obligations, and active harness adapters.

# 21. The harness validates code and its own alignment

Validators, gates, manifests, and adapters must stay in sync with the repo. Otherwise strictness becomes lock-in or theater.

# 22. Every rejection is a harness signal

A rejected output should be classified: missing rule, weak validator, late gate, broad scope, insufficient proof, stale harness, or bad rule.

# 23. Traceable handover contracts are required

Every handoff between human, agent, gate, reviewer, or future session should leave a durable artifact the next actor can pick up from.

# 24. The harness is production code

Validators, orchestrators, gate runners, transformers, and adapters should meet the same quality bar as application code.

# Practical (tool selection)

# 25. Use open standards wherever possible

Markdown, AGENTS.md, JSON Schema, OCI, plain-text configs, lockfiles, and portable manifests outlast specific vendors and travel between tools.

# 26. Prefer understandable, lightweight systems

Compact, simple code and low-overhead tools reduce both human review burden and agent context cost.

# 27. Prefer fast, local, deterministic, CLI-first tools

Tools should be cheap enough to run often, scriptable enough for agents, and transparent enough to debug.

# 28. Prefer lockfiles and reproducible environments

Reproducibility is part of validation. The same repo state should produce the same checks locally and in CI.

# 29. Choose stacks by entrypoint, runtime, and proof needs

Python, Go, Swift, TypeScript, monorepos, Docker, local runtimes, APIs, CLIs, packages, and agents are downstream choices.

# 30. Use Go and Rust-style binaries where the harness benefits from fast startup and easy distribution

Especially for repo tooling, gate runners, scaffolders, and portable validation infrastructure.

This list is a living document with personal preferences, not an absolute truth. Feedback is welcome.

- Jan Willem