MustafaKucukcoskun/Refine-agent-kit / .agents/skills/architecture
architecture
VerifiedArchitecture Decision Framework
"Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."
When to Use vs. Related Skills
| You want to… | Use |
|---|---|
| Choose between 2+ tech options | architecture (this) |
| Write an ADR | architecture (this) |
| Refactor messy code | refactoring-patterns |
| Improve code quality | clean-code |
| Design DB schema | database-design |
| Design API shape | api-patterns |
🎯 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
Decision Quality Protocol (MANDATORY)
For each architectural milestone, produce a Decision Packet.
Decision Packet Structure
- Problem statement and desired outcome.
- Constraint envelope (hard/soft/open).
- Option space (minimum 3 viable options).
- Trade-off scoring matrix.
- Chosen option + rationale.
- Risks, mitigations, and rollback strategy.
- Revisit triggers (when to re-open this decision).
Trade-off Scoring Matrix
Score each option from 1 to 5 on these dimensions:
| Dimension | Question |
|---|---|
| Correctness | Does it satisfy core requirements safely? |
| Operability | Is it observable, debuggable, supportable? |
| Time-to-Value | How fast can the team deliver useful value? |
| Team Fit | Does current team expertise support it? |
| Cost Profile | Infra and implementation cost trajectory |
| Evolvability | Can it adapt to next-stage product needs? |
Use weighted scoring only when stakeholders agree on priorities.
Unknown-Unknown Scan
Before finalizing architecture, answer:
- Which assumptions are least validated?
- Which integration points can fail silently?
- What breaks first at 10x scale?
- Which decision creates irreversible lock-in?
If uncertainty is high, prefer reversible decisions and staged rollout.
SaaS and Product Systems Guidance
When user asks for full SaaS/system design, avoid single-path recommendations.
Always provide:
- Baseline architecture (fastest reliable path).
- Scale-ready variant (for growth stage).
- Frontier variant (higher upside, higher risk).
Then recommend one path based on explicit constraints, not preference bias.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |