Skip to content

swell-agents/coding-skills / skills/designing-architecture

designing-architecture

Verified

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-<language>, awesome-<domain>), 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).
  3. Cross-check official docs. Verify the library actually supports the exact use case — a star count doesn't.
  4. 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.
  2. Select the minimum patterns the problem needs. No pattern tourism.
  3. 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.
  2. Order by dependency (what must exist before what).
  3. 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?
  2. Schema design. Conceptual (ER diagram) → logical (3NF or deliberate denormalisation) → physical (data types, partitioning, sharding key). State trade-offs explicitly.

  3. 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.

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

  5. 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

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall