Turning Complex Systems into AI‑Readable Engineering Models Before Building an Architect Agent

Problem Statement

AI coding can quickly generate code for small, new projects, but it struggles with large, long‑running distributed systems because the real constraints are scattered across code, documentation, configuration, and tacit team knowledge. An "Architect Agent" must therefore transform complex legacy systems into engineering artifacts that AI can understand, reason about, and verify.

Why Current AI Fails on Complex Systems

Existing models can read a repository, trace call chains, explain functions, add unit tests, and fix local bugs. The difficulty lies in cross‑domain architectural understanding and design. A medium‑size feature may involve dozens of repositories, dozens of APIs, multiple configuration centers, asynchronous messages, back‑office tools, and downstream batch jobs. If the AI relies only on the current repository, it can produce "locally correct but globally wrong" changes—e.g., placing logic in the wrong service, exceeding timeout budgets, or deleting compatibility branches that break older clients.

Four Knowledge Categories that Influence Design

Business Knowledge : product goals, terminology, and domain concepts that do not map directly to code identifiers.

Architecture Knowledge : service call chains, data ownership, consistency requirements, and where eventual consistency is acceptable.

Service‑Internal Knowledge : API contracts, domain objects, state machines, databases, caches, messages, scheduled tasks, and testing approaches that determine how to modify a service safely.

Engineering & Organizational Knowledge : timeout, retry, rate‑limit, gray‑release, rollback, security approval, and monitoring rules that affect whether a design can be deployed safely.

Industry Progress: Spec‑Driven Development, Harness, and Agent‑Friendly Repositories

Over the past two years the industry has realized that feeding a raw natural‑language requirement to a coding agent is unstable. More reliable approaches structure requirements, plans, tasks, and verification conditions.

Spec‑Driven Development (e.g., GitHub Spec Kit) organizes the workflow as Spec → Plan → Tasks → Implement. Tools like Kiro split requirements, designs, and tasks into separate files and emphasize staged reviews for high‑risk changes.

Harness (explored by Anthropic) adds long‑term context continuity by initializing, splitting tasks, and handing over structured artifacts between sessions, solving the context‑continuity problem for long‑running development.

Agent‑Friendly Repository provides a concise map ( AGENTS.md) instead of a massive document dump. Short, structured files hold facts, while RAG is used only for discovering raw evidence.

Knowledge‑Base Design for AI Consumption

A domain‑level business knowledge base can be organized as a hierarchy that forces a clear reading path:

business/

├── index.md
├── meta/
│   └── index.md
├── principle/
│   ├── index.md
│   ├── timeout.md
│   ├── idempotency.md
│   ├── consistency.md
│   ├── degradation.md
│   └── compatibility.md
├── scenario/
│   ├── index.md
│   └── scenario-*.md
├── reference/
├── practice/
│   ├── index.md
│   └── practice-*.md
└── history/
    └── history-YYYYMMDD.md

Responsibilities: meta: business terms, core objects, aliases, and boundaries. principle: reusable domain principles such as idempotency and compatibility. scenario: mapping from user or business scenarios to APIs, services, data, messages, and compensations. practice: historical decisions, incident lessons, and reusable patterns. reference: links to other domains without duplicating full knowledge.

This hierarchy ensures AI reads meta first (to avoid concept confusion), then scenarios (to map intent to technical entry points), then principles (for constraints), and finally practices (for historical reasons).

Service Knowledge for Microservices

Each microservice should have its own service-knowledge repository, ideally co‑located with the code. It describes responsibilities, API contracts, event contracts, data models, cache strategies, testing, and deployment rules. Benefits:

Follows DDD, boundary, and security principles, emphasizing cross‑project consistency.

Uses structured formats (YAML, Markdown) for higher information density.

Provides a compact representation that speeds up context loading for large codebases (e.g., >50 k lines can see ~25 % efficiency gain).

Reduces context pressure when multiple services are involved, avoiding compression loss in LLM windows.

Progressive Context Disclosure

Instead of loading all documents at once, AI should disclose knowledge progressively in four layers:

Business Layer : Answer “Why change? Where does the business impact land?” – source: business-knowledge (product docs, historical practice). Update frequency: low.

