home / skills / vudovn / antigravity-kit / architecture

architecture skill

safe

This skill helps you design architecture by applying an ADR-driven framework for requirements, trade-offs, and documentation.

npx playbooks add skill vudovn/antigravity-kit --skill architecture

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

1.7 KB

---
name: architecture
description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
allowed-tools: Read, Glob, Grep
---

# Architecture Decision Framework

> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."

## 🎯 Selective Reading Rule

**Read ONLY files relevant to the request!** Check the content map, find what you need.

| File | Description | When to Read |
|------|-------------|--------------|
| `context-discovery.md` | Questions to ask, project classification | Starting architecture design |
| `trade-off-analysis.md` | ADR templates, trade-off framework | Documenting decisions |
| `pattern-selection.md` | Decision trees, anti-patterns | Choosing patterns |
| `examples.md` | MVP, SaaS, Enterprise examples | Reference implementations |
| `patterns-reference.md` | Quick lookup for patterns | Pattern comparison |

---

## 🔗 Related Skills

| Skill | Use For |
|-------|---------|
| `@[skills/database-design]` | Database schema design |
| `@[skills/api-patterns]` | API design patterns |
| `@[skills/deployment-procedures]` | Deployment architecture |

---

## Core Principle

**"Simplicity is the ultimate sophistication."**

- Start simple
- Add complexity ONLY when proven necessary
- You can always add patterns later
- Removing complexity is MUCH harder than adding it

---

## Validation Checklist

Before finalizing architecture:

- [ ] Requirements clearly understood
- [ ] Constraints identified
- [ ] Each decision has trade-off analysis
- [ ] Simpler alternatives considered
- [ ] ADRs written for significant decisions
- [ ] Team expertise matches chosen patterns

Overview

This skill is an architectural decision-making framework for guiding system design, requirements analysis, trade-off evaluation, and ADR documentation. It helps teams turn requirements and constraints into explicit architecture choices with rationale. The goal is to keep designs as simple as possible and document why complexity was introduced.

How this skill works

The skill walks you through discovery questions to clarify requirements, constraints, and project classification. It provides a trade-off analysis method and ADR templates to capture decisions and their consequences. Decision trees and pattern guidance help select appropriate architectural patterns while flagging anti-patterns and simpler alternatives.

When to use it

At project kickoff to translate requirements into architectural scope and constraints.
When evaluating multiple designs or technologies and needing structured trade-offs.
Before major changes to system structure, to ensure alternatives and risks are considered.
When producing ADRs for team alignment and future auditability.
During architectural reviews to validate simplicity and team expertise alignment.

Best practices

Start with the simplest viable architecture and add complexity only when proven necessary.
Document each significant choice with an ADR that states context, decision, trade-offs, and consequences.
Explicitly capture constraints (cost, latency, compliance) and verify decisions against them.
Compare at least one simpler alternative for every complex pattern selected.
Use the validation checklist before finalizing: requirements, constraints, trade-offs, ADRs, and team skills.

Example use cases

Designing an MVP where minimizing cost and time-to-market is the priority.
Choosing between eventual consistency and strong consistency for a distributed data store.
Evaluating monolith vs. microservices based on team size, operational maturity, and release cadence.
Documenting the rationale for adopting a particular message broker or caching strategy.
Performing an architecture review before a major refactor to ensure decisions are justified.

FAQ

When should I write an ADR?

Write an ADR for any decision that affects system structure, operational model, or has lasting impact; aim to document decisions as they are made, not retroactively.

How do I keep architecture simple as the system grows?

Prefer minimal viable patterns first, continuously evaluate complexity against measured needs, and refactor only when evidence shows current design limits are reached.