跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

design-architecture

This skill should be used when the user asks to design system architecture, make architectural decisions, or translate PRD into technical design

etr · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add etr/groundwork --skill design-architecture

技能说明


name: design-architecture description: This skill should be used when the user asks to design system architecture, make architectural decisions, or translate PRD into technical design argument-hint: "[feature-name]"

Architecture Design Skill

Interactive workflow for translating product requirements into architecture through iterative decision-making.

File Locations

  • Input: {{specs_dir}}/product_specs.md (PRD with EARS requirements)
  • Output: {{specs_dir}}/architecture.md (architecture document with decisions)

Workflow Overview

  1. Load Context - Read PRD and understand requirements
  2. Identify Decisions - List architectural decisions to make
  3. Iterate Decisions - For each decision: present options → discuss → decide
  4. Document - Write architecture with full decision records

Design Principles

Anchor decisions on the named principles in ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — favor deep modules (simple interface, substantial functionality), minimize the surface Hyrum's Law will freeze into a contract, and design it twice before committing to a module boundary. When a decision passes the decision-record gate (in the principles file), record it using the Decision Record Format (ADR-lite) below. Sharpen the shared vocabulary with [[domain-modeling]].

Pre-flight: Model Recommendation

Your current effort level is {{effort_level}}.

Skip this step silently if effort is high, xhigh, or max (the scale is low < medium < high < xhigh < max, so xhigh and max are already above high) AND you are Opus (1M context). If effort is low or medium (i.e. below high), you MUST show the recommendation prompt — regardless of model. If you are not Opus (1M context), you MUST show the recommendation prompt - regardless of effort level.

Otherwise → use AskUserQuestion:

{
  "questions": [{
    "question": "Do you want to switch? Cross-decision conflict detection and trade-off synthesis across NFRs benefit from deeper reasoning.\n\nTo switch: cancel, run `/model opus[1m]` and `/effort high`, then re-invoke this skill.",
    "header": "Recommended: Opus (1M context) at high effort",
    "options": [
      { "label": "Continue" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}

If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.

Step 0: Resolve Project Context

Before anything else, resolve the project context:

  1. Monorepo check: Does .groundwork.yml exist at the repo root?
    • If yes → Is {{project_name}} non-empty?
      • If empty → Invoke Skill(skill="groundwork:select-project") to select a project, then restart this skill.
      • If set → Project is {{project_name}}, specs at {{specs_dir}}/.
    • If no → Continue to item 3.
  2. CWD mismatch check (monorepo only):
    • Skip if not in monorepo mode or if the project was just selected in item 1 above.
    • If CWD is the repo root → fine, proceed.
    • Check which project's path CWD falls inside (compare against all projects in .groundwork.yml).
    • If CWD is inside the selected project's path → fine, proceed.
    • If CWD is inside a different project's path → warn via AskUserQuestion:

      "You're working from <cwd> (inside [cwd-project]), but the selected Groundwork project is [selected-project] ([selected-project-path]/). What would you like to do?"

      • "Switch to [cwd-project]"
      • "Stay with [selected-project]" If the user switches, invoke Skill(skill="groundwork:select-project").
    • If CWD doesn't match any project → proceed without warning (shared directory).
  3. Check {{specs_dir}}/: Does a specs directory exist?
    • If yes → Single-project repo, proceed normally.
    • If no → Ask the user: "Is this a single-project repo or a monorepo with multiple projects?"
      • Single project → Proceed normally (specs will be created at {{specs_dir}}/)
      • Monorepo → Invoke Skill(skill="groundwork:setup-repo") to create .groundwork.yml, then continue.

Step 1: Load Context

Read the product specs (may be single file or directory) and extract:

  • Non-functional requirements (latency, scale, security, compliance)
  • Feature list and EARS requirements
  • Implicit constraints (budget, team size, timeline if mentioned)

Detection: Check for {{specs_dir}}/product_specs.md first (single file), then {{specs_dir}}/product_specs/ directory. When reading a directory, aggregate all .md files recursively with _index.md first, then numerically-prefixed files, then alphabetically.

If PRD doesn't exist, prompt user to run /groundwork:design-product first.

Summarize key architectural drivers:

"Based on your PRD, the key architectural drivers are:

  • [Driver 1 from NFRs]
  • [Driver 2 from features] I'll need to make decisions about [list 3-5 major areas]. Let's start with [most foundational one]."

Step 2: Identify Decision Areas

Common architectural decision categories:

CategoryExample Decisions
ComputeServerless vs containers vs VMs, orchestration
DataDatabase type, multi-tenancy strategy, caching
APIREST vs GraphQL, gateway pattern, versioning
FrontendSPA vs SSR, framework choice, state management
AuthIdentity provider, token strategy, authorization model
IntegrationSync vs async, message queues, event sourcing
InfrastructureCloud provider, IaC approach, environments
ObservabilityLogging, metrics, tracing, alerting
SecurityEncryption, network isolation, secrets management
CostPricing model alignment, reserved vs on-demand

Prioritize decisions by dependency (foundational first).

Step 3: Research Technologies

Before presenting decision options, gather research on rele

阅读完整来源 ↗