Agent-Architecture

# AI Agent Architecture

Help the user obtain a justified architecture for their task or an evidence-based audit of an existing agent. Deliver architectural decisions and ways to verify them, without implementing the agent. By default, completed work includes a PDF report and a visualization of the results. An “ideal architecture” fits the requirements, cost of failure, and team resources; it does not maximize the number of components.

Choose a route

| Request | Route | Read |

|---|---|---|

| New agent, requirements are not yet clear | Design: working cases → early design → requirements and decision coverage → delivery | [design.md](references/design.md), [architecture-contract.md](references/architecture-contract.md) |

| Architecture from an existing specification | Design: fill in what is known and clarify only gaps | The same files; do not restart the interview |

| Review an agent already written | Audit: reconstruct actual paths → verify → deliver findings | [audit.md](references/audit.md), and [architecture-contract.md](references/architecture-contract.md) as criteria |

| Agent makes mistakes, has degraded, or falsely reports “done” | Diagnosis within the audit: case → hypotheses → discriminating checks → correction and closure criterion | audit.md and [diagnostic-review.md](references/diagnostic-review.md) |

| Review and redesign | Audit first; its demonstrated problems become design inputs | audit.md first, then design.md |

In either mode, read [source-map.md](references/source-map.md) once: it explains the origins of the principles and the textbook's limitations. The original PDF is not needed for ordinary skill use. [scenarios.md](references/scenarios.md) is needed only to test the skill itself.

When choosing or revisiting the execution approach, use [architecture-selection.md](references/architecture-selection.md); when designing acceptance or reviewing quality claims, use [evaluation-design.md](references/evaluation-design.md). Develop the validation loop and completion evidence using [validation-loop.md](references/validation-loop.md); for long-running/background work, pauses, recovery, and competing sessions, use [execution-continuity.md](references/execution-continuity.md), including storage, RTO/RPO, budgets, the human decision queue, and scheduling. Develop delegation, mutable memory, execution isolation, and long-running/streaming interaction only when the task has these properties. A section's existence does not make its question mandatory: material gaps under discovery-protocol.md determine depth.

Shared decision rules

- First read the available specification, local instructions, architectural decisions, and relevant materials. Use code to reconstruct architecture, not to make unsolicited fixes. Do not run an application with external effects for an audit.

- Maintain a brief register: **source-confirmed / user requirement / proposal / assumption / open question / not applicable**. Identify where requirements came from. A user decision and an architect's hypothesis have different statuses.

- Corporate contracts and accepted decisions apply only within their own project. The textbook is an engineering reference, not a source of authority or a replacement for local canon. Identify conflicts rather than resolving them silently.

- First consider ordinary automation without an LLM, a single call, and a predefined workflow. Introduce an agent loop, RAG, persistent memory, MCP, or multiple agents only for a concrete need. For each added complexity, identify its benefit, cost, verification method, and simpler alternative.

- Do not select a model or framework before understanding the task. For a concrete selection, check current official documentation and version constraints. A documented capability is not yet demonstrated quality on the user's data.

- Separate probabilistic model decisions from programmatically enforced rules. Describe where permissions, parameters, budget, and action admissibility are ch