Architecture Designer
Capture why your stack and structure choices were made so future-you (and agents) can refactor without relitigating old debates.
Overview
Architecture Designer is an agent skill most often used in Build (also Validate and Operate) that produces numbered Architecture Decision Record markdown capturing context, the decision, consequences, and rejected altern
Install
npx skills add https://github.com/jeffallan/claude-skills --skill architecture-designerWhat is this skill?
- Complete ADR markdown skeleton: Status, Context, Decision, Consequences (positive, negative, neutral), Alternatives Cons
- Worked ADR-001 example (PostgreSQL on RDS) showing how constraints map to a clear decision statement
- Forces explicit tradeoff lists instead of one-line “we picked X” notes in chat or README fragments
- Numbered ADR-{n} convention compatible with a growing docs/adr/ folder in a solo repo
- Status lifecycle fields (Proposed, Accepted, Deprecated, Superseded) for decision churn over time
- ADR template defines six primary sections: Status, Context, Decision, Consequences, Alternatives Considered, References
- Bundled example ADR-001 covers PostgreSQL selection with positive, negative, and neutral consequence lists
Adoption & trust: 4.3k installs on skills.sh; 9.7k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You keep re-arguing the same stack and structure choices because the original rationale lived only in chat or a terse commit message.
Who is it for?
Solo builders documenting non-trivial technical tradeoffs (data store, deployment model, auth) before the codebase grows messy.
Skip if: Throwaway spikes or single-file scripts where no durable architectural choice needs a written record.
When should I use this skill?
You need to document a significant architectural or infrastructure decision with context, explicit tradeoffs, and rejected options before or after implementation.
What do I get? / Deliverables
You get a committed ADR-{n} markdown file your team and agents can cite before changing databases, boundaries, or hosting without reopening every past option.
- Numbered ADR markdown file (ADR-{n}) with status and consequence buckets
- Alternatives Considered section listing rejected options and why
- Optional References links to RFCs, vendor docs, or prior discussions
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Architecture Decision Records are living build-time documentation; the build phase is where most irreversible technical choices land and need a canonical shelf in the catalog. The skill ships an ADR markdown template and worked example—outputs belong alongside project docs, not in launch or grow tooling.
Where it fits
Record why you narrowed the MVP to a monolith plus managed Postgres before writing feature code.
Document the queue-or-cron choice for background jobs so later refactors respect original latency assumptions.
Capture the rationale for Stripe versus Paddle before wiring webhooks and tax behavior.
Attach an Accepted ADR to a PR that changes hosting so reviewers see supersession rules upfront.
Publish ADR-00N superseding RDS sizing when traffic crosses the threshold named in the original decision.
How it compares
Use structured ADR files instead of ad-hoc architecture notes scattered across issues and LLM threads.
Common Questions / FAQ
Who is architecture-designer for?
Indie and solo developers shipping SaaS, APIs, or agent-backed products who want lightweight, commit-friendly decision history without a heavyweight enterprise framework.
When should I use architecture-designer?
During Validate when locking scope and stack; during Build when choosing databases, boundaries, or cloud layout; and during Operate when superseding an old decision—you run it whenever a choice is costly to undo and needs a durable write-up.
Is architecture-designer safe to install?
It is documentation-oriented markdown guidance; review the Security Audits panel on this Prism page and the upstream repo before trusting any third-party skill in your agent workflow.
SKILL.md
READMESKILL.md - Architecture Designer
# ADR Template ## ADR Format ```markdown # ADR-{number}: {Title} ## Status [Proposed | Accepted | Deprecated | Superseded by ADR-XXX] ## Context [Describe the situation and forces at play. What is the problem? What constraints exist? What are we trying to achieve?] ## Decision [State the decision clearly. What are we going to do?] ## Consequences ### Positive - [Benefit 1] - [Benefit 2] ### Negative - [Drawback 1] - [Drawback 2] ### Neutral - [Side effect that is neither good nor bad] ## Alternatives Considered [What other options were evaluated and why were they rejected?] ## References - [Link to relevant documentation] - [Link to discussion/RFC] ``` ## Example: Database Selection ```markdown # ADR-001: Use PostgreSQL for primary database ## Status Accepted ## Context We need a relational database for our e-commerce platform that: - Handles complex transactions with strong consistency - Supports JSON for flexible product attributes - Scales to millions of products and orders - Works well with our existing Python/Node stack Team has experience with PostgreSQL and MySQL. Budget allows for managed database service. ## Decision Use PostgreSQL as the primary database, hosted on AWS RDS. ## Consequences ### Positive - ACID compliance for financial transactions - Rich feature set (JSON, full-text search, CTEs) - Strong community and tooling - Excellent performance with proper indexing - Free and open source ### Negative - Vertical scaling has limits (addressed with read replicas) - Requires DBA expertise for optimization - AWS RDS costs for high availability ### Neutral - Team will need to learn PostgreSQL-specific features - Migration from current SQLite dev database needed ## Alternatives Considered **MySQL** - Rejected: Less feature-rich for JSON operations - Considered: Similar cost, familiar to team **MongoDB** - Rejected: Relational data model needed for orders/inventory - Considered: Great for product catalog flexibility **CockroachDB** - Rejected: Higher cost, team unfamiliar - Considered: Better horizontal scaling ## References - https://www.postgresql.org/docs/current/ - Internal RFC: Database Selection for E-commerce Platform ``` ## ADR Naming Convention ``` docs/ └── adr/ ├── 0001-use-postgresql-database.md ├── 0002-adopt-microservices.md ├── 0003-implement-event-sourcing.md └── README.md ``` ## Quick Reference | Section | Purpose | Key Question | |---------|---------|--------------| | Status | Current state | Is this active? | | Context | Background | Why are we deciding? | | Decision | The choice | What did we choose? | | Consequences | Impact | What happens now? | | Alternatives | Options | What else was considered? | # Architecture Patterns ## Pattern Comparison | Pattern | Best For | Team Size | Trade-offs | |---------|----------|-----------|------------| | **Monolith** | Simple domain, small team | 1-10 | Simple deploy; hard to scale parts | | **Modular Monolith** | Growing complexity | 5-20 | Module boundaries; still single deploy | | **Microservices** | Complex domain, large org | 20+ | Independent scale; operational complexity | | **Serverless** | Variable load, event-driven | Any | Auto-scale; cold starts, vendor lock | | **Event-Driven** | Async processing | 10+ | Loose coupling; debugging complexity | ## Monolith ``` ┌─────────────────────────────────────┐ │ Application │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │Users│ │Orders│ │Products│ │ │ └─────┘ └─────┘ └─────┘ │ │ └──────────┬──────────────┘ │ │ Database │ └─────────────────────────────────────┘ ``` **When to Use**: - Starting a new project - Small team (< 10 developers) - Simple domain - Rapid iteration needed **Pros**: Simple deployment, easy debugging, no network latency **Cons**: Hard to scale independently, technology locked, deployment risk ## Microservices ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Users