Architecture design
Skill SWEStash/swe-workflow-skills/skills/architecture-design
Guide architectural and structural decisions using Architecture Decision Records (ADRs) — new services, pattern choices, database selection, component boundaries, state management, costly-to-reverse decisions. Triggers: how should I architect, which pattern, design decision, should I use X or Y, system design, ADR, component design, architectural trade-off. Owns internal-structure decisions — build vs buy/adopt a vendor or OSS capability → build-vs-buy.From its SKILL.md
npx -y skills add SWEStash/swe-workflow-skills --skill architecture-designAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.4 KB, as published. Nobody here has run it
Architecture Design
Help the user make well-reasoned architectural decisions and document them in Architecture Decision Records (ADRs). Good architecture is about managing trade-offs explicitly, not finding perfect solutions.
Workflow
Step 0: Inventory What Already Exists
If a system is already running, establish what it already provides before proposing a new service, module, boundary, or pattern. Map the current state directly from the codebase — don't infer it from the requirements, the docs, or memory. Docs describe the system someone intended; the code is the one you have.
Cover both:
- Artifacts — existing services, modules, and seams that already own, or could own, the responsibility in question. Search by capability, not just by name: the component that does this may be called something else entirely.
- Written decisions — the ADR log, established conventions, and prior audit findings. A decision already made and recorded is not yours to re-litigate silently; supersede it explicitly or work within it.
Exit condition — one line, then keep going in the same response:
"<existing component> already handles <responsibility>; it does / does not
serve this because <reason>."
This step is not a gate on delivering. Greenfield — nothing built yet, or nothing you can reach — closes it in one line: say so and go straight to Step 1. When you can't inspect, name what you would check and continue under stated assumptions. Never answer a design question with inventory and questions alone; carry the options, the recommendation, and the trade-offs in the same reply.
This constrains the input, not the choice. A new component is a fine outcome; an unexamined one isn't.
Step 1: Frame the Decision
Identify the exact decision to be made. A good architectural question is specific and scoped:
- Too broad: "How should I design the backend?"
- Right scope: "Should user authentication be a separate microservice or a module within the monolith?"
If the user's question is too broad, help narrow it by asking:
- What triggered this decision? (new feature, scaling issue, tech debt)
- What are the constraints? (team size, timeline, existing stack)
- What's the blast radius? (which parts of the system are affected)
Step 2: Explore the Context
Understand the current state before proposing changes:
- Current architecture: the Step 0 finding — what exists today, established from the code rather than assumed. If you can't state it, Step 0 isn't done.
- Quality attributes that matter: Performance? Scalability? Developer experience? Maintainability? Deployment simplicity?
- Team context: Team size, expertise, on-call burden
- Growth trajectory: Expected scale in 6-12 months (not 5 years — YAGNI)
Step 3: Generate Options
Present 2-4 viable options. For each option:
- Name it clearly (e.g., "Separate Auth Service" vs "Auth Module in Monolith")
- Describe the approach in 2-3 sentences
- Analyze trade-offs against the quality attributes identified in Step 2
- Estimate complexity (implementation effort, operational overhead)
- Identify reversibility — how hard is it to change this decision later?
Avoid presenting a straw-man option just to make the preferred one look better.
Step 4: Apply Design Principles
Evaluate each option through these lenses:
- KISS: Which option is simplest to implement and operate?
- YAGNI: Which avoids building for hypothetical future needs?
- Functional Independence: Which gives the cleanest boundaries and lowest coupling?
- Separation of Concerns: Which isolates responsibilities clearly?
- DRY: Which avoids duplication of logic or data?
- SOLID: Does the design respect Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion? See references/solid-principles.md.
- Clean Architecture: Does the dependency direction point inward? Are business rules protected from infrastructure details? See references/clean-architecture.md.
- Component boundaries: Are components cohesive (CCP, CRP) and acyclic (ADP)? Do dependencies flow toward stability (SDP)? See references/component-principles.md.
Document which principles favor which option. Conflict between principles is expected — that's why it's a decision, not a formula.
See references/principles.md for deeper guidance on applying KISS, YAGNI, coupling, and separation of concerns to architecture decisions.
Step 5: Make a Recommendation
State the recommended option clearly, with reasoning. Structure it as:
- Recommendation: Option X
- Primary reason: The most compelling argument (one sentence)
- Key trade-off accepted: What you're giving up and why it's acceptable
- Conditions that would change this decision: Future triggers to revisit
Step 6: Document the ADR
Produce an ADR using the template at templates/adr.md. Save it in the project's decision log (e.g., docs/decisions/NNN-decision-title.md).
ADRs are immutable records. If a decision is superseded, create a new ADR that references the old one — don't edit the original.
For visual architecture documentation (system diagrams, runtime flows, infrastructure topology), see the architecture-documentation skill.
When the decision is whether a capability should be built at all versus bought or adopted (vendor/SaaS/OSS, TCO, lock-in, exit costs), use build-vs-buy — it produces the same ADR-style record, but for sourcing rather than structure.
When to Split Decisions
If the analysis reveals multiple independent decisions bundled together, split them into separate ADRs. For example, "How should we handle caching?" might split into:
- ADR-001: Cache invalidation strategy
- ADR-002: Cache storage technology
- ADR-003: Cache warming approach
What ships with it: 6 files
28.8 KB alongside SKILL.md
evals/
- evals.json2.6 KB
references/
- clean-architecture.md8.2 KB
- component-principles.md6.8 KB
- principles.md3.8 KB
- solid-principles.md6.1 KB
templates/
- adr.md1.3 KB
Gives 0 of the 12 instructions most architecture codebase skills give
Counted across 858 of the 1,304 authors here whose files we hold, read 2026-09-06
- Apply the deletion test to identify shallow modulesin 32 of 858, across 31 files
- Read domain glossary and ADRs before exploringin 22 of 858, across 19 files
- Use Tailwind and Mermaid via CDN for reportsin 21 of 858, across 18 files
- Document architecture decision recordsin 20 of 858, across 12 files
- Offer to record ADRs for rejected candidatesin 17 of 858, across 14 files
- Limit primary navigation to four to seven itemsin 17 of 858, across 7 files
- Write HTML report to the system temp directoryin 17 of 858, across 14 files
- Read product marketing context before asking questionsin 16 of 858, across 6 files
- Use Mermaid graph TD for visual sitemapsin 15 of 858, across 5 files
- Ensure every page has at least one internal linkin 15 of 858, across 5 files
- Use ASCII tree format for page hierarchy draftsin 15 of 858, across 5 files
- Enforce lowercase URLs with hyphensin 15 of 858, across 5 files
Said here and by no other author read
- Map current state directly from the codebase
- Identify existing components and written decisions
- State existing component responsibility in one line
- Help narrow broad architectural questions
- Identify quality attributes and team context
- Evaluate options using design principles
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.