arch-design

分类: 数据与AI | 上传者: heliohq | 下载: 0 | 版本: v1.0（最新）

系统架构和设计思维——需求分析、组件设计、数据建模、扩展策略和权衡分析。在以下情况下使用：“设计这个系统”、“架构的用途是什么”、“X 的权衡”、“我们应该如何架构”、“系统设计”、“API 设计”、“数据模型”、“服务边界”、“架构文档”、“创建 ADR”。当设计思维完成后，这项技能就会交给 /ship:write-docs 来编写设计文档。注意：这不适用于视觉设计（使用/ship：视觉设计）或实施规划（使用/ship：设计）。 --- # 架构设计在将系统设计决策写下来之前，请仔细思考。这项技能是关于**思考**——需求、组件、权衡、边界。当设计准备就绪时，您必须调用`Skill("write-docs")`来编写设计文档——不要内联编写文档。 ## 扩展至复杂性并非每个决策都需要全部 5 个阶段。将深度与决策相匹配： - **小**（单一组件，明确的约束） - 第 1 阶段简要，第 2 阶段，第 5 阶段。跳过深入研究和扩展。 - **中**（多组件，一些未知）- 所有 5 个阶段，但保持每个阶段简洁。 - **大型**（新系统、重大未知因素、跨团队）——全部 5 个阶段的全面深入，带有图表和明确的负载估计。 ## 危险信号 **从不：** - 跳过需求收集并直接跳到解决方案 - 在不了解现有约束（技术堆栈、团队、时间表）的情况下进行设计 - 省略权衡分析 - 每个决策都有因某种原因被拒绝的替代方案 - 跳过边界部分 - 这是核心的防漂移机制 - 提出设计而不验证实际代码库的假设 - 将“我们想要的”与“存在的”混为一谈 - 明确差距 ## 第 1 阶段：需求收集在设计任何东西之前，请先了解您要解决的问题。 ### 功能要求 - 系统必须做什么？列出具体能力。 - 输入/输出有哪些

更新日志: Source: GitHub https://github.com/heliohq/ship

目录结构

当前层级: tree/main/skills/arch-design/

📄 SKILL.md 6.8 KB

SKILL.md

---
name: arch-design
description: >
  System architecture and design thinking — requirements analysis, component design,
  data modeling, scaling strategy, and trade-off analysis. Use when: "design this system",
  "what's the architecture for", "trade-offs for X", "how should we architect",
  "system design for", "API design", "data model for", "service boundaries",
  "architecture doc", "create an ADR". When the design thinking is done, this skill
  hands off to /ship:write-docs to write the design document. Note: this is NOT for
  visual design (use /ship:visual-design) or implementation planning (use /ship:design).
---

# Architectural Design

Think through system design decisions rigorously before writing them down. This skill is about the **thinking** — requirements, components, trade-offs, boundaries. When the design is ready, you MUST invoke `Skill("write-docs")` to write the design document — do not write the doc inline.

## Scale to Complexity

Not every decision needs all 5 phases. Match the depth to the decision:

- **Small** (single component, clear constraints) — Phase 1 briefly, Phase 2, Phase 5. Skip deep dive and scaling.
- **Medium** (multi-component, some unknowns) — All 5 phases, but keep each concise.
- **Large** (new system, significant unknowns, cross-team) — All 5 phases in full depth, with diagrams and explicit load estimates.

## Red Flag

**Never:**
- Skip requirements gathering and jump straight to a solution
- Design without understanding existing constraints (tech stack, team, timeline)
- Omit trade-off analysis — every decision has alternatives that were rejected for a reason
- Skip the Boundaries section — it's the core anti-drift mechanism
- Propose a design without verifying assumptions against the actual codebase
- Conflate "what we want" with "what exists" — be explicit about the gap

## Phase 1: Requirements Gathering

Before designing anything, understand what you're solving.

### Functional Requirements
- What must the system do? List concrete capabilities.
- What are the input/output contracts?
- What user-facing behaviors are required?

### Non-Functional Requirements
- **Latency**: What response times are acceptable? (p50, p99)
- **Throughput**: How many requests/events per second?
- **Availability**: What uptime target? (99.9%? 99.99%?)
- **Consistency**: Strong consistency required, or eventual is acceptable?
- **Data volume**: How much data now? Growth rate?

