AI-assisted architecture reviews from a live codebase

Why generic architecture reviews miss the point

Most bad review notes sound reasonable until a team tries to use them. They say things like "split this service," "reduce coupling," or "improve observability" without showing where the trouble actually starts.

That happens when advice ignores how the code really works. A repository has habits, shortcuts, old decisions, and hidden dependencies that never show up in a clean diagram. If a reviewer cannot see which modules call each other, which files change together, and which deployment step fails when one script breaks, the advice stays vague.

A static diagram looks tidy. Real systems usually are not. A service may seem small on paper, but the code can show that two files inside it pull in half the app, trigger most regressions, and slow every release.

The same gap shows up in delivery. A diagram can show "API -> worker -> database" and still miss the release path that depends on a hand-run migration, one fragile environment variable, and a forgotten CI step. Teams end up with architecture comments that sound smart but do nothing for next week's release.

Noise is the real cost. Engineers spend hours sorting useful comments from generic ones, arguing over wording, and checking whether a suggestion even fits the current system. Product teams lose time too, because broad advice turns into broad tickets.

AI-assisted architecture reviews work better when they start with project data instead of theory. If the review sees real dependency maps, code hotspots, and deployment paths, the output gets shorter and sharper. Instead of "reduce coupling," you get "this auth package reaches into billing and notifications, so every login change raises release risk." A team can act on that.

Short, specific advice does not come from making the model say less. It comes from giving it better input.

What to pull from the codebase first

Start with evidence, not opinions. The review works best when the model can see how the code is arranged, where teams keep making changes, and how those changes reach production.

The first thing to export is a dependency map. Keep it simple. Show services, major modules, and shared packages, then show who calls or imports what. It does not need to be perfect. It only needs enough detail to expose risky links, like one shared package sitting in the middle of half the system.

Then mark the hotspots. Look for files or modules with heavy recent churn, repeat bug fixes, or tests that fail or drag. Those areas create most of the noise in architecture discussions because they mix design problems with daily delivery pain. A calm, stable module matters less than the messy one changed twelve times this month.

Deployment paths matter as much as the code itself. Write down what happens from commit to production for each part of the system. Include build steps, test gates, package or image creation, infrastructure changes, approvals, and rollout steps. If one service ships in ten minutes and another needs manual fixes across three tools, the review should see that difference.

Ownership is the part teams often skip. Note which services or modules have a clear owner and which do not. When nobody owns a shared library, it tends to grow in the wrong direction. When two teams think the other team owns a service, bugs sit longer and risky changes slip through.

A small example makes this clear. Say your SaaS app has an auth service, a billing service, and a shared notification package. The dependency map shows billing and auth both rely on that package. Churn data shows the package changed every week. The deployment path shows notification updates still need a manual release step. Ownership notes show nobody wants it. That is already enough for a useful review, because the evidence is specific.

Pick one review question

AI-assisted architecture reviews work best when the prompt asks one clear question. If you ask for a full verdict on structure, reliability, performance, security, and team process all at once, the output gets fuzzy fast.

Start with the problem you want to reduce this month. That could be failed releases, slow feature work, painful on-call nights, or too many changes touching the same files. A narrow goal gives the review a filter, so dependency maps, code hotspots, and deployment paths only matter when they help answer that goal.

Good review questions sound plain:

• Why do changes in billing keep causing release issues?
• What makes this API slow to change?
• Which service creates most deployment risk in this product area?
• Where does this checkout flow depend on too many teams?

Keep the scope tight. Pick one product area, like onboarding or billing, or one group of services that usually ships together. If you include the whole platform, the reviewer spends half the time describing the obvious system shape instead of finding the few design choices that keep causing pain.

Also write down what the reviewer should ignore. This matters more than most teams expect. If your goal is faster changes in one service group, say so. Tell the reviewer to ignore old admin tools, background jobs outside that flow, and style issues that do not affect delivery speed. The review gets shorter, and the advice gets easier to use.

The audience matters too. A staff engineer may want call chains, module boundaries, and deployment coupling. A founder usually needs a shorter answer: what slows releases, what to change first, and what can wait. If nobody owns the result, even a sharp review ends up unused.

A short prompt note helps: who the answer is for, what decision it should support, what is in scope, and what is out. That small step often cuts the final output in half.

Build the review flow step by step

Start small. If you dump the whole repository into a model, it drifts into general advice and misses the parts that hurt your team every week.

