ClaudeMap

12-Factor Agents

HumanLayer's 12 design principles for production-grade LLM agents — the closest thing to a 'best practices' manifesto.

Tutorials & Guidesagentsbest-practicesproductionprinciples

12-Factor Agents is HumanLayer's opinionated manifesto for building production-grade LLM agents. It distils hard-won lessons into 12 principles: own your prompts, own your context window, design for stateless redeploys, and so on. The closest thing the ecosystem has to a 'best practices' document.

What it does

  • 12 design principles for production-grade LLM agents from HumanLayer — the closest thing to a best-practices manifesto
  • Covers context ownership, tool design, state management, and human escalation
  • Written from production agent experience, not theory

When to use it

Read it before shipping your first serious agent — each factor is a checklist item that converts post-launch incidents into pre-launch design decisions.

Getting started

No install — read the principles in the repository. Each factor has its own markdown chapter.

Things to know

Opinionated principles, not a spec — they assume tool-calling agent architectures. Apply them with judgment; not every factor fits every stack.

Repository

humanlayer/12-factor-agents

Charted

Related on the map

  • Anthropic's canonical essay on agent design — workflows vs agents, and five composable patterns.

    • official
    • agents
    • engineering
    • patterns
  • Official curated registry of MCP servers — discovery, versioning, and metadata for the ecosystem.

    • official
    • mcp
    • registry
    • discovery