RUNBOOK.md + DECISIONS.md: Production Agent Template Clinic

Production agent systems fail when intent, authority, context, and evidence stay implicit. The AgentAtlas Template Clinic turns two reviewed project files into a practical working session each week. The rotation is deterministic and sponsorship-independent: it selects from the maintained Starter Kit, follows the related primary sources, and never asks a model to invent new requirements.

This edition covers **RUNBOOK.md** and **DECISIONS.md**. Treat them as connected controls rather than paperwork. Each file should answer a decision another person or agent will genuinely face, and each important statement should point to an owner, source, artifact, or executable check.

1. RUNBOOK.md: Agent operations runbook

Give operators a tested path from alert to diagnosis, containment, rollback, recovery, communication, and follow-up using the signals and failure modes of the complete agent workflow.

**Use this decision rule:** Write a runbook for failures that require timely coordinated action or specialized diagnosis. Keep routine automatic recovery in the system and record its limits here.

The downloadable [RUNBOOK.md template](/starter-kit/operations-runbook) is organized around four evidence-bearing sections. Replace its prompts with current project facts; remove fields that do not apply rather than preserving generic boilerplate.

Service ownership and dependencies

Make the operating boundary and escalation path available before an incident.

• **Owners:** List primary, secondary, security, data, product, and vendor contacts.
• **Dependencies:** List models, tools, queues, databases, auth, providers, and critical limits.
• **Environments:** List production, staging, regions, release identifiers, and access procedure.

Signals and diagnosis

Connect every alert to a workflow stage, user impact, and known failure mode.

• **Service indicators:** Define completion, correctness, safety, latency, cost, and availability signals.
• **Dashboards and traces:** Link workflow, model, tool, queue, authorization, and business views.
• **Diagnostic sequence:** List the fastest read-only checks and evidence to preserve.

Containment and recovery

Provide exact reversible actions with authority and stop conditions.

• **Contain:** Define feature disablement, permission revocation, queue pause, isolation, and traffic controls.
• **Rollback:** Define code, configuration, prompt, model, schema, and data rollback.
• **Recover:** Define validation, replay, reconciliation, re-enable order, and customer remediation.

Communication and learning

Keep stakeholders informed and convert failures into maintained controls.

• **Updates:** Define internal, user, vendor, legal, and regulatory communication owners and cadence.
• **Closure evidence:** State the signals and reviewers required to close the incident.
• **Follow-up:** Add eval cases, tasks, architecture decisions, documentation, and owner deadlines.

Before calling RUNBOOK.md complete, ask a reviewer to trace its claims to the relevant specification, decision, task, test, trace, or owner. The file should reduce rediscovery and ambiguity during real work, not merely describe an ideal process.

**Primary references:** [Running agents](https://openai.github.io/openai-agents-python/running_agents/) · [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) · [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) · [Human-in-the-loop](https://openai.github.io/openai-agents-python/human_in_the_loop/) · [Configure permissions](https://code.claude.com/docs/en/permissions).

2. DECISIONS.md: Architecture decision log

Keep important product, model, architecture, data, protocol, safety, and operating decisions traceable to context, alternatives, evidence, consequences, owners, and review triggers.

**Use this decision rule:** Record a decision when reversing it later would be costly, when multiple teams or agents depend on it, or when the tradeoff cannot be understood from code alone.

The downloadable [DECISIONS.md template](/starter-kit/decision-log) is organized around four evidence-bearing sections. Replace its prompts with current project facts; remove fields that do not apply rather than preserving generic boilerplate.

Decision index

Make active, proposed, superseded, and rejected decisions easy to discover.

• **Identifier:** Assign a stable ADR or decision number and short title.
• **Status:** Mark proposed, accepted, deprecated, superseded, or rejected.
• **Ownership:** Name decider, consulted reviewers, date, and affected systems.

Decision record

Capture the decision in enough context to understand it later.

• **Context:** Describe the problem, constraints, forces, and urgency.
• **Decision:** State what is being chosen and the scope of that commitment.
• **Consequences:** List benefits, costs, risks, follow-up work, and compatibility impact.

Alternatives and evidence

Show why the choice was reasonable without pretending uncertainty disappeared.

• **Alternatives:** List viable options, including keeping the current state.
• **Evaluation:** Compare options against explicit product, quality, safety, cost, and operating criteria.
• **Evidence:** Link prototypes, benchmarks, evals, incidents, primary sources, and stakeholder input.

Review and supersession

Define when new evidence requires the decision to be revisited.

• **Review triggers:** Name thresholds, incidents, provider changes, scale, cost, or regulatory events.
• **Review date:** Set a date when uncertainty or change rate makes scheduled review useful.
• **Supersession:** Link the replacement decision and migration or cleanup work without rewriting history.

Before calling DECISIONS.md complete, ask a reviewer to trace its claims to the relevant specification, decision, task, test, trace, or owner. The file should reduce rediscovery and ambiguity during real work, not merely describe an ideal process.

**Primary references:** [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) · [A2A protocol specification](https://a2a-protocol.org/latest/specification/) · [AGENTS.md specification](https://agents.md/) · [GitHub Spec Kit](https://github.github.com/spec-kit/index.html) · [Codex security](https://developers.openai.com/codex/security) · [GPT-5.4 model guide](https://developers.openai.com/api/docs/models/gpt-5.4) · [Claude prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices).

Use the two files together

Start with the file that owns the earlier decision in your workflow, then let its accepted outputs constrain the second. Link them explicitly in both directions. If the files disagree, fix the artifact that owns the decision instead of adding compensating prose downstream.

Run one representative task using only the documented inputs. Record what the agent or teammate still had to rediscover, which instruction was ambiguous, and which claimed check could not be reproduced. Tighten the smallest relevant field, repeat the task, and keep the version that measurably reduces correction or uncertainty.

Review and freshness policy

Both templates are generated from the same reviewed data as the [Production Agent Starter Kit](/starter-kit). The generator rebuilds the Markdown files, consolidated bundle, and SHA-256 manifest whenever approved records change. Structural checks require complete lifecycle coverage, valid topic links, substantive prompts, primary references, valid Skill frontmatter, and matching file hashes.

Official repository activity is treated as a review signal rather than proof that behavior changed. The [content status map](/content-status) identifies which topics and templates are affected by a monitored upstream change. If source dates move beyond the 30-day review window, automation opens a review issue and blocks stale publishing until an editor verifies the guidance.