REOPT
ARCHITECTURE
AI agent architecture: patterns and governance
An AI agent architecture defines which decisions an agent can make, which tools it can call, what context it can access, and how execution stops or recovers. reopt architecture is a practical reference for teams turning a working agent into an accountable production system.
Design AI agents with explicit tool permissions, human approval, evaluation gates, and cost limits. Use eight architecture patterns, a GOVERNANCE.md template, and implementation case studies.
Start with the failure you need to prevent
Choose one workflow and its most costly failure. Follow a pattern, produce the artifact below, and test the boundary before expanding the agent’s authority.
An agent can change data without approval
Separate proposing an action from executing it. Bind approval to the exact action and arguments, then verify authorization again at execution time.
Deliverable: an approval record and a test that rejects changed or expired requests.
Design human approvalRetries and tool calls run beyond budget
Give each run a budget and a stop condition. Include nested model calls and retries in the same accounting boundary.
Deliverable: a run budget and a test proving execution stops when it is exhausted.
Bound agent costNobody can explain a failed agent run
Connect the user request, agent version, tool calls, approval, and outcome with one trace identifier. Decide which data must be redacted.
Deliverable: a trace that reconstructs a failed action without exposing secrets.
Make decisions traceable
Worked example: a support agent that drafts refunds
Illustrative design, not a production benchmark. The agent may read an authorized order and propose a refund. A separate executor owns the payment operation; a support lead owns the outcome.
| Boundary | Implementation decision | Failure to test |
|---|---|---|
| Authority | Expose read_order and propose_refund to the agent. Keep execute_refund behind server-side authorization. | A prompt or tool argument attempts to invoke the payment operation directly. |
| Approval | Store the order, amount, currency, requester, approver, and expiry with the proposal. Recheck them before execution. | The amount changes after approval, approval expires, or the order belongs to another tenant. |
| Recovery | Use an idempotency key for the approved operation. Reconcile an uncertain payment result before retrying. | The provider accepts the refund but the response times out. |
| Evaluation | Run denied, expired, cross-tenant, and duplicate-request cases before granting write access. Keep the resulting trace. | A plausible model response passes review while the underlying action violates a rule. |
Write these decisions in GOVERNANCE.md, then enforce them in tool handlers and tests. A policy document or an instruction in a prompt cannot enforce a payment boundary by itself.
The Five-Phase Methodology
Assess
Make the current state objective
Scan the product's requirements and structural risks across 17 engineering and business attributes. The first phase is the team seeing the same picture and agreeing on priorities.
Product AssessmentDefine
Document the structural commitments
Lock the assessment results into GOVERNANCE.md. Declaring the four — ownership, judgment contracts, collaboration rules, improvement criteria — gives the loop and the execution a direction.
GOVERNANCE.md guideLoop
Sharpen the structure through the four OCLS phases
- OWNName the owner of the outcome — governance changes with whether the owner is human or AI.
- CONTRACTDeclare judgment conditions and boundaries — the more an AI owns it, the stricter the contract.
- LAYERLayer the product structure and scale.
- SHARPENRefine the structure from operational outcomes.
Execute
Make design decisions with patterns
Pick the right pattern for the situation and make the design decision. Responsibility Partitioning, Module Contract, Context Routing — when the team answers the judgment questions of the eight patterns, GOVERNANCE.md's commitments turn into real design.
Pattern catalogEvaluate
Measure outcomes and iterate
Evaluate execution outcomes through the agentic-debt lens. Update GOVERNANCE.md, return to the assessment (phase 1). Each pass sharpens the structure.
Re-assessImplementation notes and field experience
Inspect the code examples, design decisions, and limits behind the methodology. These are author-reported experiences; their outcomes do not establish results for other systems.
Implementing Reopt Agentic Governance: from assessment to system
How a production SaaS running eight AI agents used reopt architecture's principles to diagnose its governance gaps and close them — universal audit logging, persistent approval records, MCP tracing and rate limiting, agent constraints, and an admin dashboard.
Projects as design experiments: learning architecture with AI
Across 25 pilot projects, comparing projects with different development principles proved especially useful. This guide turns that experience into cross-project design review: make policies explicit, derive improvement hypotheses from reference projects, and verify them in the receiving project.
Running the reopt architecture five-phase loop in Claude Code
A practical guide that maps the Assess→Define→Loop→Execute→Evaluate methodology onto Claude Code's CLAUDE.md auto-load, slash commands, sub-agents, and skills — applied to a real repository.
Use the parts your system needs
A deterministic workflow may only need a module contract, an owner, and failure tests. Add agent delegation when a task requires open-ended decisions; add approval where actions cross a meaningful authority boundary. The reference is independent of an agent framework and is not a compliance certification.