Architecting Solutions
Turn fuzzy product asks into PRD-style technical solution and architecture documents in docs/ before implementation.
Overview
Architecting Solutions is an agent skill most often used in Validate (also Build pm, Build backend) that designs technical solutions and documents architecture in PRD-style docs/.
Install
npx skills add https://github.com/charon-fan/agent-playbook --skill architecting-solutionsWhat is this skill?
- Four focus areas: clarify requirements, analyze constraints, propose options with trade-offs, document decisions
- Produces PRD-style architecture output under docs/
- Explicit handoff rule: use prd-planner when the user asks for PRD-specific work
- Triggers on phrases like design solution, architecture design, technical design, or 方案设计
- Hooks log session and background self-improvement after architecture completion
- Four documented focus areas from clarify requirements through PRD-style documentation
Adoption & trust: 698 installs on skills.sh; 58 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a feature or system idea but no written architecture, trade-offs, or success criteria for your agent to implement against.
Who is it for?
Solo builders starting billing, multi-tenant analytics, migrations, or new subsystems who need options compared before build.
Skip if: Requests explicitly for PRD-planner-only workflows or trivial one-file changes that do not need architecture docs.
When should I use this skill?
User says design solution, architecture design, technical design, or 方案设计 without asking for PRD-planner-specific PRD work.
What do I get? / Deliverables
You get a docs/ PRD-style solution design with options and a documented decision ready for implementation planning or coding.
- PRD-style architecture document in docs/
- Options analysis with trade-offs and chosen direction
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Validate → scope because architecture design locks requirements and trade-offs before the Build phase starts. Scope subphase is where constraints, options, and success criteria are documented—not ad-hoc coding.
Where it fits
Compare storage and tenancy models before committing to a multi-tenant analytics MVP.
Document extension architecture when adding a billing module to an existing SaaS.
Produce a data migration technical design with constraints pulled from the current codebase.
How it compares
PRD-style architecture skill in-repo, not a cloud IaC generator or generic brainstorming chat.
Common Questions / FAQ
Who is architecting-solutions for?
Indie and solo builders on Claude Code using agent-playbook who need solution and architecture design before implementation.
When should I use architecting-solutions?
Use in Validate → scope for new systems; in Build → pm when extending multi-tenant analytics; in Build → backend for data migration technical design.
Is architecting-solutions safe to install?
Review the Security Audits panel on this page; the skill can Write/Edit docs and run Bash—confirm hooks and repo policies match your comfort.
SKILL.md
READMESKILL.md - Architecting Solutions
# Architecting Solutions > A Claude Code skill for technical solution and architecture design. ## Installation This skill is part of the [agent-playbook](../../README.md) collection. ## Usage ``` You: Design solution for a new billing system You: Provide an architecture design for multi-tenant analytics You: Technical design for a data migration plan ``` ## Focus Areas 1. **Clarify requirements** and success criteria 2. **Analyze constraints** and existing patterns 3. **Propose options** with trade-offs 4. **Document the decision** in a PRD-style output in `docs/` --- name: architecting-solutions description: Designs technical solutions and architecture. Use when user says "design solution", "architecture design", "technical design", or "方案设计" WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead. allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, WebSearch, Grep, Glob metadata: hooks: after_complete: - trigger: self-improving-agent mode: background reason: "Learn from architecture patterns" - trigger: session-logger mode: auto reason: "Log architecture design" --- # Architecting Solutions Analyzes requirements and creates detailed PRD documents for software implementation. ## Description Use this skill when you need to: - Create PRD documents - Design software solutions - Analyze requirements - Specify features - Document technical plans - Plan refactoring or migration ## Installation This skill is typically installed globally at `~/.claude/skills/architecting-solutions/`. ## How It Works The skill guides Claude through a structured workflow: 1. **Clarify requirements** - Ask targeted questions to understand the problem 2. **Analyze context** - Review existing codebase for patterns and constraints 3. **Design solution** - Propose architecture with trade-offs considered 4. **Generate PRD** - Output markdown PRD to `{PROJECT_ROOT}/docs/` directory **IMPORTANT**: Always write PRD to the project's `docs/` folder, never to plan files or hidden locations. ## Workflow Copy this checklist and track progress: ``` Requirements Analysis: - [ ] Step 1: Clarify user intent and success criteria - [ ] Step 2: Identify constraints (tech stack, timeline, resources) - [ ] Step 3: Analyze existing codebase patterns - [ ] Step 4: Research best practices (if needed) - [ ] Step 5: Design solution architecture - [ ] Step 6: Generate PRD document (must be in {PROJECT_ROOT}/docs/) - [ ] Step 7: Validate with user ``` ## Step 1: Clarify Requirements Ask these questions to understand the problem: ### Core Understanding - **Problem Statement**: What problem are we solving? What is the current pain point? - **Success Criteria**: How do we know this is successful? Be specific. - **Target Users**: Who will use this feature? What are their goals? ### For Refactoring/Migration: - **Why Refactor?**: What's wrong with current implementation? Be specific. - **Breaking Changes**: What will break? What needs migration? - **Rollback Plan**: How do we revert if something goes wrong? ## Step 2: Identify Constraints - **Technical Constraints**: Existing tech stack, architecture patterns, dependencies - **Time Constraints**: Any deadlines or phases? - **Resource Constraints**: Team size, expertise availability - **Business Constraints**: Budget, external dependencies, third-party APIs ## Step 3: Analyze Existing Codebase ```bash # Find similar patterns in the codebase grep -r "related_keyword" packages/ --include="*.ts" --include="*.tsx" # Find relevant directory structures find packages/ -type d -name "*keyword*" # Check existing patterns ls -la packages/kit/src/views/similar-feature/ ``` **Critical for Refactoring:** - Find ALL consumers of the code being changed - Identify ALL state/data flows - Trace ALL entry points and exit points - **Look for existing mechanisms that might solve the problem already** ```bash # Find all imports/usages of a module grep