Planning & Architecture Agent — Engineering Guide

InfinitySDLC Engineering Guides · 03/12

The architecture agent turns an approved problem into an implementation plan that is testable, reversible and compatible with the existing estate. It produces engineering artifacts—not architecture theater.

Its value is not the speed at which it draws boxes. It is the ability to connect an approved requirement to affected systems, compare viable alternatives and make the evidence behind a design reviewable.

Reference engineering design. Sections 3.1–3.6 and the implementation blueprint follow the Enterprise AI Agent Mesh handbook. Sections 3.7–3.12 extend that design with production recommendations. Examples and numerical targets are illustrative, not results from a completed client deployment.

Architecture proposes an explicitly versioned change. It does not gain permission to execute that change merely because the proposal is coherent.

The Header diagram connects requirements, constraints and policies with design options, ADRs and delivery artifacts. These outputs require architect review. Open the architecture diagram at full size.

3.1 Core toolset

• Repository and graph MCP: symbol search, dependency graph, code ownership, API and interface extraction, and build graph.
• Cloud inventory MCP: read-only inventory of Kubernetes, cloud resources, databases, queues, IAM relationships and quotas.
• Architecture knowledge RAG: architecture decision records (ADRs), platform standards, reference architectures, threat models, non-functional requirements (NFRs), service-level objectives (SLOs) and deprecation plans.
• Work management MCP: read requirements and create draft epics or tasks after approval.
• Cost and observability tools: historical utilization, service latency, failure rates and spend baselines.

These are capability boundaries for internal tools. The architecture does not assume that every platform exposes an identical, ready-made MCP server. Scope access to the repositories, environments and source documents admitted for the task.

3.2 Code-aware RAG

Do not embed a monorepo as undifferentiated text. Build a symbol index using language parsers or an LSP/SCIP-like pipeline, and retain call edges, imports, ownership and test relationships. Combine it with commit-aware lexical search.

Questions such as “what calls this API?” require graph traversal, not just semantic similarity. Generated diagrams are views over evidence, not the source of truth. The handbook’s illustrative service record makes dependencies and operating constraints explicit:

service_node: payments-api
owners: [team-payments]
dependencies:
  sync: [identity-api]
  async: [topic.payment-events]
data:
  writes: [postgres.payments]
  reads: [redis.payment-cache]
slos:
  availability: 99.95
  p95_ms: 250

The SLO values above reproduce an example from the handbook. They are not default production targets. An actual design must define the workload, measurement window, source and approving owner.

3.3 Planning algorithm

1. Create a change-impact graph linking requirements to services, schemas, APIs and operational controls.
2. Retrieve relevant ADRs and platform standards; flag conflicts before proposing new technology.
3. Generate two or three viable designs with trade-offs, migration paths and rollback strategies.
4. Run threat-model and reliability checks through tools or specialist agents rather than prose-only self-review.
5. Estimate dependency-aware work packages with validation criteria.
6. Draft the ADR, interface changes, data migration plan, observability plan and test strategy.
7. Ask a human architect to accept the design before creating actionable backlog items.

The input is the approved package from the Product Discovery Agent. Unresolved product choices remain open decisions; the architecture agent must not silently convert them into technical commitments.

3.4 Claude Code, Codex and local models

Preserve the shared identity, retrieval and approval boundaries across these routes. A more capable model is not permission to disclose restricted code or execute infrastructure changes. Prototypes provide evidence only within their tested conditions; they are not production deployments.

3.5 Required output contract

Emit a structured proposal before producing its narrative and diagrams. The following is the handbook’s output contract; a chosen option is still proposed until the approval state changes.

architecture_decision:
  status: proposed
  requirement_ids: [PRD-441, NFR-18]
  affected_services: [payments-api, billing-worker]
  options:
    - id: A
      summary: ...
      tradeoffs: [...]
  chosen_option: A
  interfaces_changed: [...]
  migration:
    phases: [...]
    rollback: ...
  security_findings: [...]
  reliability_findings: [...]
  validation_gates: [...]
  evidence:
    - ADR-0081
    - servicegraph:payments-api@2026-09-14

3.6 Anti-patterns

• Inventing cloud services or libraries without checking approved technology catalogs.
• Estimating from natural language alone without repository, build-graph and delivery evidence.
• Writing an ADR that cannot be traced to a requirement or measurable NFR.
• Skipping migration and rollback because the target architecture looks cleaner.
• Letting the architecture agent provision resources directly. Architecture proposes; Environment and Release agents execute through policy gates.

