Skill · doctrine · twelve-factor-agents
Twelve-factor agents
Apply HumanLayer's 12-factor production doctrine to an agent or agentic product. Use when shipping to production, reviewing a design, owning prompts/context/control flow, hitting the 70–80% framework trap, or the user mentions 12-factor, last 20%, stateless reducer, or 'the demo works but customers will wait'.
GET /api/canon/skills/twelve-factor-agents?format=md
Even if models get smarter, these remain — they are software constraints, not model deficiencies. Steal modular concepts into existing software instead of a greenfield rewrite around a README.
When
Someone will pay, wait, or sue. A framework got you a demo. The last 20% is software engineering.
Do
- 01
Name the twelve
1 NL→tools 2 own prompts 3 own the window 4 tools are structured outputs 5 unify state 6 launch/pause/resume 7 humans as tools 8 own control flow 9 compact errors 10 small agents 11 trigger from anywhere 12 stateless reducer.
- 02
Own the three you can print
The prompt, the context builder, and the control flow (factors 2, 3, 8). If you cannot diff them, you do not own them.
- 03
One blob
Business fields and loop fields together. The ticket is the agent state. (state, event) → (newState, effects).
- 04
Refuse the 80% trap
Do not rewrite the company around a framework. Take checkpoints, types, or MCP from a library; keep the reducer.
Don't
- Inherit a black-box prompt from a vendor dashboard.
- Keep execution state and ticket state in two tables that drift.
- Contact humans over a Slack side channel that cannot resume.
Hard rules
- If a design cannot name termination, sandbox, context builder, eval set, and pause API, it is not ready.
- The model proposes; code dispatches and enforces.
- Small agents: few tools, narrow goal, short context.
Refuse
- Unowned prompt — The policy lives in a framework black box you cannot diff, test, or revert.
- HITL that cannot resume — The human answers and the run is gone. Approval as a side channel, not a tool.
- Unbounded loop — No max-turns, token, wall-clock, or money budget. The agent rambles until the bill or the context dies.
- Eval by demo — Architecture first, golden set never. Success is a recorded GIF.
Load with this
Load next
- The agent loopYou need a loop you can pause, inspect, eval, and resume. Frameworks wrap this; they must not own it.
- Durable executionA demo works on your laptop and a customer will wait on it.
- Own the context windowHour two of a task, or any time the transcript is treated as the product.
- Humans as toolsA side effect needs a person, or the agent is missing information only a person has.
Trigger tests
Should fire
- “Review this agent against 12-factor”
- “We're stuck at 80% with LangGraph”
- “How do we own the prompt and the window?”
Should not
- “What is a transformer?”
- “Pick a color palette”