Begin with the dependency map. That gives the review a shape. You can see where one service leans too hard on another, where a shared module touches too many areas, and where a small change can spread farther than expected.

Next, add hotspots. A hotspot is code that changes often, causes bugs, or keeps showing up in pull requests and incident notes. This matters because a clean-looking module on a diagram can still be your biggest problem if the team edits it every few days.

Then add deployment paths. This is where many reviews become useful fast. Show the path from commit to production, including builds, checks, approvals, scripts, and any manual handoff between people or systems. A service might look fine in the codebase but still create risk because one release depends on a shell script, a copy-paste step, or someone remembering the right order.

A simple flow is enough:

1. Feed the dependency map for the area you want to review.
2. Add hotspot data from recent commits, bugs, or support pain.
3. Attach the deployment path for that same area.
4. Ask one narrow question, such as "Where do changes create the most release risk?"
5. Ask for only three actions, ranked by impact and effort.

That last part matters. If you ask for a full report, you usually get a long document nobody uses. If you ask for three actions, you force the model to choose. The result is clearer, shorter, and easier to test in the next sprint.

Save the exact inputs with the prompt. Keep the same map slice, hotspot window, deployment notes, and review question together. Then the team can rerun the flow after a refactor and compare results without guessing whether the prompt changed.

A simple example from a SaaS product

Picture a small SaaS team with three main parts to look after: a billing service, an admin app for support staff, and a worker queue that sends invoices, retries failed charges, and updates account status. It is not a huge system, but releases still feel tense.

The billing service changes almost every week. Pricing rules move, tax logic gets patched, coupons get added, and payment provider edge cases keep showing up. The team knows billing is risky, but a generic review only tells them what they already know, like "reduce coupling" or "improve reliability."

A live codebase review gives them something they can use. They feed in a dependency map, recent hotspots, and the real deployment path. That is enough to show where the stress comes from.

One issue appears quickly. The billing service and the admin app both depend on the same shared package. At first, that package looked helpful because it kept customer status, pricing rules, and retry settings in one place. Over time, it became a trap. A small admin change could now affect billing behavior, even when nobody meant to touch payment logic.

The deployment path shows a second problem. One release step still depends on a person doing a manual check before restarting a worker. It sounds minor, but those steps cause real trouble. Someone gets busy, skips it, and the queue starts backing up after deploy.

The team makes two small changes instead of planning a rewrite. First, they split the shared package so billing keeps its own logic. Then they leave the admin app with a thinner package that exposes only the data it needs. They also script the release check so deployment stops automatically if the queue setting is wrong.

That is the kind of result you want. The advice stays short because it points to one shared dependency and one deploy step, not ten abstract best practices.

What good review output looks like

A useful architecture review note points to one real risk in one real place. It does not talk about "the backend" or "the deployment process" in general. It names the module, file path, query, queue, or deploy step that can fail.

That level of detail changes the discussion. A team can open the code, check the claim, and decide what to do in minutes. Generic advice turns into debate. Specific advice turns into action.

The best output is short and grounded. It should say what is wrong, why it matters, and what small fix the team can try this week.

A review note people will actually use

A good note reads like this:

• billing/invoice_sync.ts retries failed sync jobs without a cap, which can flood the queue during a payment provider outage.
• This matters because checkout can look healthy while invoice jobs pile up and delay account updates for hours.
• Add a retry limit and move failed jobs to a dead-letter queue after the third attempt.
• Check the deploy pipeline step that runs worker migrations before app rollout, so old workers do not keep the bad retry loop alive.

That is enough for one meeting. People know where to look, what can break, and what to test next. Nobody needs a lecture on "resilience patterns."

Plain words matter as much as technical accuracy. "This can double cloud costs during traffic spikes" is better than "this creates resource amplification under peak conditions." Most teams move faster when the review sounds like a teammate, not a conference talk.

Good output also stays narrow. One note should cover one issue. If the review finds five problems, give five separate notes. When one comment mixes caching, permissions, deployment order, and schema drift, people miss the real risk.

A simple check works well: can someone read the note out loud in under a minute, then assign an owner right away? If yes, the review is probably doing its job.

Mistakes that make the review noisy

Most bad review output starts before the model reads a single file. If you feed the whole repo and ask for "an architecture review," you usually get broad advice that could fit almost any product. The model sees too many paths, too many patterns, and no priority.

