architecture decision helper

    1

    Evaluate architectural trade-offs and generate structured ADRs with evidence-based rationale.

    Free

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    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.

    OptionBenefitsCostsRisks
    A: Status Quo (Monolith)Zero infra overhead, utilizes existing team skills.Deployment coupling remains.Scaling limits of the monolith.
    B: Celery Job QueueDecouples execution, stays in Python, simple ops.Requires Redis/RabbitMQ.Worker management overhead.
    C: Go MicroserviceHigh 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

    1. Review the Redis infrastructure requirements for the Celery backend.
    2. Define the retry logic and failure modes for the new worker queue.
    3. Update the README.md with 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

    1. Reframe the decision as a specific question while listing all known constraints and reversible choices.
    2. Identify alternatives including the current or "least-change" option to ensure a fair baseline.
    3. Compare options against criteria like operational burden, security, cost drivers, and team capability.
    4. 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.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Agents & Orchestration.

    Requires user-provided weights for scoring. Does not invent benchmark data. Limited to architectural scope, not low-level code implementation.

    How to use

    1. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    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 to use

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 2 days ago

    • Free with an Agensi account

    Permissions

    Write Files
    Listed2 days ago

    What's inside

    Frequently Asked Questions

    The skill uses an 'evidence-readiness-gate' to distinguish between verified facts and assumptions, forcing a comparison against a 'least-change' baseline to prevent the common bias toward new technologies.

    You receive a production-ready agent skill that generates structured ADRs (Architecture Decision Records) and Mermaid.js diagrams, compatible with most major AI agent platforms and orchestration frameworks.

    This skill is framework-agnostic and designed for system-level design tasks, making it ideal for backend scalability, database selection, and microservices orchestration regardless of your specific stack.

    Simply import the skill into your preferred AI agent environment and provide your current system constraints; no complex configuration or external API keys are required to start generating ADRs.

    While it provides the structure and logic for evaluations, it cannot invent your specific business requirements or performance data; you must provide the weights and evidence for the final recommendation to be valid.

    New in Agents & Orchestration

    Free