### Constraints
- Existing tech stack and infrastructure
- Team size and expertise
- Timeline and budget
- Compliance and regulatory requirements
- Backward compatibility requirements

## Phase 2: High-Level Design

Map out the major components and how they interact.

- **Component diagram**: Major services/modules and their responsibilities. Each component should have a single clear purpose. Use ASCII art, mermaid, or a described diagram — the format matters less than clarity.
- **Data flow**: How data moves through the system — request paths, event flows, data pipelines. A sequence diagram helps for complex flows.
- **API contracts**: Key interfaces between components. Define input/output shapes, not implementation.
- **Storage choices**: Which database(s), why. Access patterns determine storage choice, not the other way around.

## Phase 3: Deep Dive

Go deep on the components that matter most.

- **Data model**: Entities, relationships, indexes. Think about access patterns — how will this data be queried?
- **API design**: REST vs GraphQL vs gRPC. Endpoint structure, authentication, rate limiting, versioning strategy.
- **Caching strategy**: What to cache, invalidation approach, TTL. Cache only what's read-heavy and tolerant of staleness.
- **Async and queues**: What needs to be asynchronous? Retry policies, dead-letter queues, idempotency.
- **Error handling**: Failure modes for each component. Fallback strategies, circuit breakers, graceful degradation.

## Phase 4: Scale and Reliability

Design for the load you'll actually face, not hypothetical scale.

- **Load estimation**: Back-of-envelope calculations for storage, bandwidth, compute. Ground these in real numbers.
- **Scaling strategy**: Horizontal vs vertical. Sharding strategy if needed. Read replicas.
- **Failover**: What happens when each component fails? Single points of failure?
- **Monitoring**: Key metrics to track, alerting thresholds, dashboards. What does "healthy" look like?

## Phase 5: Trade-off Analysis

Every design decision has trade-offs. Make them explicit.

For each major decision:
- **What alternatives were considered** (at least 2)
- **Pros and cons of each** (concrete, not vague)
- **Why this choice won** (the deciding factor)
- **What we're giving up** (be honest about costs)

Common trade-off dimensions:
- Consistency vs availability
- Simplicity vs flexibility
- Build vs buy
- Latency vs throughput
- Cost vs performance
- Team familiarity vs best tool for the job

## What to Revisit

Before wrapping up, flag decisions that won't age well:

- **Load-dependent**: "This works at 1k rps but needs rethinking at 10k" — name the threshold.
- **Time-bound**: "We chose X because Y isn't ready yet" — note when to re-evaluate.
- **Assumption-sensitive**: "If we go multi-region, the consistency model breaks" — link to the assumption.

These aren't weaknesses — they're honest engineering. A design that claims to handle everything forever is hiding its assumptions.

## Design Document Output

When the design thinking is complete, the result should be written as a design document. Every design doc needs:

- **Boundaries section** (required) — what this design does NOT cover, what must not change without updating this doc. This is the core anti-drift mechanism.
- **Trade-offs section** (recommended) — the alternatives considered and why this choice won.
- **Assumptions section** (recommended) — what must be true for this design to hold (e.g., "assumes < 10k concurrent users", "assumes single-region deployment"). When assumptions change, the design is stale.

When the design thinking is complete, invoke `Skill("write-docs")` to write the design document with category `design`. Do not write the doc inline — the write-docs skill enforces frontmatter, numbering, and index generation.

## Execution Handoff

After writing the doc via write-docs, output the report card (read `skills/shared/report-card.md` for the standard format):

```
## [Arch Design] Report Card

| Field | Value |
|-------|-------|
| Status | <DONE / BLOCKED> |
| Summary | <one-line: what was designed and the key decision> |

### Metrics
| Metric | Value |
|--------|-------|
| Phases completed | <N>/5 |
| Trade-offs analyzed | <N> |
| Revisit items | <N> |

### Next Steps
1. **Write the doc (required)** — /ship:write-docs with category design
2. **Full pipeline** — /ship:auto to implement the design
3. **Plan implementation** — /ship:design to create executable stories
```

登录后下载/点赞/收藏 ❤ 9 | ★ 0

arch-design

目录结构

SKILL.md

举报内容

提示