3.7 Build a versioned architecture evidence package

A design can be internally consistent and still describe a system that no longer exists. As a production extension, attach a reproducible evidence package to each proposal: requirement revision, repository commits, service-catalog version, applicable ADR revisions, infrastructure observation times and the policy version used for evaluation.

Do not flatten those versions into a single “current” timestamp. A repository snapshot and a live dependency observation can legitimately describe different states. Record that difference, then decide whether it blocks the proposed change.

Separate observed, inferred and proposed entities

Give every node and edge an evidence status. An existing service must resolve to a canonical catalog or repository identity. A proposed service must be labeled as new, with its owner, purpose and exception or approval status. An inferred relationship must preserve its basis and uncertainty.

Static analysis may miss runtime configuration, reflection, external consumers or dynamically selected endpoints. A bounded graph query therefore needs coverage information: languages indexed, repositories excluded, traversal limits and unresolved edges. “No dependency found” must not become “no dependency exists” when the graph is incomplete.

For each critical change, retain a path explanation from the changed symbol or contract to an affected consumer. This lets a reviewer challenge the impact analysis instead of trusting an opaque score.

Generate context, container or deployment views from the same structured model. Structurizr DSL is an example of a model-based approach that produces multiple views from one model. In this reference design, diagrams are regenerated artifacts; changing a diagram alone does not change the accepted decision.

3.8 Compare viable alternatives and preserve decision history

Begin with hard constraints, then compare the remaining options. An option that violates an approved data boundary does not become acceptable because its weighted score is high. Record the failed constraint and either reject the option or request an explicit exception.

Include the smallest viable change or a no-change baseline where it addresses the problem. Otherwise the agent can make a large redesign appear necessary simply by comparing it with two even larger redesigns.

Store the reason for rejecting each alternative, not just a winner. Preserve assumptions that would cause the decision to be revisited: a changed workload, a new regional restriction or a dependency retirement.

AWS’s ADR process preserves accepted decisions and supersedes them through a new decision rather than silently rewriting their history. Apply that principle to agent drafts: attach a proposal revision and evidence digest to the review, and require a new review when a material constraint changes.

3.9 Turn non-functional requirements into verification contracts

“Fast, secure and scalable” is not a test plan. For every consequential NFR, require a measurement definition, an operating scenario, a threshold approved by its owner, a verification method and a failure response. Leave missing targets unresolved rather than generating plausible numbers.

A latency objective needs the transaction boundary, workload mix, concurrency, data size, percentile, measurement window and treatment of errors. A recovery requirement needs the failure being simulated, the definition of restored service and the evidence used to measure recovery. Different scenarios should not be collapsed into one reassuring adjective.

# Proposed production extension; illustrative fields
constraint_id: NFR-18
status: awaiting_owner_target
scope: checkout -> pricing dependency
measure:
  boundary: customer-visible request
  statistic: p95
  workload_profile: reference-to-approved-profile
  treatment_of_errors: separately_reported
threshold: not_yet_approved
verify:
  method: controlled_load_test
  artifact: versioned_test_report
owner: service_owner
blocking_until_defined: true

Use deterministic validators for completeness and referential integrity: every external API has an owner and authentication strategy; every critical dependency has timeout and retry semantics; every migration has an approved recovery path. Passing those validators establishes that required fields exist, not that the design is correct. Load tests, threat-model review and engineering judgment address different questions.

Keep test evidence tied to the candidate architecture and workload. A benchmark from a different topology or data distribution can inform an estimate but cannot certify the proposed system.

3.10 Design the transition, not only the destination

The highest-risk architecture is often the temporary state in which old and new components coexist. Describe that state explicitly. A final-state diagram cannot answer which application versions can read or write during migration, which representation is authoritative or how divergence will be detected.

AWS’s blue/green deployment guidance highlights compatibility between application versions and schema changes. An additive change is useful only when the old and new readers and writers actually tolerate the transition.

Illustrative expand–migrate–contract plan

1. Expand: introduce the new representation or interface while preserving required compatibility. Specify which component remains the authoritative writer.
2. Migrate: backfill in bounded batches with stable checkpoints, idempotent operations and explicit reconciliation. A job reporting success is not proof that all records are correct.
3. Switch: promote the new read or write path only after the defined checks pass. Record the supported rollback route at this point.
4. Contract: remove the old interface or field only after consumer evidence and the approved rollback window permit it.

Dual writes require a conflict and repair strategy; they are not a correctness guarantee. Define what happens if one write succeeds and the other fails. Measure reconciliation outcomes and route ambiguous cases to an owner.

