# Architect

> Design the shape of a non-trivial module, API, or system before implementing it. Use when a design decision has more than one reasonable answer, when introducing a new abstraction or interface, or when getting the shape wrong would be expensive to undo.

- Skill: `vasu-devs/architect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vasu-devs/architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vasu-devs/architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: vasu-devs (https://skillmd.com/u/vasu-devs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vasu-devs/architect

---


```
 █████╗ ██████╗  ██████╗██╗  ██╗██╗████████╗███████╗ ██████╗████████╗
██╔══██╗██╔══██╗██╔════╝██║  ██║██║╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝
███████║██████╔╝██║     ███████║██║   ██║   █████╗  ██║        ██║
██╔══██║██╔══██╗██║     ██╔══██║██║   ██║   ██╔══╝  ██║        ██║
██║  ██║██║  ██║╚██████╗██║  ██║██║   ██║   ███████╗╚██████╗   ██║
╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝   ╚═╝   ╚══════╝ ╚═════╝   ╚═╝
```

# Architect the shape first

Code is easy to write and hard to reshape. The interface you choose outlives the implementation. This skill produces a deliberate design instead of the first one that compiles.

## 1. Search before you build

Before designing anything custom, decide where this work belongs on the ladder:
- **Adopt** — a library/tool already does this well. Use it.
- **Extend** — something close exists; extend it.
- **Compose** — combine existing pieces.
- **Build** — only when the above genuinely don't fit.

Check package registries, the existing codebase, and installed skills/MCP tools first. Report what you found and why you're building rather than adopting. Most "new" problems are solved problems.

## 2. Design it twice (at least)

Never ship the first design. Generate **2-3 genuinely different** designs, each forced apart by a *different constraint*:
- minimize the interface surface
- maximize flexibility
- optimize the common case
- imitate a known, well-understood paradigm
- survive failure well (idempotency, partial-failure, retries, backpressure)

If subagents are available, dispatch them in parallel — one design each — so the options don't converge. Then compare.

## 3. Judge on depth, not effort

- A **deep** interface is small but hides significant complexity (good). A **shallow** one is a large surface over a thin implementation (bad — it just relocates complexity onto callers).
- Optimize for **ease of correct use** and **hardness of misuse**.
- Do **not** rank designs by how much code they take to implement — that's the cheapest part and the wrong axis.
- **Record the decision, including the losers.** Output a short comparison (each design × how it scores on the constraints / its key failure mode) and one sentence per rejected design saying exactly why it lost. A design chosen with no written loser isn't a decision — it's the first thing that compiled.

## 4. Earn every abstraction

- **Deletion test:** imagine deleting this module. If the same complexity reappears, duplicated across N callers, the module earned its place. If not, you're abstracting for its own sake — don't.
- **Two-adapter rule:** one adapter is a *hypothetical* seam; two real adapters prove a seam exists. Don't introduce an interface for a single implementation "in case." (This is `forge:principles` #2 applied to structure.) **Exception:** a test double or an external-boundary port (network, clock, third-party API, persistence you'll mock in tests) *is* the second adapter — seam it.

## 5. Name and record

- Name every concept in the project's **ubiquitous language** — one canonical term per idea, aliases explicitly retired. Update CONTEXT.md.
- Record an **ADR** only when the decision is hard to reverse *and* surprising without context *and* a real trade-off. Capture the *decision and why*, not file locations (those rot).

## Exit
Hand the chosen shape to `forge:plan` to break into vertical slices, then `forge:tdd` to build.