A better prompt gives it one job. Ask about a slow release, a risky dependency chain, a brittle service boundary, or a hotspot that keeps breaking.

Another common problem comes from mixing old diagrams with current code. Teams often paste a system map from six months ago next to today's repo and expect one clean answer. If the diagram says one thing and the imports, queues, or API calls say another, the review starts fighting itself.

Use the code as the source of truth. Bring diagrams in as supporting notes, not as law. If they disagree, that gap is useful on its own because it often points to drift nobody noticed.

Teams also miss release steps that live outside the app code. A service may look independent in the repo but still depend on a migration, a GitLab pipeline job, a worker restart, a secret in the deploy system, or an infrastructure rule at the edge. If you leave that out, the review can blame the wrong layer.

One more mistake is asking for a rewrite. That almost always pulls the output toward big, vague plans. Ask instead for the smallest changes that cut risk this month.

Keep the output on a leash too. Long wish lists feel smart, but they are hard to use. A review should usually end with a short set of ranked actions: fix now because it blocks releases, fix next because it causes repeat incidents, watch because it may grow into a real problem, or ignore for now because the cost is higher than the risk.

If the review cannot fit into a few clear actions, the input is still too loose.

Quick checks before you trust the advice

Bad review advice usually fails for ordinary reasons. It points to files nobody touched, deploy steps nobody uses, and fixes nobody owns.

Start with the branch, not the report. If the review names payments/service.ts but your current branch moved that logic into billing/renewal.ts, the rest of the advice may already be off. A live codebase review only helps when the named files, modules, and services match what the team works on today.

Then compare the reported hotspots with real pain. If the review says one package is risky, you should see some proof in recent incidents, support tickets, noisy alerts, or slow on-call fixes. When a hotspot never shows up in production, it may still be messy code, but it should not jump to the top of the list.

A few fast checks catch most bad advice:

• Confirm that every named file and service still exists on the current branch.
• Compare hotspots with recent bugs, support pain, and error spikes.
• Check that the release steps in the review match how the team deploys now.
• Put one owner next to each suggested action.
• Make sure the team can test the change without betting the whole release.

That third check matters more than many teams expect. If your team deploys through GitLab CI/CD but the review assumes a manual release script, the suggested fix path can waste a day. The same goes for runtime checks. If you track failures in Sentry and the review does not line up with what Sentry shows, slow down before you trust it.

Ownership is another easy filter. "Refactor the auth boundary" sounds smart until three teams think someone else will do it. Each action needs one person who can pick it up, make the change, and answer questions.

Testing decides whether advice is useful or just risky. The team should know how to verify the change in staging, behind a feature flag, or with a small rollout and rollback plan. If they cannot test it safely, the review is still too broad.

When two or more of these checks fail, ask for a tighter review. Short advice tied to the current branch beats a long report built on stale context.

Next steps for your team

Do not roll this out across the whole product on day one. Pick one area that already hurts: failed checkouts, slow background jobs, fragile auth, or a release path that breaks under pressure. A narrow test gives the review a real target and makes bad advice easy to spot.

Run the flow on that slice for a week or two. Keep the inputs tied to the same area: the dependency map, recent hotspots, and the deployment path. When those pieces stay together, the review gets much more specific. You get fewer broad opinions and more comments the team can actually use.

Then compare the output with what your senior engineers already know. If the review says "split this service" but the team knows the real issue is a risky migration step, trust the people who live with the system. The review should confirm patterns they already see, point out a blind spot or two, and shorten arguments. It should not overrule experience.

After the first pass, keep only suggestions that clear a simple bar. The team should be able to explain the problem in plain language, give one person ownership, ship the change soon, and measure whether it helped.

Turn the best two suggestions into tickets right away. Give each one an owner, a tight scope, and a success check such as fewer rollback steps, lower error rates, or 15 minutes less deploy time. Two small wins teach a team more than a backlog full of clever ideas.

This is also a good way to judge whether the review flow is worth keeping. If it finds issues the team already knew but describes them faster and with less back-and-forth, that still helps. If it mostly produces obvious advice or rewrite fantasies, cut the scope and try again.

If you need help setting up this kind of review flow, Oleg Sotnikov at oleg.is works as a Fractional CTO and startup advisor on architecture, infrastructure, and practical AI adoption. That kind of outside view is most useful when a team wants sharper technical judgment without hiring a full-time CTO yet.