# Architect > Surface architectural friction in the codebase and design better module interfaces. Uses parallel sub-agents to explore radically different interface designs. Based on "deep modules" philosophy — small interfaces hiding significant complexity. Use when code feels tangled, hard to test, or hard to navigate. Use when this capability is needed. - Skill: `tomevault-io/architect-5` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/architect-5` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/architect-5/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/architect-5 --- # Architecture Improvement Explore the codebase to surface architectural friction, then design deep module interfaces using parallel sub-agents. A **deep module** (Ousterhout) has a small interface hiding a large implementation — more testable, more navigable, more resilient to change. ## Process ### 1. Discover project context Read domain documentation: 1. `docs/CONTEXT_MAP.md` — bounded contexts and relationships 2. `docs/contexts/*/CONTEXT.md` — ownership, invariants, contracts 3. `docs/UBIQUITOUS_LANGUAGE.md` — canonical terminology ### 2. Explore the codebase Navigate organically, noting friction: - Where does understanding one concept require bouncing between many small files? - Where are modules so shallow that the interface is nearly as complex as the implementation? - Where have pure functions been extracted "for testability" but the real bugs hide in how they're called? - Where do tightly-coupled modules create integration risk at the seams? - Which parts are untested or hard to test? - Where do bounded context boundaries leak? (one context directly accessing another's internals) The friction you experience IS the signal. ### 3. Present candidates Present a numbered list of deepening opportunities: ``` 1. [Cluster Name] Modules: [which modules/concepts are involved] Coupling: [why they're coupled — shared types, call patterns, co-ownership] Dependency type: [in-process | local-substitutable | remote-owned | true-external] Test impact: [what tests would be replaced by boundary tests] Context: [which bounded context(s)] 2. ... ``` Ask the user: **"Which of these would you like to explore?"** ### 4. Frame the problem space For the chosen candidate, write a user-facing explanation: - The constraints any new interface would need to satisfy - The dependencies it relies on - A rough illustrative code sketch (NOT a proposal — just grounding) Show this to the user, then proceed to design. ### 5. Design multiple interfaces Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface: - **Agent 1**: "Minimize the interface — 1-3 entry points max" - **Agent 2**: "Maximize flexibility — support many use cases and extension" - **Agent 3**: "Optimize for the most common caller — make the default case trivial" - **Agent 4** (if applicable): "Ports & adapters — inject all external dependencies" Each agent outputs: 1. Interface signature (types, methods, params) 2. Usage example 3. What complexity it hides internally 4. Dependency strategy 5. Trade-offs ### 6. Compare and recommend Present designs sequentially, then compare in prose: - Interface simplicity (fewer methods, simpler params = better) - General-purpose vs specialized - Implementation efficiency - Depth (small interface + deep implementation = good) - Ease of correct use vs ease of misuse Give your recommendation. Be opinionated — the user wants a strong read. ### 7. Capture the decision Based on user's choice: - If it warrants implementation → save as a spec in `docs/contexts//specs/` - If it's a significant architectural decision → consider an ADR in `docs/contexts//adrs/` - Update `docs/contexts//CONTEXT.md` if ownership or contracts change ## Dependency categories | Category | Description | Test strategy | |----------|------------|---------------| | **In-process** | Pure computation, no I/O | Merge and test directly | | **Local-substitutable** | Has local test stand-in (e.g., SQLite for Postgres) | Test with substitute | | **Remote but owned** | Your own services across network boundary | Port + adapter pattern, in-memory adapter for tests | | **True external** | Third-party services (Stripe, OpenAI) | Mock at boundary | ## Testing principle **Replace, don't layer.** Once boundary tests exist for a deepened module, delete the old shallow unit tests. Tests assert on observable outcomes through the public interface, not internal state. ## Related skills - `/domain` — stress-test the chosen design against the domain model - `/spec` — formalize the improvement into a spec - `/slice` — break the refactor into vertical slices - `/holistic` — understand the broader system before refactoring --- > Source: [AgentiveStack/skills](https://github.com/AgentiveStack/skills) — distributed by [TomeVault](https://tomevault.io).