Architecture review with an AI agent

What architecture review is really for

Architecture review helps a team understand how a system behaves, where change is risky, and what work should happen next. It is not a scavenger hunt for every file in the repository. The goal is judgment: what matters, what is fragile, and what should be improved first.

AI can accelerate this work by reading more context than a person has time to inspect manually. But the output still needs engineering discipline. It should cite concrete evidence, distinguish design concerns from implementation trivia, and avoid pretending that a quick repository scan is equivalent to institutional knowledge.

What the agent should inspect

• Entry points: application startup, routing, workers, jobs, APIs, and CLI commands.
• Module boundaries: where responsibilities are separated or tangled.
• Data flow: databases, queues, files, external APIs, caches, and state transitions.
• Configuration: environment variables, deployment files, feature flags, and secrets handling.
• Reliability signals: logging, retries, error handling, idempotency, tests, and runbooks.
• Change risk: areas where small edits could create broad regressions.

The agent should also identify what it cannot know from the repository alone. Runtime load, organizational constraints, product priorities, and production incidents may require human context.

Example Kendr prompt

Review this repository as an architecture reviewer.

Focus on:
- system boundaries and major modules
- data flow and dependency hotspots
- operational risks
- test and documentation gaps
- risky areas for future edits

Return:
- architecture summary
- risk register
- evidence from files or docs
- 30/60/90 day action plan
- questions for the engineering team

This prompt asks the agent to produce a review package instead of a loose description. The action plan matters because architecture review should feed execution.

Risk register structure

A useful architecture review should produce a risk register with severity, evidence, affected area, likely impact, and recommended next action. This makes the review easier to discuss with engineering and leadership.

• Boundary risk: responsibilities are mixed across modules or services.
• Data risk: migrations, schema assumptions, or state transitions are hard to reason about.
• Operational risk: deployment, observability, or recovery behavior is unclear.
• Security risk: authentication, authorization, secrets, or data exposure needs review.
• Velocity risk: missing tests, confusing structure, or weak docs will slow future work.

Evidence quality in architecture review

Architecture review should be grounded in repository evidence, but not all evidence is equal. A test suite can show intended behavior. A migration can reveal data model history. A deployment file can reveal operational assumptions. A README may be outdated. A TODO comment may be useful, but it may also be stale.

The agent should call out the evidence type behind each finding. For example, "the service boundary is unclear because authentication checks appear in three modules" is stronger than "the architecture seems messy." Specific file-backed observations make the review actionable.

When evidence is missing, the review should say so. Missing runbooks, missing tests, missing architecture docs, or missing deployment notes are themselves useful findings because they show where future maintainers will struggle.

Architecture review outputs

Different audiences need different outputs. Engineering leads need technical detail and sequencing. Product or leadership teams need risk, impact, and investment rationale. A good Kendr run can produce both without forcing one audience to read the wrong format.

• Technical architecture brief: system map, modules, data flow, dependencies, and design constraints.
• Risk register: risks, evidence, severity, affected area, and recommended action.
• Leadership summary: what matters, why it matters, and what investment is recommended.
• Execution plan: quick wins, medium-term refactors, high-risk work, and approval points.
• Project memory: concise context future agents should load before planning changes.

Questions for engineering leads

An AI review should produce questions, not just conclusions. Questions help the team validate whether the repository evidence matches lived operational reality.

• Which modules are hardest to change safely?
• Where does production behavior differ from local or test behavior?
• Which areas have the most incident history?
• Which dependencies or APIs are most brittle?
• Which tests are trusted, and which are noisy?
• Which refactors are blocked by product, migration, or release constraints?

These questions turn the agent's first pass into a better human review session.

From review to execution

The highest-value output is a sequenced plan. A review that says "the architecture has problems" is not enough. The team needs to know what can be fixed now, what needs design discussion, what requires migration planning, and what should not be touched before a release.

A 30/60/90 day plan works well because it separates quick wins from deeper changes. Quick wins might include docs, tests, dependency cleanup, or observability improvements. Medium-term work might include module boundaries or deployment hardening. Longer-term work might include data model changes, service separation, or platform investment.

Review boundaries

An AI architecture review should be explicit about limitations. If the agent did not run the system, inspect production metrics, talk to maintainers, or review incident history, it should not overstate confidence. Good reviews include uncertainty.

Teams should treat AI review as a strong first pass that accelerates human judgment. It can surface patterns, prepare questions, organize evidence, and draft plans. Engineering leads still decide the priorities.

How Kendr helps

Kendr can preserve architecture findings as project memory so future agentic workflows start with the system context already loaded. That helps later code review, refactoring, deployment planning, and incident response.