architecture-decision
This skill structures architecture decisions by enforcing a rigorous trade-off analysis: context, constraints, at least three viable options, and explicit consequences. It produces formal decision records (ADR/RFC/RFD) that capture both positive and negative outcomes, ensuring decisions remain auditable and reversible.
Architecture Decision documents your design choices with full context, constraints, options, and trade-off analysis.
AI-generated summary based on this skill's SKILL.md
Install
softspark/ai-toolkit/architecture-decision · repository language: Python
git clone https://github.com/softspark/ai-toolkit
cp -r ai-toolkit/app/skills/architecture-decision ~/.claude/skills/architecture-decisionnpx skillfed install softspark/ai-toolkit/architecture-decisionFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I document architecture decisions?
architecture-decision structures your documentation by capturing context, constraints, at least three viable options, and explicit trade-offs. It enforces a rigorous format—similar to ADR (Architecture Decision Record) or RFC templates—that records both positive and negative consequences. This ensures decisions remain auditable, reversible, and justified for future teams reviewing why a choice was made.
What format should an ADR template for design choices follow?
architecture-decision uses a structured template that includes: the decision's context and constraints, multiple architectural options evaluated side-by-side, a trade-off analysis comparing reliability, scalability, cost, and maintainability, and documented consequences (both positive and negative). This format makes it easy to compare approaches and understand why one was selected over alternatives.
How can I compare database options like SQL vs NoSQL?
architecture-decision provides a trade-off matrix framework to evaluate critical factors: reliability, scalability, cost, and maintainability. For SQL vs NoSQL, you'd document constraints (consistency vs availability needs), list both options plus at least one hybrid approach, then explicitly compare each on your key criteria. This structured comparison captures trade-offs and consequences for each choice.
What should I include when documenting design trade-offs?
architecture-decision requires you to record context (why the decision matters), constraints (what limits your options), at least three viable approaches, and explicit consequences—both positive outcomes and negative trade-offs—for each option. This comprehensive capture ensures stakeholders understand what was gained and lost, making decisions transparent and reversible if circumstances change.
How does architecture-decision help evaluate architectural options?
architecture-decision enforces a rigorous evaluation process: define your constraints upfront, present multiple options (minimum three), then systematically compare them using a trade-off matrix covering reliability, scalability, cost, and maintainability. By documenting both positive and negative consequences, you create a formal decision record (ADR/RFC/RFD) that justifies your choice and remains auditable for future reference.
Can architecture-decision be used for infrastructure choices?
Yes. architecture-decision applies to any architectural decision—infrastructure, technology, or design. Whether comparing cloud providers, container orchestration platforms, or deployment strategies, the skill guides you through the same structured process: context, constraints, multiple options, trade-off analysis, and documented consequences. This ensures infrastructure decisions are as well-justified and auditable as any other architectural choice.
SKILL.md
rendered from the published skill — quoted content, verbatim
Architecture Decision Skill
Core Philosophy: "Everything is a Trade-off"
There are no "best solutions", only solutions with the right set of trade-offs for the specific context.
Decision Making Process (RFD / RFC)
- Context: What is the problem? Why now?
- Constraints: Budget, Time, Skillset, Legacy.
- Options: Propose at least 3 viable options.
- Trade-off Analysis: Compare constraints vs options.
- Recommendation: Choose one and justify.
Trade-off Analysis Matrix (Template)
| Feature | Option A (e.g. SQL) | Option B (e.g. NoSQL) | Option C (e.g. File) |
|---|---|---|---|
| Scalability | Medium (Vertical) | High (Horizontal) | Low |
| Consistency | Strong (ACID) | Eventual (BASE) | N/A |
| Complexity | Low (Known) | Medium (New tech) | Low |
| Cost | $$ | $$$ | $ |
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 2 files
app/skills/architecture-decision/SKILL.md
app/skills/architecture-decision/templates/adr-template.md