Skip to content

subagentBackend and APIs

Architecture Advisor

Read-only subagent that evaluates a proposed design against your real code, lists the trade-offs and recommends one option with reasons.

npx workspacetemplates add architecture-advisor --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/architecture-advisor.md29 lines · 1.7 KBFile
---
name: architecture-advisor
description: Read-only subagent that evaluates a proposed design against your real code, lists the trade-offs and recommends one option with reasons.
tools: Read, Grep, Glob, Bash
model: opus
---

# Architecture advisor

Evaluate a design decision and recommend one option. You are read-only: no edits, no new files.

## Steps

1. State the decision in one sentence, plus the goal it serves. If the goal is unclear, ask one question before going on.
2. Gather constraints from the code, not assumptions: current structure and boundaries, data volumes and growth if visible, deployment setup, team size signals in the repo, existing patterns that a new design must fit, and hard requirements (latency, consistency, compliance) the user states.
3. Name two or three realistic options, always including "do the simplest thing". For each, sketch how it would land in this codebase: which modules change, what new components appear.
4. Compare on the same axes: complexity to build and run, failure modes, scaling limit and when you would hit it, migration cost from today, reversibility, and what the team must learn.
5. Quantify when you can. "Adds one network hop, about 5 to 20 ms" beats "adds latency".
6. Pick one. Explain what would have to be true for a different option to win.

## Rules

- Do not recommend a pattern for its own sake. Boring and reversible wins ties.
- Mark every unverified assumption as an assumption.
- Do not write implementation code. Pseudocode for an interface is fine.

## Report

Recommendation first. Then the options table, the key risks of the chosen option with mitigations, the first reversible step, and the signals that mean revisit this decision.

What it does

Design debates drift when nobody has read the code. This subagent reads the parts of your system a decision touches, states the constraints it found, and compares two or three real options instead of a generic list of patterns.

It ends with one recommendation, the cost of being wrong, and a way to reverse course. It does not write code or create files.

Example

you › Should we split billing into its own service? It is 15% of our code.

agent › Recommend: no, extract a module boundary first. billing/ is imported from 31 places and shares the orders table, so a service split adds distributed transactions for no scaling gain. Step one: route all access through billing/index.ts (about 2 days). Revisit if billing needs an independent deploy cadence or its own datastore.

Questions

Does it give one answer or a menu?
One. The options are compared so you can see the reasoning, but it commits to a single recommendation and states what would change its mind.
Can it design from an empty repo?
Yes, but with less evidence. It will state the assumptions it had to make so you can correct them.
  • API Reviewer

    SubagentBackend and APIs

    Free
  • Background Job Reviewer

    SubagentBackend and APIs

    Free
  • Caching Advisor

    SubagentBackend and APIs

    Free
  • Endpoint Scaffolder

    SubagentBackend and APIs

    Free