AI Architect
The architecture review, as something you can run.
Four checks against a real codebase. Each one names something you can grep, measure, or point at — because a review with no evidence is an opinion. Work through it here, or install it into the coding agent that already has the repository open.
What it checks
In order of what it costs to defer.
- 01Where does the model call go?
- 02What shape is the loop?
- 03Where does the trust boundary sit?
- 04Where does a long run live?
Everything else — prompt wording, chunk size, which reranker, which framework — is a refactor you can do on a quiet Thursday.
The four checks
Most decisions are reversible in an afternoon. These four are not.
Run them in order. The cost of deferring rises as you go down the list, and check three rises fastest, because it scales with the number of tools already shipped.
- 01
Where does the model call go?
Grep for the provider SDK import across the repo.
rg -l "from ['\"](openai|@anthropic-ai/sdk|@google/gen)"
- Made
- One module knows a provider name. The seam exists.
- Deferred
- Ninety call sites. The decision was deferred, and the deferral compounds.
- 02
What shape is the loop?
Find the loop's exit condition.
Read the control flow, not the prompt.
- Made
- A counter, a budget, or a state machine. Bounded in code.
- Deferred
- An instruction to stop when done. An unbounded loop with a polite request attached.
- 03
Where does the trust boundary sit?
Trace one retrieved document from the retriever to the context window.
Point at the line where it becomes labelled data.
- Made
- Untrusted text stays in the data position. Side effects sit behind a gate.
- Deferred
- You cannot find the line. Then a document can act, and the corpus is attack surface.
- 04
Where does a long run live?
The longest real production run, against the platform ceiling.
Not the median. The longest.
- Made
- Both numbers known, and the second is larger.
- Deferred
- Neither number known. The platform choice was load-bearing and nobody made it.
One question closes the set: what breaks first if your primary model provider is unavailable for four hours? If the answer is everything, all four are still open, and they are open in the expensive direction. The long version of the argument covers why each one is expensive.
Run it now
Four answers in, one verdict out.
The same rubric the installable skill runs — deterministic, in your browser, and nothing you enter leaves the page. Each option names the evidence it stands on, because a review with no evidence is an opinion.
0 of 4 answered. The verdict appears when all four are in.
Install
Run it where the architecture actually is.
One file, no dependencies, no account. Drop it where your harness looks for skills.
mkdir -p .claude/skills/ai-architect-review curl -sSL https://www.frankx.ai/skills/ai-architect-review/SKILL.md \ -o .claude/skills/ai-architect-review/SKILL.md
- Claude Code
.claude/skills/ai-architect-review/SKILL.md
Project-level. Activates from context, or ask for an architecture review.
- Cursor
.cursor/rules/ai-architect-review.md
Reads the same file. Add a description line if your rules use frontmatter.
- Codex / Windsurf / Copilot
AGENTS.md, or the rules directory your harness reads
Paste the body, or reference the file. It is plain markdown by design.
The engineering call
Why this is a skill and not an MCP server.
MCP is the right shape for capability with side effects — something that reads your systems, holds state across calls, and acts. It costs a server you host, an auth story, and uptime you are now responsible for.
A rubric is static knowledge. Shipping it as a file your agent reads is strictly better on every axis that matters here: it works offline, it cannot break when a server goes down, it costs nothing per run, and one file installs into every harness rather than one.
The threshold to cross is narrow and worth naming: MCP starts earning its complexity the day the reviewer needs to read your repository and carry state across a session. At that point the value has moved into the reading, and the rubric is still just a file.
What is free, and what is not
- Free, permanently
- The rubric, the skill file, the field guide, the diagrams. A rubric is only worth something if it travels, and a paywall stops it travelling.
- Not free
- Applying it to a system with real constraints, real history, and a real team. That is judgement rather than an artifact, and it does not compress into a file.
Questions
Before you install it
What is an AI architecture review?
A pass over the parts that surround a model rather than the model itself: where the model call is made, what shape the control loop is, where untrusted text can and cannot go, and where work that outlives a request runs. It checks those four first because they are the decisions that are expensive to reverse, then walks the seven planes looking for one nobody owns.
Is this an MCP server or a skill?
A skill. MCP is the right shape for capability with side effects — something that reads your systems, holds state, and acts. This rubric is static knowledge, so a file your agent reads is strictly better: it works offline, it cannot break when a server goes down, it costs nothing to run, and the same file installs into Claude Code, Cursor, Codex, Windsurf and Copilot. An MCP server would only start earning its complexity if the reviewer needed to read your repository and hold state across a session.
What does the skill cost?
Nothing. It is MIT licensed and served as a plain markdown file. The rubric is free because a rubric distributes; what is not free is the judgement of applying it to a system with real constraints, which is what a human review is for.
Which coding agents can use it?
Any harness that reads a markdown skill or rules file. That covers Claude Code, Cursor, Codex, Windsurf, and GitHub Copilot today. The file carries standard skill frontmatter with a name and a description, and the body is ordinary markdown with no harness-specific syntax.