Design Code Architecture
Deliberate architecture for a new system
Takes you from an app idea to a deliberate architecture: boundaries, domain model, data decisions, and resilience, making only the expensive-to-reverse decisions and deferring the rest. It orchestrates its eight skills phase by phase, asking you the decision questions at every step and recording every result in your project's docs/ folder so the journey resumes across sessions.
npx skills add wondelai/skills/design-code-architecture --global - 01
Do source-code dependencies point inward — is the core testable with no DB, web, or framework?
Clean Architecture → docs/ARCHITECTURE.md - 02
Where does the business actually split, and what does each term mean?
Domain-Driven Design → docs/ARCHITECTURE.md - 03
How little system does our real load actually need?
System Design → docs/ARCHITECTURE.md - 04
Which data model, storage engine, and consistency does each workload need?
Data-Intensive Apps → docs/ARCHITECTURE.md - 05
Is complexity hidden behind deep modules, or is this classitis?
Software Design → docs/TECH-DEBT.md - 06
Will it degrade gracefully when a dependency is slow or down?
Release It! → docs/RELIABILITY.md - 07
What thin slice proves the boundaries, and what habits keep them reversible?
Pragmatic Programmer → docs/TESTING.md + docs/TECH-DEBT.md - 08
What is essential for v1, and what speculative abstraction do we cut?
The 37signals Way → docs/ARCHITECTURE.md + docs/TECH-DEBT.md
Each phase asks the question, then writes the answer before the next one starts.
The long read behind the phases: How to Design the Best Possible Architecture for a New App
02 What it is
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/.
03 In practice
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.
Written to your repo
- docs/ARCHITECTURE.md
- docs/TECH-DEBT.md
- docs/RELIABILITY.md
- docs/TESTING.md
- docs/DESIGN-CODE-ARCHITECTURE-PLAN.md journey tracker
Stop anytime. The tracker records which phases are done and which decision is next, so a new session opens at the unanswered question.
04 Prompts
Say it like this.
Name the journey at the end of a prompt and it takes over from phase one. Say it again in a later session and it resumes at the unanswered question.
We're starting a new service — design the architecture with me, decision by decision. using design-code-architecture skill
Run the architecture journey for this system; default to a modular monolith. using design-code-architecture skill
Resume the architecture design from the decision log. using design-code-architecture skill
05 Fit
One prompt runs it.
Every phase asks before it acts, and every decision lands in your project's docs/ folder as a living document.
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.
07 Questions
Before you install.
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.
Eight skills, one deliberate order.
Run the whole journey with one prompt.
npx skills add wondelai/skills/design-code-architecture --global MIT licensed · Claude, Claude Code, Codex, Cursor, OpenClaw, Hermes · No account