Claude Code

Verified against Claude Code · 2026-08-12

Get an architecture review from Claude Code that cites file and line, not a generic 'consider microservices' essay

A tightly bounded prompt for a structured architecture review — layering violations, coupling hotspots, and a prioritized list of concrete findings, each backed by an actual file reference rather than abstract best-practice advice.

Claude Code4 fillable variables

The prompt

Ready to copy — highlighted parts are example details you can swap.

Review the architecture of the services/ and rag/ directories of the RAG API, excluding tests/. Read the actual code and dependency structure before writing anything — do not produce a generic architecture essay that would apply to any codebase.

What I actually want checked: whether the retrieval service still talks directly to the Qdrant SDK anywhere instead of going through VectorStorePort, after last month's refactor.

The expected layering, if the project has one, is: Presentation (api/) -> Application (services/) -> Domain (rag/) -> Infrastructure (vectorstore/, llm/); domain code must never import a vendor SDK directly. Check whether the code actually respects it — trace real import statements and call chains, not what the folder names imply.

Produce exactly these sections:

1. LAYERING VIOLATIONS — every place a supposedly lower layer imports from or depends on a higher one, or a domain module imports a framework/vendor SDK directly instead of going through an abstraction. Cite the actual file and line for each one found. If none are found, say so plainly rather than inventing a marginal one to have something to report.

2. COUPLING HOTSPOTS — modules with an unusually high number of inbound or outbound dependencies relative to the rest of the codebase, named specifically with the count, not just asserted as 'this module does a lot.'

3. RISK RANKING — of everything found above, rank by (a) how many other modules would need to change if this were fixed, and (b) how likely this pattern is to cause a bug the next time someone extends the code nearby. State both factors per item, not a single unexplained severity label.

4. FIXES, SCOPED TO WHAT WAS ACTUALLY ASKED — for each item in the risk ranking, one concrete, minimally invasive fix. Do not propose a framework swap, a full rewrite, or a different architecture paradigm unless the finding genuinely requires it — most layering violations are fixed by introducing one interface or moving one import, not by starting over.

Depth for this pass: Focused pass — the two directories named above only, not a full-repo audit.

WHAT NOT TO DO
- Do not flag naming conventions, formatting, or code style — this is an architecture review, not a lint pass.
- Do not recommend microservices, a new database, or a different language as a default suggestion; only raise it if a specific finding above actually points there, and say which finding.
- Do not pad the report with restated best practices that aren't tied to a specific thing found in this codebase.
- Do not claim a violation exists without naming the file and line where it lives — an unverifiable claim is worse than no claim, since it can send a reviewer chasing something that isn't there.

Customize

Optional — swap in your own details for the highlighted parts above.

Why this works

Claude Code's advantage over a review done from memory or from a diagram is that it can actually open every file, trace an import statement to where it resolves, and follow a call chain across module boundaries with tools like Grep and Glob rather than trusting what a folder name implies about layering — which is exactly why the prompt insists on citing file and line for every finding: a claim that isn't tied to an actual location is unfalsifiable, and an unfalsifiable architecture finding is worse than none because a reviewer then has to go hunting for something that may not exist. Bounding the review to a named scope and a specific stated concern, rather than an open-ended 'review the architecture,' matters because a generic review prompt reliably produces a generic essay — one that lists best practices any codebase could benefit from, restates SOLID principles in the abstract, and reaches for a familiar big recommendation like microservices or a rewrite regardless of whether the actual code supports that conclusion, since that's the median answer for the median unscoped prompt of this shape. Requiring the risk ranking to state two separate factors, blast radius and likelihood of recurrence, rather than a single severity label, forces the model to reason about each finding on its own evidence instead of defaulting to a template severity scale that doesn't actually reflect this codebase's specific coupling. The what-not-to-do section exists because architecture review and code style review get conflated by default — a review asked for broadly will often pad its findings with naming and formatting nits because those are easy, verifiable, and plentiful, which crowds out the harder structural findings the review actually exists to surface, and explicitly ruling that out redirects the effort toward the layering and coupling questions that were the actual point of asking.

What you get back

1. Layering violations: rag/retrieval/hybrid.py:34 imports `qdrant_client` directly instead of going through `vectorstore.base.VectorStorePort` — introduced in the reranking commit, bypasses the port added for the pgvector swap. 2. Coupling hotspots: services/query_service.py has 11 inbound imports (highest in services/), mostly other services reaching into it for its retry helper. 3. Risk ranking: #1 above ranked highest — low blast radius (one file) but high recurrence risk, since it reintroduces the exact coupling VectorStorePort was built to prevent.

Verified against

Claude Code Sonnet 4.6 · 2026-08-12

Changelog

  • 2026-08-12 — Initial publish, verified against Claude Code Sonnet 4.6.

Building this for real?

This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.

EXPLORE CUSTOM SOFTWARE
All Claude Code prompts

Check your AI visibility

One URL in, a 0–100 score and the exact fixes out.

RUN THE CHECK

Browse all the tools

15 tools across six categories
13 of them never send your data anywhere

Free · No signup · No trial clock

SEE THE DIRECTORY