Architecture Layer : Answer “Which systems are involved? Who is affected?” – source: AITOM, service graph, API dependencies. Update frequency: medium.

System Layer : Answer “How to safely modify a specific service?” – source: AGENTS.md, .knowledge/ generated via service-knowledge-generate. Update frequency: high.

Infrastructure Layer : Answer “What are the engineering and release constraints?” – source: middleware specs, release process, security and stability rules. Update frequency: low.

The agent loads only the layer needed for the current reasoning step, then proceeds to the next layer based on the conclusions drawn.

Six‑Step AI Technical Design Workflow

Read the PRD that has passed requirement admission and extract acceptance criteria, scope, exclusions, risks, and pending items.

Parse key business terms and scenarios from the business knowledge base, mapping them to responsible systems, APIs, and data.

Use the architecture graph (AITOM) to locate candidate services and the full call chain, identifying main paths, side‑paths, sync calls, async events, downstream dependencies, and architectural red‑lines.

Enter each candidate repository and load the relevant service knowledge. For new APIs, read contracts, compatibility policies, tests, and policies; for database changes, read schema semantics, migration rules, downstream dependencies, and verification requirements.

Perform a gap analysis: mark reusable capabilities, required extensions, and completely new components. This forces the design to answer “why this change” instead of merely listing file modifications.

Generate a complete design document that includes change points, impact analysis, exception propagation, compatibility strategy, test matrix, release and configuration actions, requirement coverage matrix, knowledge‑base links, and pending items.

Each step is accompanied by progressive context loading, evidence verification, and a stop condition when the agent encounters information it cannot infer and must ask a human.

What Makes a Design Executable

Where to change?

Why change?

Who is impacted?

How to verify?

What remains uncertain?

The design should also provide term mappings, a clear scope of involved repositories, a “reuse / refactor / new” gap classification, impact analysis, a verification matrix (unit tests, contracts, regression, monitoring, rollout, rollback), and explicit pending items.

Knowledge Correctness Requires Ongoing Maintenance

Out‑of‑date knowledge is more dangerous than missing knowledge because the model treats stale facts as reliable. Service knowledge should be linked to Git push, pull‑request, and release pipelines. Hooks or CI can detect changes to APIs, objects, messages, or configuration, generate candidate updates, and verify directory structure, cross‑links, version baselines, and required fields. High‑risk knowledge (API contracts, DB semantics, MQ schema, state machines, security policies) must be reviewed by humans before being committed.

Business knowledge also needs two mechanisms:

Incremental Maintenance : When key APIs, business flows, or rules change, distill the new material into structured knowledge. Unverified content is marked as pending and cannot be silently promoted.

Periodic Calibration : Large‑scale events (e.g., promotions, stability reviews, system walkthroughs, incident post‑mortems) are distilled into the knowledge base on a regular cadence.

Every important fact should record its source, last confirmation time, applicable scope, current status, and owner. Every design should trace key conclusions back to sources, and every code change should indicate which knowledge items may need synchronization.

Value of Service Knowledge

Service knowledge reduces repeated parsing of entities, states, contracts, and call relationships. For codebases >50 k lines, it yields at least a 25 % efficiency improvement. In multi‑service scenarios it prevents context overflow by providing a high‑density, structured view of each service.

Agent Runtime: Connecting Context, Tools, and Process

Agent capabilities are split into five layers:

Business Understanding Layer : Structured business knowledge (terms, domain models, scenarios, principles, practice) accessed via a knowledge‑base MCP.

System Analysis Layer : API retrieval and call‑graph analysis provided by AITOM.

Architecture Reasoning Layer : The technical‑design skill defines how to ingest requirements, load context, locate services, and verify completeness.

Service Knowledge Layer : Per‑service service-knowledge describing responsibilities, contracts, data models, and constraints.

Fact‑Verification Layer : Direct access to the Git repository to read code, configuration, and validate conclusions against the actual implementation.

AI Technical Design Six‑Step Process (Re‑stated for Runtime)

Read the admitted PRD and extract goals, scope, exclusions, risks, and pending items.

Resolve business terms and scenarios from the business knowledge base, mapping them to concrete systems, APIs, and data.

Use the architecture graph to locate candidate services and full call chains, identifying main paths, side‑paths, sync calls, async events, downstream dependencies, and architectural red‑lines.

