decide-architecture

Select or review software architecture through a branching interview and pattern catalog.

Updated Jun 14, 2026
One-click install
npx skills add https://github.com/AdamKrysztopa/architectural-decisions --skill decide-architecture-adamkrysztopa
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: decide-architecture
Source: https://github.com/AdamKrysztopa/architectural-decisions/tree/main/skills/decide-architecture
Command: npx skills add https://github.com/AdamKrysztopa/architectural-decisions --skill decide-architecture-adamkrysztopa

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Choosing or assessing software architecture is error-prone: teams over-engineer simple apps with microservices and CQRS, or under-architect systems that genuinely need distribution. This Skill guides architecture decisions for new systems and audits existing codebases against a pattern catalog, always recommending the least architecture that meets the requirement. ## Core Features & Use Cases - Greenfield selection interview: Walks a decision tree covering structure, topology, data, presentation, and concurrency axes, composing one pick per axis into a labelled stack with the cost of every choice. - Refactoring review: Maps an existing codebase's actual architecture, finds mismatches using catalog review cues, and recommends targeted incremental moves rather than rewrites. - Decision recording: Persists outcomes as proposed decision files with a regenerated constitution, and supports ADR migration and drift observation at checkpoints. - Use Case: Ask whether a new payments service should be a monolith or microservices, and receive a composed stack table with per-axis rationale, costs, and a least-architecture check. ## Quick Start Ask the assistant to help you choose an architecture for a new service or review whether your current codebase's architecture still fits.

Frequently Asked Questions about decide-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose between a monolith and microservices?

The decision tree asks how you need to deploy and scale: one deployable with clean module boundaries means a modular monolith, while independent deploy and data ownership forced by org size or scale justifies microservices. Microservices carry distributed-data and operational costs, so they are not the default.

How to review whether an existing codebase's architecture still fits?

The refactoring mode maps the current structure, topology, and data flow, then compares them against catalog review cues like layer scatter or leaked infrastructure dependencies. It recommends the smallest targeted moves and explicitly names what to leave alone.

Does this skill cover LLM agent system design?

No, agentic and LLM systems use a different axis set and are handed off to the agentic-patterns skill. This skill covers regular software systems such as services, APIs, apps, and data platforms.

When should I use CQRS or event sourcing?

CQRS fits read-heavy workloads or systems needing many read shapes, where denormalized read models pay off. Event sourcing applies when full history is the source of truth, such as heavy audit, replay, or temporal queries; both add synchronization and versioning complexity.

What happens to the architecture decision after the interview?

The outcome is written as a single status: proposed decision file containing context, decision, and consequences, and the constitution is regenerated. A human later promotes it to active; nothing becomes enforced automatically.