| name | designing-architecture |
| description | Design pre-implementation architecture: components, libraries, data flow, schema. |
Methodology
Phase 1 — Requirements
- Parse the feature into functional and non-functional requirements (latency, throughput, availability, consistency, failure modes).
- Identify constraints: language, framework, existing codebase, deployment target, regulatory.
- 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
- Discover candidates. Search awesome-lists (
awesome-<language>, awesome-<domain>), GitHub by topic, package registries (PyPI, npm, crates.io). For data layer questions, also DB-Engines and CNCF Landscape.
- 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).
- Cross-check official docs. Verify the library actually supports the exact use case — a star count doesn't.
- Compare alternatives in a table with consistent rows and explicit trade-offs.
Phase 3 — Pattern selection
- 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.
- Select the minimum patterns the problem needs. No pattern tourism.
- Map selections to the project's conventions; don't introduce a new pattern when an existing one fits.
Phase 4 — Design
- Define component structure: classes / modules / interfaces / boundaries.
- Define data flow: inputs → processing → outputs, including failure paths.
- Define error-handling strategy (retry, dead-letter, circuit-breaker, idempotency keys).
- Define configuration, secrets handling, dependency injection.
- Produce an ASCII diagram showing components, dependencies, and data direction.
Phase 5 — Implementation plan
- Decompose into TDD-ready steps. Each step:
- Sized for one red-green-refactor cycle.
- Independently testable.
- Delivers incremental value.
- Order by dependency (what must exist before what).
- 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:
-
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?
-
Schema design. Conceptual (ER diagram) → logical (3NF or deliberate denormalisation) → physical (data types, partitioning, sharding key). State trade-offs explicitly.
-
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.
-
Migration plan. Zero-downtime where possible (expand → backfill → contract). Tooling (Alembic, Flyway, Liquibase, Prisma). Backward + forward compatibility for online deploys.
-
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 <feature>
---
# Architecture — <feature>
## 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] <awesome-list URL>
- [2] <official docs URL>
- [3] <ThoughtWorks Radar entry>
## 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: <title>** — <what to implement>; depends on: none; test: <what the failing test pins down>.
2. **Step 2: <title>** — ...
...
## 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