Enter each candidate repository and load the relevant service knowledge (API contracts, compatibility policies, tests, database semantics, migration rules, etc.).

Perform gap analysis: classify each needed change as reuse, refactor, or new, forcing justification for every modification.

Generate a complete design document containing change points, impact analysis, exception propagation, compatibility strategy, test matrix, release/config actions, requirement‑coverage matrix, knowledge‑base links, and pending items.

Progressive context loading follows the chain: requirement → business knowledge → scenario → architecture graph → service knowledge → code verification → design → evidence validation.

Criteria for an Executable Technical Design

Repository & Scope Definition : Clearly list which repositories are modified, which are read‑only, and which external parties are involved.

Term Mapping : Map PRD language, business terminology, configuration names, service names, and code identifiers.

Gap Classification : Use “reuse / refactor / new” to justify each change.

Impact Analysis : Identify callers, exception propagation, and invariants that must remain unchanged.

Verification Matrix : Define unit tests, contract tests, regression tests, monitoring, rollout, and rollback steps.

Pending Items : Explicitly list unknowns or conflicts instead of silently assuming they are resolved.

If the design answers the five questions—where, why, who, how to verify, and what remains uncertain—it is ready for engineering execution.

95% Completeness Metric

Completeness is measured across six dimensions:

Requirement Coverage : Every PRD item is classified as “do”, “don’t”, or “pending”.

System Coverage : All involved services, repositories, configurations, downstream dependencies, and external participants are listed.

Evidence Coverage : Key conclusions trace back to business knowledge, architecture facts, code, configuration, or confirmed documents.

Risk Coverage : Compatibility, exception handling, gray‑release, cache, message, state‑machine, and security constraints are examined.

Verification Coverage : Unit tests, contract tests, regression tests, monitoring, release, and rollback plans are defined.

Uncertainty Governance : Unknown or conflicting information is explicitly recorded as pending items.

In a well‑prepared case (e.g., the “experience‑site Phase 3” demand), a state‑of‑the‑art LLM can produce a design that meets >95 % of these criteria, leaving only cross‑team decisions, external system behavior, data definitions, or product trade‑offs as open questions.

Knowledge Base as Shared Infrastructure

The same knowledge base that powers technical‑design agents also supports online incident investigation, post‑mortems, onboarding, and continuous learning. By making business terms, scenarios, architecture graphs, and service constraints explicit once, teams can reuse them across multiple workflows.

Architect Agent as the Next Step

Technical‑design is the first concrete manifestation of an Architect Agent because it requires the full stack of system understanding, cross‑service reasoning, and verification. Once an agent can reliably produce such designs, the same capabilities can be extended to requirement enrichment, impact analysis, architecture reviews, and online incident triage.

FAQ (Core Technical Answers)

Q: How does an Architect Agent differ from a regular Coding Agent? A: Coding Agents focus on reading files, applying patches, and running tests. Architect Agents must first understand business intent, cross‑service architecture, and engineering constraints before producing a feasible design.

Q: Why do AI agents often fail on legacy systems? A: Critical knowledge lives outside code—historical compatibility, business semantics, configuration effects, downstream consumers, gray‑release rules, and incident lessons. Relying only on code leads to locally correct but globally wrong solutions.

Q: Why isn’t RAG enough for complex system knowledge? A: RAG can surface relevant fragments but cannot guarantee completeness, structural consistency, or temporal correctness. Complex designs need structured business terms, scenarios, architecture graphs, service constraints, and engineering rules.

Q: Should service‑knowledge live in the code repository? A: Co‑location simplifies access for design, coding, and review agents and enables CI hooks to keep the knowledge in sync. If stored elsewhere, the runtime must still ensure a reliable link between knowledge and code.

Q: What problem does progressive disclosure solve? A: It prevents overloading the LLM context with all knowledge at once, allowing the agent to focus on the most relevant facts step‑by‑step, which improves reasoning accuracy and reduces token usage.

Q: After AI produces a design, what remains for humans? A: Humans validate identified gaps, make business trade‑offs, approve cross‑team commitments, and assume responsibility for high‑risk changes. AI handles most retrieval, reasoning, and documentation, but final accountability stays with the team.