> the operational discipline for AI agents
12-Factor AgentOps
Make each session smarter than the last
AgentOps is the operational discipline for working with AI agents — the principles that turn ad-hoc agent usage into a reliable, compounding practice.
Inspired by The Twelve-Factor App, 12-Factor Agents, and HumanLayer.
The 12 Factors
Context Is Everything
Manage what enters the context window like you manage what enters production.
Track Everything in Git
If it's not in git, it didn't happen.
One Agent, One Job
Each agent gets a scoped task and fresh context. Never reuse a saturated window.
Research Before You Build
Understand the problem space before generating a single line of code.
Validate Externally
No agent grades its own work. Ever.
Lock Progress Forward
Once work passes validation, it ratchets — it cannot regress.
Extract Learnings
Every session produces two outputs — the work product and the lessons learned.
Compound Knowledge
Learnings must flow back into future sessions automatically.
Measure What Matters
Track fitness toward goals, not activity metrics.
Isolate Workers
Each worker gets its own workspace, its own context, and zero shared mutable state.
Supervise Hierarchically
Escalation flows up, never sideways.
Harvest Failures as Wisdom
Failed attempts are data. Extract and index them with the same rigor as successes.
// ready_to_start.sh
Start with Factor I
Begin with context management and build a foundation for reliable AI agents.
Begin Factor I