ADR: agent, fixed workflow or person?

Use it when someone proposes an agent for a task, before anyone builds anything. An ADR (architecture decision record) keeps a decision and its reasons. The outcome can be a fixed workflow or a person.
The template asks you to do five things:
Answer six questions about the task.
Mark the trifecta: untrusted content, sensitive data and outward actions in the same session.
Review what you can undo.
Write down how you will evaluate.
Write down what it will cost.
Copy the block with the button in its corner, or open the file on GitHub.
# ADR-[number]: [task]: agent, fixed workflow or person?

<!--
How to use this template:
- An ADR (architecture decision record) keeps a decision and its reasons.
- Write it before you build. Keep it in the repository, for example in docs/adr/.
- Fill in every field in brackets. Delete these comments when you finish.
- Format: MADR (Markdown Architectural Decision Records), adapted for agents.
-->

- Status: [proposed | accepted | superseded by ADR-___]
- Date: [YYYY-MM-DD]
- Decider: [name and role of the accountable person]
- Consulted: [security, data protection, the team that does the task today]

## Context

<!-- Describe the task as a person does it today. One concrete problem, not an "agent platform". -->

- Task: [what goes in, what comes out]
- Who does it today and how long it takes: [role, minutes per case]
- Volume: [cases per month]
- Cost of a mistake today: [what happens and what it costs]

## The questions that decide

| Question | Answer | What it tells you |
|---|---|---|
| Can you write down the steps and branches in advance? | [yes / no] | If yes, a fixed workflow is enough. |
| Are the inputs ambiguous (free text, varied documents)? | [yes / no] | If not, you don't need a model. |
| If it gets it wrong, is the mistake cheap and reversible, costly but reversible, or irreversible? | [...] | Irreversible actions stay with a person or behind an approval. |
| How many chained steps does the task have? | [n] | At 95% success per step, 10 steps succeed 60% of the time. |
| Do you have at least 20 real cases to evaluate with? | [yes / no] | Without real cases, you can't decide yet. |
| Who reviews, and how much time do they have? | [role, minutes per case] | A reviewer without time turns approval into a rubber stamp. |

## Trifecta (rule of two)

<!--
The trifecta is three conditions that together let an attacker steal data.
Tick each condition that holds within one agent session.
If you tick all three, the agent can't run on its own. Cut one of the three,
or add a human approval bound to the exact action. Details in mapa-de-amenazas.md.
Any request to a URL counts as an external action, the same as a message.
For example: a search, a fetch, a markdown image, a link that gets previewed
or a trace sent to a third-party tool.
-->

- [ ] It reads untrusted content (emails, web pages, tickets, customer files, third-party tool descriptions).
- [ ] It accesses sensitive or personal data.
- [ ] It acts externally or changes state (sends messages, requests a URL, pays, publishes, deletes, edits data).

Condition we cut and how: [...]
Actions that need human approval: [...]

## Reversibility

<!-- One row for each action the agent can take. What can't be undone stays with a person or behind an approval. -->

| Action | If it goes wrong, can it be undone? | How it is undone and how long it takes | Level in the policy |
|---|---|---|---|
| [e.g. create a refund] | [no, the money is gone] | [ask the customer to return it, days] | [confirm] |
| [...] | [...] | [...] | [...] |

## Options considered

1. Fixed workflow: deterministic code (it always does the same thing with the same input). If needed, a model does one bounded step.
2. Narrow agent: one task, few tools, least privilege (only the permissions the task needs), budget with a hard stop.
3. Agent with human approval on risky actions.
4. Person, with or without AI help.

## Decision

We chose [option] because [reason tied to the questions above].

## Evaluation before launch

<!-- pass^k: the probability that k attempts at the same task all succeed. -->

- Evaluation plan: [link to plan-de-evaluacion.md]
- Exit criterion: pass^[k] of at least [__]% on [n] tasks.
- Rollback criterion: [metric, threshold, who decides].

## Cost

- Estimated cost per successful task: [__] (see ficha-de-costo.md).
- Cost of the task today (person or fixed workflow): [__].
- Daily budget with automatic cutoff: [__].

## Consequences

- Good: [...]
- Bad, and risks we accept: [...]
- Date we revisit this decision: [YYYY-MM-DD]

## Why this is here

- If you can write the steps in advance, write them in code, not in the prompt: *Agents need control flow, not more prompts* (Hacker News, 2026).
- Add complexity only when it improves a measurable result. A three-agent harness (the code that coordinates the agents) built better applications than a single agent, but cost over 20 times more: *Harness design for long-running application development* (Anthropic, 2026).
- With untrusted content, sensitive data and external actions in the same session, the agent needs human oversight: *Agents Rule of Two* (Meta, 2025) and *New prompt injection papers: Agents Rule of Two and The Attacker Moves Second* (Simon Willison, 2025). A prompt injection (text that gives hidden orders to the agent) moved the victim's files out through an allowed domain, with no approval from the user: *Claude Cowork Exfiltrates Files* (PromptArmor, 2026).
- pass^k measures whether the agent gets it right every time, not just once: *Demystifying evals for AI agents* (Anthropic, 2026). Getting every attempt right is much harder than getting one right: *τ-Knowledge* (Shi et al., 2026).
- Measure cost and accuracy together: *Holistic Agent Leaderboard* (Kapoor et al., 2025).