Design review
An ordered checklist to review an agent design before anyone writes code. Each block depends on the block before it: if one fails, the review stops there. It uses the other six templates as requirements. It also has a table of personal data rules by country.
Copy the block with the button in its corner, or open the file on GitHub.
# Design review: [agent name]
<!--How to use this template:- Review the design before anyone writes code. Follow the order: each block depends on the one before.- If a block fails, stop there. Fix it before you move on.- Tick [x] what holds. If something doesn't, write down why and who fixes it.-->
- Date: [YYYY-MM-DD]- Design author: [name]- Reviewers: [names, with at least one person from security]- ADR: [link to adr-agente-o-no.md]
## 1. The problem
- [ ] An ADR ruled out a fixed workflow with a concrete reason.- [ ] The agent solves one task. The task fits in one sentence.- [ ] The agent has a named owner who answers for it working.
## 2. Scope and tools
- [ ] The tools are listed. Each one does only one thing. There is no general-purpose shell.- [ ] Tool parameters prevent common mistakes (for example, absolute paths, capped amounts).- [ ] There is an instructions file with the domain rules, the commands and the limits.
## 3. Control flow
- [ ] Code owns the loop. The model proposes the next step and code decides whether it runs.- [ ] There is a maximum number of steps per task: [n].- [ ] There is a token budget per task with an automatic cutoff: [n].- [ ] Code detects repeated calls and breaks the loop.- [ ] State is saved at each step. A retry doesn't start from scratch.
## 4. Security
- [ ] The threat map is done: [link to mapa-de-amenazas.md].- [ ] No session combines untrusted content, sensitive data and external actions without a person who approves. Requesting a URL already counts as an external action.- [ ] The agent has its own identity, not a person's account or a shared account.- [ ] The agent's credentials are short-lived and minimally scoped. They never exceed the permissions of the user it serves.- [ ] In production the agent only reads, except for the actions in the policy.- [ ] Backups live in another account and another volume. The agent can't delete them.- [ ] MCP servers (Model Context Protocol, the standard for connecting tools) are in an inventory, with pinned versions.
## 5. Actions
- [ ] The action policy is done: [link to politica-de-acciones.md].- [ ] An action missing from the policy requires confirmation.- [ ] Approval is bound to the exact action and enforced by code, not by the prompt.
## 6. Evaluation
- [ ] The evaluation plan is done: [link to plan-de-evaluacion.md].- [ ] There is an exit criterion with pass^k and a rollback criterion.- [ ] During the first [n] weeks, a person reviews 100% of responses.
## 7. Log
- [ ] Every action is logged with what the agent saw, the tool, the parameters and who approved.- [ ] The log keeps the agent's proposal and the authorization as separate events.- [ ] The agent can't delete or edit the log.
## 8. Cost
- [ ] The cost sheet is done: [link to ficha-de-costo.md].- [ ] There is a daily spend cap with an alert and a cutoff. Who can lift it: [role].
## 9. People and data
- [ ] People know they are talking to an AI from the first interaction, unless it is obvious. In the European Union, this duty falls on the provider of the system.- [ ] There is a visible way to reach a person.- [ ] For each country with users there is a recorded legal basis (the reason the law accepts for using the data). There is also a minimization rule: use only the personal data you need.- [ ] A person can review decisions with a significant effect on someone.- [ ] There is a data processing agreement with the model provider.- [ ] We know how many approvals each reviewer makes per hour. That number is sustainable: [n].
<!--Personal data by country. Check the status of each law before you use this table.AI bills and effective dates change fast.Delete the countries where you have no users and add the ones missing.-->
| Country or region | Personal data law | Chosen legal basis | Notice to the user | Review of automated decisions ||---|---|---|---|---|| European Union | GDPR | [...] | [...] | [which safeguards the GDPR requires for automated decisions with significant effects] || Brazil | LGPD | [...] | [...] | [LGPD Art. 20: right to request a review, not necessarily by a human] || Mexico | LFPDPPP | [...] | [...] | [...] || Chile | Law 21.719 (check its effective date) | [...] | [...] | [...] || Colombia | Law 1581 of 2012 | [...] | [...] | [...] || Argentina | Law 25.326 | [...] | [...] | [...] |
As of November 2026, none of the five Latin American countries in the table has an AI law in force. Legal exposure today comes from their personal data laws.
## 10. Operations
- [ ] The incident runbook is ready: [link to runbook-incidente-agente.md].- [ ] There is a switch for read-only mode and another to shut down. We tested them.- [ ] There is an on-call person who knows how to use them.
## Outcome
- Decision: [approved | approved with changes | not approved]- Requested changes, with owner and date: [...]
## Why this is here
- A rule in the prompt is not a control. A production database was deleted through a token (credential) with too much scope and backups on the same volume: *An AI agent deleted our production database* (Hacker News, 2026).- An instructions file, together with build setup, raised the agent's success rate from 38.1% to 69%. Expert review of every change kept quality up: *Ten Months with Copilot Coding Agent in dotnet/runtime* (Stephen Toub, 2026).- Many tool definitions use up context and lower accuracy. Load tools when they are needed: *Introducing advanced tool use on the Claude Developer Platform* (Anthropic, 2025).- The provider of a system that talks to people must disclose that it is an AI, unless it is obvious. This applies since 2 August 2026: *Article 50* of the EU AI Act (2024).- The agent processes personal data like any other system: it needs a legal basis and data minimization. In Brazil, a person can ask for an automated decision to be reviewed, and the law does not require a person to do the review: *Lei nº 13.853, de 8 de julho de 2019* (Câmara dos Deputados, 2019).