Distinguish application rollback, data restoration and forward repair. Returning to an old binary does not undo new writes. Restoring a backup can discard later valid work unless the recovery design accounts for it. Mark destructive steps and points of no return in the proposal, with the recovery procedure and approving owner.

Have the Risk & Reliability Agent assess the transition’s blast radius, and hand execution to Change & Release Orchestration. Neither review transfers production credentials to the architecture agent.

3.11 Produce dependency-aware work packages

A delivery plan should explain what must be true before work starts and what evidence makes it complete. For each package, record input decisions, affected interfaces, dependencies, owner, validation artifacts, rollout constraints and unresolved assumptions.

A dependency graph is not yet a schedule. Team capacity, scarce reviewers, procurement and environment availability can serialize work that looks parallel on the graph. Report these constraints separately rather than converting the number of generated tasks into a precise delivery date.

# Illustrative handoff, not an approved schedule
work_package: WP-03
based_on:
  requirement_revision: PRD-441-r2
  architecture_proposal: ADR-draft-017-r3
depends_on: [WP-01-interface-contract]
outputs:
  - versioned migration implementation
  - reconciliation report
  - rollback or forward-repair rehearsal
blocked_by:
  - data_owner_approval
completion_gate: independent_verification
execution_owner: delivery_team

Where historical delivery data is available, disclose the reference class and uncertainty used for estimates. Where it is missing, return a range of scenarios or an unresolved estimate—not a model-invented commitment. Separate engineering effort from elapsed approval and waiting time.

Bind backlog drafts to the accepted proposal version. If an interface or NFR changes during planning, mark dependent packages for revalidation. Avoid rewriting accepted architecture or creating duplicate tickets when a tool response is lost; reconcile against a stable proposal and operation identifier.

3.12 Evaluate decision quality and dangerous omissions

The following proposed suite extends the handbook’s hard failures. It tests whether the agent preserves engineering boundaries when evidence is incomplete or a superficially attractive design is unsafe.

Combine automated consistency checks with independent architecture review and tests of the resulting artifacts. Anthropic’s evaluation guidance separates the agent’s transcript from the environment outcome. Here, a persuasive ADR is not enough: referenced services, compatibility claims and verification artifacts must withstand inspection.

Report evidence completeness, critical omissions, rejected invented entities, reviewer corrections and time to an accepted design package. Break results down by change class. A documentation-only task and a stateful migration should not share a single average that conceals high-risk failures.

The acceptance package should contain the proposal, evidence versions, alternatives, unresolved risks, review decision and execution handoff. These are the artifacts a delivery team can use; the number of generated diagrams is not a readiness measure.

Implementation Blueprint: Machine-Checkable Design

Deterministic services to build before the LLM

• Code graph builder: symbols, imports, call edges, tests, owners and commit SHA.
• Service catalog: canonical services, APIs and data stores, with owners, lifecycle and tier.
• ADR registry: current and superseded decisions, scope and effective date.
• Impact API: bounded dependency expansion with path explanations.
• Cost and capacity API: approved technologies and historical utilization baselines.

Architecture loop

approved requirements
  -> change-impact graph
  -> retrieve ADRs, standards and NFRs
  -> generate 2–3 viable options
  -> security + reliability review + cost estimate
  -> compare trade-offs with evidence
  -> proposed ADR + interface deltas
  -> migration, recovery and validation plan
  -> human architecture approval
  -> backlog drafts

Store architecture as a structured object before rendering Markdown or diagrams. The source blueprint requires checkable rules: every new external API has an owner, authentication and version strategy; every state migration has rollback or forward-fix semantics; every critical dependency has timeout, retry and fallback behavior.

Failure conditions from the handbook

• Invented services or interfaces are a hard failure.
• An ADR conflict without an explicit request to change the decision is a hard failure.
• A schema migration without verification and rollback or forward-fix is incomplete.
• A technology outside the approved catalog must be flagged as an exception, not silently selected.

Sources and shared prerequisites

Adapted from Article 3 and Blueprint 3 of the September 2026 Enterprise AI Agent Mesh handbook. The additional production design sections are recommendations, not claims of completed client work. External references are linked next to the specific practices they support.

The Enterprise Agent Platform Foundation guide defines shared identity, model routing, retrieval, sandboxing, approvals and audit. Validate tool versions and deployment capabilities before implementation.

Explore the series

Previous: Product Discovery Agent

Next: Environment Agent