Designing Architecture

Methodology

Phase 1 — Requirements

1. Parse the feature into functional and non-functional requirements (latency, throughput, availability, consistency, failure modes).
2. Identify constraints: language, framework, existing codebase, deployment target, regulatory.
3. Read the project's architecture map (often docs/architecture.md) — see reviewing-changes/reference/architecture-map-pattern.md for the convention. Identify integration points with existing modules.

Phase 2 — Technology landscape scan

1. Discover candidates. Search awesome-lists (awesome-, awesome-), GitHub by topic, package registries (PyPI, npm, crates.io). For data layer questions, also DB-Engines and CNCF Landscape.
2. Evaluate each candidate with consistent dimensions:

• GitHub stars and trend, last commit, release cadence.
• Open vs closed issue ratio.
• Documentation quality (fetch the README; check for runnable examples).
• License compatibility (MIT/Apache/BSD safe; AGPL/GPL needs deliberate decision).
• Dependency footprint (transitive count, security history).

1. Cross-check official docs. Verify the library actually supports the exact use case — a star count doesn't.
2. Compare alternatives in a table with consistent rows and explicit trade-offs.

Phase 3 — Pattern selection

1. Identify candidate patterns from problem shape:

• Creational — Factory, Builder, Singleton (only if state is genuinely global).
• Structural — Adapter, Decorator, Facade, Proxy.
• Behavioural — Strategy, Observer, Command, Chain of Responsibility, State.
• Domain — Repository, Unit of Work, Specification, Value Object.
• Architectural — Hexagonal / ports-and-adapters, Pipes & Filters, Event-Driven, CQRS, Saga, Outbox.

1. Select the minimum patterns the problem needs. No pattern tourism.
2. Map selections to the project's conventions; don't introduce a new pattern when an existing one fits.

Phase 4 — Design

1. Define component structure: classes / modules / interfaces / boundaries.
2. Define data flow: inputs → processing → outputs, including failure paths.
3. Define error-handling strategy (retry, dead-letter, circuit-breaker, idempotency keys).
4. Define configuration, secrets handling, dependency injection.
5. Produce an ASCII diagram showing components, dependencies, and data direction.

Phase 5 — Implementation plan

1. Decompose into TDD-ready steps. Each step:

• Sized for one red-green-refactor cycle.
• Independently testable.
• Delivers incremental value.

1. Order by dependency (what must exist before what).
2. Hand off to running-tdd-cycles for execution. Do not implement here.

Database architecture overlay

When the design includes a data layer, run a parallel mini-pipeline:

1. Pick the technology family.

• Relational (PostgreSQL, MySQL) — strong consistency, complex joins, transactions.
• Document (MongoDB, DynamoDB) — flexible schema, horizontal scale, simple access.
• Key-value (Redis, DynamoDB) — sub-ms reads, cache-like access.
• Time-series (TimescaleDB, InfluxDB, ClickHouse) — append-heavy, time-range queries.
• Graph (Neo4j, Neptune) — multi-hop relationships are first-class.
• Search (Elasticsearch, OpenSearch, Meilisearch) — full-text, faceted filtering.
• NewSQL (CockroachDB, Spanner, YugabyteDB) — global consistency at scale.

Decide via CAP-theorem framing: which two of consistency, availability, partition tolerance does the workload force?

1. Schema design. Conceptual (ER diagram) → logical (3NF or deliberate denormalisation) → physical (data types, partitioning, sharding key). State trade-offs explicitly.

1. Indexing strategy. B-tree for equality/range, Hash for exact match, GiST/GIN for full-text/geometry, BRIN for huge ordered tables, partial/filtered indexes for hot subsets. Composite indexes ordered by query selectivity.

1. Migration plan. Zero-downtime where possible (expand → backfill → contract). Tooling (Alembic, Flyway, Liquibase, Prisma). Backward + forward compatibility for online deploys.

1. Security and compliance. RBAC and row-level security where applicable. At-rest + in-transit encryption. Audit logging for sensitive ops.

Output

Produce a single Markdown document. The architecture document should be self-contained and feed directly into running-tdd-cycles.

---
purpose: Architecture design for 
---

# Architecture — 

## 1. Requirements
Functional + non-functional, including SLA targets if relevant.

## 2. Technology selection

### Selected
| Library | Purpose | Stars | Last release | Why |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |

### Rejected
| Library | Reason |
|---|---|
| ... | ... |

### Sources
- [1] 
- [2] 
- [3] 

## 3. Patterns
The patterns selected and the concrete reason each fits this problem.

## 4. Architecture
ASCII diagram + per-component description.

## 5. Data layer (if applicable)
Technology, schema, indexes, migration plan.

## 6. TDD-ready implementation plan
1. **Step 1: ** — ; depends on: none; test: .
2. **Step 2: ** — ...
   ...

## 7. Open questions
Decisions that need user input before implementation begins.

Behavioural traits

• Research before recommending. Never propose a library without checking GitHub activity, docs, and at least one alternative.
• Minimum viable architecture. Design only what the feature needs. No speculative abstractions.
• Ecosystem first. Always prefer established libraries to custom code. Check awesome-*, package registries, and official docs before writing anything bespoke.
• Explicit trade-offs. When choosing between alternatives, state what is gained and what is lost.
• TDD-ready output. Decompose every architecture into red-green-refactor-sized steps.
• Codebase-aware. Read the architecture map and existing code before designing. Follow established conventions.
• No pattern tourism. Apply a pattern only when it solves a concrete problem in the current feature.
• Recency matters. Prefer libraries with commits in the last six months and recent releases.

Cross-references

• running-tdd-cycles — receives the implementation plan from this skill.
• reviewing-changes — verifies the implementation against this design.
• python-conventions / go-conventions / solidity-conventions — language-specific tooling and idioms feed into the design.
• engineering-philosophy — KISS, YAGNI, Use Libraries, No Magic dominate during design.

Reference

• [reference/architect-agent.md](reference/architect-agent.md) — original Claude-Code architect agent verbatim (model: opus).
• [reference/database-architect-agent.md](reference/database-architect-agent.md) — original Claude-Code database-architect agent verbatim (model: opus).
• [reference/qualified-sources.md](reference/qualified-sources.md) — curated list of research sources (awesome-*, ThoughtWorks Radar, DB-Engines, CNCF Landscape, Refactoring.guru, Fowler's catalogue, 12-factor, OWASP).
• [reference/pattern-catalogue.md](reference/pattern-catalogue.md) — design pattern descriptions with applicability tests.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: swell-agents
• Source: swell-agents/coding-skills
• License: MIT

Install and usage instructions live in the source repository linked above.