Planning & Architecture Agent — Engineering Guide

InfinitySDLC Engineering Guides · 03/12

Reference implementation guide, not a report of a completed client deployment. Code, configurations, metrics and policies are illustrative. Adapt and validate them before production use.

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.

3.1 Core toolset

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

3.2 Code-aware RAG

Do not embed a monorepo as undifferentiated text. Build a symbol index from language parsers or an LSP/SCIP-like pipeline and store call edges, imports, ownership and test relationships. Combine this with commit-aware lexical search. Architecture questions often require graph traversal (“what calls this API?”) more than semantic similarity. Treat generated diagrams as views over graph data, not as the source of truth.

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

3.3 Planning algorithm

1. Create a change-impact graph from 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 explicit trade-offs, migration path and rollback strategy.
4. Run threat-model and reliability checks as tools/subagents rather than prose-only self-review.
5. Estimate implementation as dependency-aware work packages with validation criteria.
6. Generate ADR draft, interface changes, data migration plan, observability plan and test strategy.
7. Ask a human architect to accept the design before creating actionable backlog items.

3.4 Claude Code vs Codex vs local models

3.5 Required output contract

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

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

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/data stores, owners, lifecycle and tier.
• ADR registry: current/superseded decisions, scope and effective date.
• Impact API: bounded dependency expansion with path explanations.
• Cost/capacity API: approved technologies and historical utilization baselines.

Architecture loop

requirements -> change-impact graph -> retrieve ADRs/standards/NFRs
-> generate 2-3 viable options
-> Security Prevention review + Reliability review + cost estimate
-> compare trade-offs with evidence
-> emit ProposedADR + interface deltas + migration/rollback + validation plan
-> human architecture approval -> backlog drafts

Store the architecture in a structured object first, then render Markdown or diagrams. This lets deterministic validators check rules such as: every new external API has an owner/auth/version strategy; every state migration has rollback or forward-fix semantics; every critical dependency has timeout/retry/fallback behavior.

Failure conditions

• Invented services/interfaces are a hard failure.
• A design that conflicts with an ADR without explicitly requesting an ADR change is a hard failure.
• A schema migration without verification and rollback/forward-fix is incomplete.
• A technology not in the approved catalog must be flagged as an exception, not silently selected.

Source and Shared Prerequisites

Adapted from the September 2026 Enterprise AI Agent Mesh handbook, Article 3 and Blueprint 3. The Enterprise Agent Platform Foundation guide provides the shared identity, MCP, retrieval, sandbox, audit and evaluation design, plus the source handbook’s further-reading list. Validate model, protocol and tool versions before production use.

Explore the Series

Previous guide · Series foundation · Next guide