- Home
- Skills
- Agents & Orchestration
- architecture decision helper
architecture decision helper
Evaluate architectural trade-offs and generate structured ADRs with evidence-based rationale.
Free
Works with the AI Agents you already use
architecture decision helper
Example session with this skill installed
Evaluate if we should move our notification logic from our Django monolith to a separate Go microservice. Team is 4 devs, no Go experience. Priority is operational simplicity.
- Read your context and instructions
- Compiled the architecture decision helper
I have evaluated the architectural transition for the notification system. Below is the structured Architecture Decision Record based on your team constraints and priority for operational simplicity.
ADR: Notification System Architecture
Status: Proposed
Context: Current Django monolith handles notification logic. Increasing load is causing deployment bottlenecks.
Constraints: 4-person backend team, no Go experience, priority on operational simplicity over absolute scalability.
| Option | Benefits | Costs | Risks |
|---|---|---|---|
| A: Status Quo (Monolith) | Zero infra overhead, utilizes existing team skills. | Deployment coupling remains. | Scaling limits of the monolith. |
| B: Celery Job Queue | Decouples execution, stays in Python, simple ops. | Requires Redis/RabbitMQ. | Worker management overhead. |
| C: Go Microservice | High performance, isolated scaling. | High learning curve, new deployment pipeline. | Significant delay due to skill gap. |
Decision and Rationale:
Accepted Option B (Celery Job Queue).
While Option C offers the best technical isolation, it violates the primary constraint of "operational simplicity" and team capability. Option B provides the necessary decoupling of the notification logic from the request-response cycle without introducing a new language runtime or complex cross-service auth.
Consequences:
- Positive: Improved response times for users; deployments won't be blocked by long-running notification tasks.
- Negative: Adds a dependency on a message broker (e.g., Redis).
Evidence and Assumptions:
- Assumption: Redis is easier for the current team to manage than a Go/K8s microservice stack.
- Evidence: Current bottlenecks are I/O bound during third-party API calls.
Next steps
- Review the Redis infrastructure requirements for the Celery backend.
- Define the retry logic and failure modes for the new worker queue.
- Update the
README.mdwith the new background task architecture.
Connects securely to your tools. The creator never sees your data.
About this skill
Architectural decisions often happen in a vacuum of vague preferences, leading to technical debt and missed requirements. This skill enforces a structured evaluation process to turn complex system choices into defensible Architecture Decision Records (ADRs). It moves beyond "vibes-based" engineering by forcing a comparison of the status quo against feasible alternatives based on your specific constraints.
What it does
- Evaluate trade-offs by analyzing architectural choices like monolith vs. microservices or database selection.
- Generate ADRs following a strict schema including context, constraints, rationale, and consequences.
- Diagram systems using Mermaid syntax to visualize structural changes between components.
- Assess readiness through an evidence-readiness-gate that separates facts from assumptions and unknowns.
- Plan migrations by outlining rollout steps, rollback triggers, and benchmarking plans for performance targets.
How it works
- Reframe the decision as a specific question while listing all known constraints and reversible choices.
- Identify alternatives including the current or "least-change" option to ensure a fair baseline.
- Compare options against criteria like operational burden, security, cost drivers, and team capability.
- Deliver an ADR that documents the rationale, risks, and specific triggers that would require a revisit.
Frameworks & tools
This skill is framework-agnostic but designed for system-level design tasks involving backend scalability, deployment patterns, and data ownership. It integrates with documentation workflows using Mermaid for diagrams and standard ADR formats for repository storage.
Why this beats prompting it yourself
Standard prompts often produce biased recommendations or ignore the "do nothing" option. This skill enforces an evidence-readiness-gate, ensuring technical claims are tied to your specific repository context or official documentation rather than hallucinations.
Use cases
- Deciding whether to extract a specific module into a standalone microservice.
- Selecting a caching strategy or message broker based on team skill and SLOs.
- Documenting the rationale for a major database schema migration.
- Choosing between third-party managed services and self-hosted infrastructure.
Known limitations
Does not replace user-provided requirements or evidence. Recommendation scores require user-provided weights to be objective. Performance benchmarks must be validated via the generated plan.
Requires user-provided weights for scoring. Does not invent benchmark data. Limited to architectural scope, not low-level code implementation.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 2 days ago
- Free with an Agensi account