# Design Code Architecture

> Deliberate architecture for a new system — a guided journey that orchestrates 8 AI agent skills, one decision at a time.

Published 2026-07-16 · Updated 2026-08-17 · Guided journey · Free and MIT-licensed
Canonical: https://skills.wondel.ai/skills/design-code-architecture/
Source: https://github.com/wondelai/skills/tree/main/design-code-architecture
Companion guide: https://skills.wondel.ai/guides/design-the-best-architecture-for-a-new-app/

**Install:** `npx skills add wondelai/skills/design-code-architecture --global`

## What is the Design Code Architecture journey?

Architecture is the set of decisions that are expensive to reverse, so this journey makes only those — deliberately, before a first sprint sets them by accident. Eight phases cover boundaries, the domain model, honest sizing, data and consistency, failure handling and scope, writing each choice and its alternatives into docs/.

## The 8 phases

1. **Clean Architecture** — Do source-code dependencies point inward — is the core testable with no DB, web, or framework? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/clean-architecture/)
2. **Domain-Driven Design** — Where does the business actually split, and what does each term mean? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/domain-driven-design/)
3. **System Design** — How little system does our real load actually need? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/system-design/)
4. **Data-Intensive Apps** — Which data model, storage engine, and consistency does each workload need? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/ddia-systems/)
5. **Software Design** — Is complexity hidden behind deep modules, or is this classitis? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/software-design-philosophy/)
6. **Release It!** — Will it degrade gracefully when a dependency is slow or down? → `docs/RELIABILITY.md` (https://skills.wondel.ai/skills/release-it/)
7. **Pragmatic Programmer** — What thin slice proves the boundaries, and what habits keep them reversible? → `docs/TESTING.md + docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/pragmatic-programmer/)
8. **The 37signals Way** — What is essential for v1, and what speculative abstraction do we cut? → `docs/ARCHITECTURE.md + docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/37signals-way/)

## What it produces

- `docs/ARCHITECTURE.md`
- `docs/TECH-DEBT.md`
- `docs/RELIABILITY.md`
- `docs/TESTING.md`
- `docs/DESIGN-CODE-ARCHITECTURE-PLAN.md`

## When to use Design Code Architecture — and when not to

Reach for it when:

- Design a new system's structure before the first sprint locks it in
- Draw boundaries and model the domain so the code speaks the business language
- Size the system honestly and skip the scaling machinery you don't need
- Make data, consistency, and failure-handling decisions explicitly
- Cut speculative abstractions with an appetite-bounded review

Reach for something else when:

- You want one storage or consistency question settled — Data-Intensive Apps answers it directly, no journey required.
- The product idea is still unvalidated — Create an App tests the riskiest assumption before committing to any structure.
- A weekend prototype needs hardening before launch — Improve Code Quality starts from a safety net, not a blank page.
- Boundaries need drawing inside a system already in production — Remove Technical Debt does that without a rewrite.

## Example prompts

- We're starting a new service — design the architecture with me, decision by decision. using design-code-architecture skill _(New service kickoff)_
- Run the architecture journey for this system; default to a modular monolith. using design-code-architecture skill _(Modular monolith default)_
- Resume the architecture design from the decision log. using design-code-architecture skill _(Resume journey)_

## Worked example — Design the Architecture Before the Code Locks It In

A new system is starting; the first sprint's shortcuts will become the permanent architecture unless you decide now.

```
We're designing a new system before the first sprint locks the architecture in. Run the design-code-architecture journey: boundaries, domain model, honest sizing, data decisions, failure design — every expensive-to-reverse decision logged in docs/ARCHITECTURE.md with alternatives.

Use design-code-architecture skill.
```

## Frequently asked questions

### How do I install the Design Code Architecture journey?

Run `npx skills add wondelai/skills/design-code-architecture --global`. It takes about 30 seconds and needs no account. The Design Code Architecture skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills.

### Which skills does the Design Code Architecture journey run, and what does it produce?

It orchestrates 8 skills across 8 phases — Clean Architecture, Domain-Driven Design, System Design, Data-Intensive Apps, Software Design, Release It!, Pragmatic Programmer, The 37signals Way — asking you one decision question per phase. Each answer is written to your project's docs/ folder (docs/ARCHITECTURE.md, docs/TECH-DEBT.md, docs/RELIABILITY.md, docs/TESTING.md, docs/DESIGN-CODE-ARCHITECTURE-PLAN.md), so the journey survives across sessions and you keep the reasoning, not just the output.

### How do I know I need a whole journey rather than one decision?

Count the open questions. If you can already name the boundaries, the domain language, the real load and the storage model, you have an architecture and need only the phase that closes the one gap — Data-Intensive Apps for storage, Release It! for failure behaviour. The journey earns its cost when several of those are still assumptions, because each phase’s answer constrains the next one’s options.

### Does this always end in a modular monolith?

Often, but not by rule. The System Design phase asks how little system your real load actually needs, and for most products the honest answer is one deployable with firm internal boundaries. If load, team topology or compliance say otherwise, the phase says so, and docs/ARCHITECTURE.md records the reasoning along with the alternatives you rejected. What the journey resists is distributing a system for reasons of fashion.

### The last phase cuts things. What does it cut?

Speculative abstraction — the plugin system for the one plugin, the repository interface over the one database, the queue for traffic you do not have. The 37signals phase asks what is essential for v1 and reviews everything the previous seven phases proposed against an appetite. Cuts and their reasoning go to docs/ARCHITECTURE.md and docs/TECH-DEBT.md, so a later session can reopen a decision instead of rediscovering it.

### How much existing code is too much for this journey?

A tracer bullet is fine — the Pragmatic Programmer phase actively wants a thin slice through every layer to prove the boundaries hold. A few weeks of feature work is fine too. Once the structure is load-bearing and people are working around it, you are past the point where choosing is cheap, and Remove Technical Debt is the journey that changes boundaries in a running system.