create-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create an App

构建应用

Take a raw app idea to a validated, cleanly architected first version that ships on a sustainable cadence — without over-building for scale you have not earned, or writing a prototype that calcifies into a rewrite. This journey runs ten phases: it asks before every decision and records each choice in

docs/

so you can stop and resume across sessions. The early phases often produce no code at all; once an experiment greenlights building, the engineering phases build the real thing well.

将原始应用想法转化为经过验证、架构清晰且能以可持续节奏发布的首个版本——无需为尚未达成的规模过度开发，也不会写出最终需要重写的原型。该流程分为10个阶段：每个决策前都会提问，并将每个选择记录在

docs/

文件夹中，让你可以随时暂停并跨会话继续流程。早期阶段通常不会产生代码；一旦实验验证可行，工程阶段就会高质量地构建实际产品。

Core Principle

核心原则

Validate fast while keeping options open: make the expensive-to-reverse decisions early and defer everything cheap. Spend scarce early effort on the few things that compound — the riskiest assumption, the dependency boundaries, the domain language — and aggressively avoid waste everywhere else.

This skill sequences the phases, asks the questions, and records the decisions; the constituent skills carry the method. Invoke them rather than improvising their frameworks.

快速验证同时保留选择权：尽早做出难以逆转的昂贵决策，推迟所有低成本决策。 将早期稀缺精力投入到少数能产生复利的事情上——最具风险的假设、依赖边界、领域语言——并在其他方面积极避免浪费。

本技能负责编排阶段、提出问题并记录决策；具体方法由各子技能执行。请调用这些技能，而非自行套用其框架。

Journey Map

流程地图

Phase	Skill	Question it answers	Artifact
1	lean-startup	Is the riskiest assumption true, and what is the MVP?	Creates docs/PRODUCT.md + docs/EXPERIMENTS.md
2	design-sprint	What should the core flow be?	Creates docs/DESIGN.md, extends docs/EXPERIMENTS.md — awaiting-evidence
3	clean-architecture	What boundaries keep options open?	Creates docs/ARCHITECTURE.md
4	domain-driven-design	What does the code mean?	Extends docs/ARCHITECTURE.md
5	clean-code	Is each function readable and tested?	Creates docs/TESTING.md
6	pragmatic-programmer	Which habits keep it healthy?	Extends docs/TESTING.md + docs/TECH-DEBT.md
7	system-design	How big must it really be?	Extends docs/ARCHITECTURE.md
8	ios-hig-design	Does it feel native on iOS?	Extends docs/DESIGN.md — iOS only
9	37signals-way	What ships, and what is cut?	Extends docs/PRODUCT.md + docs/STRATEGY.md
10	software-design-philosophy	Where is complexity hiding?	Extends docs/TECH-DEBT.md + docs/ARCHITECTURE.md

阶段	技能	要解决的问题	产出物
1	lean-startup	最具风险的假设是否成立？MVP是什么？	创建docs/PRODUCT.md + docs/EXPERIMENTS.md
2	design-sprint	核心流程应该是什么样的？	创建docs/DESIGN.md，扩展docs/EXPERIMENTS.md —— 等待验证证据
3	clean-architecture	哪些边界能保留选择权？	创建docs/ARCHITECTURE.md
4	domain-driven-design	代码的业务含义是什么？	扩展docs/ARCHITECTURE.md
5	clean-code	每个函数是否易读且经过测试？	创建docs/TESTING.md
6	pragmatic-programmer	哪些习惯能保持代码健康？	扩展docs/TESTING.md + docs/TECH-DEBT.md
7	system-design	产品实际需要多大规模？	扩展docs/ARCHITECTURE.md
8	ios-hig-design	在iOS上是否有原生体验？	扩展docs/DESIGN.md —— 仅适用于iOS
9	37signals-way	哪些功能要发布，哪些要砍掉？	扩展docs/PRODUCT.md + docs/STRATEGY.md
10	software-design-philosophy	复杂性隐藏在何处？	扩展docs/TECH-DEBT.md + docs/ARCHITECTURE.md

Operating Rules

操作规则

Resume first. Before anything else, read
```
docs/CREATE-APP-PLAN.md
```
and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted.
Intake on first run only. No tracker: run the Intake below, then create
```
docs/CREATE-APP-PLAN.md
```
with every phase statused
```
pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason
```
. Done when the tracker exists and the user has confirmed the phase plan.
Phase entry. Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase
```
in-progress
```
on proceed. Done when the user chose.
Skill invocation and fallback. Load the phase's skill and use it: each phase's Invoke line names the skill by slug — use that skill to run the phase. If it is not available, offer:
```
npx skills add wondelai/skills/<slug> --global
```
. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in.
In-phase decisions. Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect.
Phase exit. Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows
```
done
```
.
Artifact discipline. Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in
```
docs/
```
. Every recommendation lands as a checkbox or a table row with owner and priority. See references/artifact-templates.md when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names.
The agent prepares and processes; only the human talks to customers and test users. Draft sprint scripts and interview guides and score the results, then pause with status
```
awaiting-evidence
```
until the user returns with notes. The ios-hig-design phase applies only when shipping a native iOS app; skip it otherwise at intake.

优先恢复流程。在任何操作前，先读取
```
docs/CREATE-APP-PLAN.md
```
和流程地图中的所有产出物。如果存在追踪文件，用3-5行总结当前流程状态，并询问进入哪个阶段。当用户确认进入点后完成此步骤。已有追踪文件的流程需恢复，而非重启。
仅首次运行时收集信息。若没有追踪文件：执行下方的信息收集步骤，然后创建
```
docs/CREATE-APP-PLAN.md
```
，将每个阶段标记为
```
pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason
```
。当追踪文件创建完成且用户确认阶段计划后完成此步骤。
进入阶段。告知用户：该阶段的作用、需要做出的决策、产出的文件、大致工作量。提供继续/跳过/推迟选项——标记为GATE的阶段可推迟，但不可跳过。选择继续则将阶段标记为
```
in-progress
```
。当用户做出选择后完成此步骤。
调用技能及备选方案。加载该阶段的技能并使用：每个阶段的调用行以slug命名技能——使用该技能运行阶段。若技能不可用，提供方案：
```
npx skills add wondelai/skills/<slug> --global
```
。若用户拒绝，使用该技能的简要说明（最简可行方法）运行阶段，并说明当前使用的模式。
阶段内决策。询问“与用户共同决策”下的所有问题——提供具体选项和你的建议。将选择记录在追踪文件的“关键决策”部分。未明确做出的决策视为缺陷。
退出阶段。在写入前展示产出物草稿内容供用户确认。获得批准后：写入或扩展docs/文件夹中的文件，更新追踪文件（状态、关键决策、下一步行动）。当文件写入完成且阶段状态显示为
```
done
```
后完成此步骤。
产出物规范。先读后写；仅当文件不存在时创建，否则扩展——添加或更新你的部分，保留其他人的内容。docs/文件夹中的文件为大写格式。所有建议需以复选框或带负责人和优先级的表格行呈现。首次创建docs/文件时，请参考references/artifact-templates.md——从完整框架（所有章节标题）创建，然后填充该阶段对应的章节。
Agent负责准备和处理；仅人类与客户及测试用户沟通。起草 sprint 脚本和访谈指南并评分，然后将状态设为
```
awaiting-evidence
```
暂停，直到用户带回反馈记录。ios-hig-design阶段仅适用于发布原生iOS应用的情况；否则在信息收集阶段跳过。

Intake

信息收集

Ask these before creating the tracker:

What is the app idea in one sentence, and what is the riskiest belief behind it? (Gates Phase 1; if the job the app is hired for is fuzzy, add the jobs-to-be-done optional phase.)
Is the underlying idea already validated with behavioral evidence, or still a hunch? (Unvalidated and high-stakes makes Phase 1 mandatory; if paying customers already exist you may be in the wrong journey — improve-app or grow-app.)
What is the stage — weekend prototype, funded build toward launch, or a team forming around it? (A prototype leans on Phases 1-3 and 10; a forming team may add inspired-product.)
Will you ship a native iOS client? (Yes keeps Phase 8; no skips it.)
Do you have customers to talk to, or must you find them? (Gates the human evidence loop in Phases 1-2 and optional mom-test / continuous-discovery.)
What load do you expect in the first months — daily active users and actions per day? (Feeds Phase 7 capacity math and stops premature scaling.)
Solo build or team, and who owns shipping cadence? (Gates Phase 9 shaping.)

Phase-skip heuristics: skip Phase 2 when the core flow is already tested or trivial; skip Phase 8 unless shipping native iOS; skip Phase 7 only when load is obviously tiny — but still record the estimate; for a weekend prototype, run Phases 3-6 as one pass but never skip the Dependency Rule.

Then create

docs/CREATE-APP-PLAN.md

from the template with every phase statused, marking Phase 8 iOS-conditional. Done when

docs/CREATE-APP-PLAN.md

exists with every phase statused and the user has confirmed the plan.

创建追踪文件前需询问以下问题：

用一句话描述应用想法，以及背后最具风险的假设是什么？（决定是否进入阶段1；若应用的核心价值模糊，需添加jobs-to-be-done可选阶段。）
底层想法是否已通过行为证据验证，还是仍为猜测？（未验证且高风险的情况下阶段1为必填；若已有付费客户，你可能选错了流程——应使用improve-app或grow-app。）
项目处于什么阶段——周末原型、融资后准备发布，还是正在组建团队？（原型阶段侧重阶段1-3和10；组建团队的情况可添加inspired-product阶段。）
你是否会发布原生iOS客户端？（是则保留阶段8；否则跳过。）
你是否有可沟通的客户，还是需要寻找客户？（决定阶段1-2及可选的mom-test / continuous-discovery中的人工验证环节。）
最初几个月你预计的负载是多少——日活跃用户数和每日操作数？（为阶段7的容量计算提供数据，避免过早扩容。）
单人开发还是团队开发，谁负责发布节奏？（决定阶段9的内容规划。）

阶段跳过规则：当核心流程已测试或非常简单时，跳过阶段2；除非发布原生iOS应用，否则跳过阶段8；仅当负载明显极小时跳过阶段7——但仍需记录估算值；对于周末原型，将阶段3-6合并执行，但绝不能跳过依赖规则。

然后从模板创建

docs/CREATE-APP-PLAN.md

，标记每个阶段的状态，将阶段8标记为iOS条件触发。当

docs/CREATE-APP-PLAN.md

创建完成且所有阶段状态已标记，用户确认计划后完成此步骤。

Phases

各阶段详情

Phase 1 — Validate the riskiest assumption (lean-startup)

阶段1 — 验证最具风险的假设（lean-startup）

Purpose: Prove the belief that would kill the app if false — before writing production code.

Brief (fallback): Plan Build-Measure-Learn backward: what must you learn, how will you know, what is the smallest build that finds out. Rank leap-of-faith assumptions by what is fatal, not what is easy to test. An MVP is a learning vehicle, often crude (Dropbox validated with a video, not a sync engine). Climb the validation ladder — signups weak, paid deposit strong, active usage strongest; aim for behavioral level 4-5, never "would you use this?" opinion.

Invoke: Use the

lean-startup

skill with the idea and, if CUSTOMER.md exists, the job statement. Ask for ranked leap-of-faith assumptions, the single smallest experiment that falsifies the riskiest, and a pre-committed behavioral success threshold.

Decide with the user: Which assumption is fatal if false? Which experiment type — smoke test (demand), concierge (value), Wizard of Oz (automation)? What go/pivot threshold, fixed before running? Only the user runs it with real people; then pause

awaiting-evidence

Artifact: Create docs/PRODUCT.md with

## Vision

and

## MVP Definition

; create docs/EXPERIMENTS.md with

## Experiment Cards

(EXP-001 with hypothesis, metric, decision rule) and

## Experiment Backlog

. Update the tracker.

Done when: the fatal assumption is named, EXP-001 has a pre-committed threshold, PRODUCT.md states the MVP scope, and the user has the experiment to run.

目标： 在编写生产代码前，证明若不成立就会导致应用失败的核心假设。

备选简要说明： 反向规划Build-Measure-Learn流程：你需要了解什么？如何验证？最小可行的验证方案是什么？按致命程度而非易测试程度对核心假设排序。MVP是学习工具，通常很粗糙（Dropbox用视频而非同步引擎完成验证）。沿着验证阶梯推进——注册是弱验证，付费押金是强验证，活跃使用是最强验证；目标达到行为验证级别4-5，绝不要停留在“你会用这个吗？”的观点层面。

调用： 使用

lean-startup

技能，传入应用想法；若存在CUSTOMER.md，同时传入核心价值声明。要求用户对核心假设排序，选择验证最具风险假设的最小实验，并设定预先约定的行为成功阈值。

与用户共同决策： 哪个假设不成立会导致应用失败？选择哪种实验类型——烟雾测试（需求验证）、礼宾服务（价值验证）、绿野仙踪（自动化验证）？设定什么继续/转型阈值（需在实验前确定）？仅由用户与真实用户执行实验；然后将状态设为

awaiting-evidence

暂停。

产出物： 创建docs/PRODUCT.md，包含

## Vision

和

## MVP Definition

；创建docs/EXPERIMENTS.md，包含

## Experiment Cards

（EXP-001，含假设、指标、决策规则）和

## Experiment Backlog

。更新追踪文件。

完成标志： 已确定致命假设，EXP-001已设定预先约定的阈值，PRODUCT.md明确了MVP范围，用户已拿到要执行的实验方案。

Phase 2 — De-risk the core experience (design-sprint)

阶段2 — 降低核心体验风险（design-sprint）

Purpose: Settle what the core flow should be with a tested facade, before committing engineering time.

Brief (fallback): Five days: Map the problem Monday, Sketch Tuesday, Decide Wednesday, Prototype Thursday, Test with five real users Friday. Output is a high-fidelity facade plus evidence, not code. The riskiest moment is a stranger's first ten minutes — test whether they understand it and finish the core task with no explanation. Five users surface the patterns; you need patterns, not significance. Never explain the prototype; watch where they get stuck.

Invoke: Use the

design-sprint

skill with the MVP scope from PRODUCT.md. Ask for a Monday map and How Might We reframes, a winning concept storyboard, and a five-act interview script with a note-taking grid (checkmark / cross / tilde per participant). Record the approved script under the sprint card in docs/EXPERIMENTS.md when pausing, so it survives the session break.

Decide with the user (on return): Does the tested flow work as-is, need a reshape, or expose a demand problem that loops back to Phase 1? Which confusions become fixes?

Artifact: Create docs/DESIGN.md with

## Design Direction

; extend docs/EXPERIMENTS.md

## Experiment Cards

with the sprint test and its verdict. Update the tracker.

Done when: DESIGN.md records the direction, the sprint result and verdict are in EXPERIMENTS.md, and the user chose proceed / reshape / loop.

目标： 通过经过测试的界面确定核心流程，再投入工程时间。

备选简要说明： 为期5天：周一梳理问题，周二绘制草图，周三做出决策，周四制作原型，周五邀请5名真实用户测试。产出物是高保真界面及验证证据，而非代码。最关键的时刻是陌生人使用的前10分钟——测试他们是否无需解释就能理解并完成核心任务。5名用户就能发现规律；你需要的是规律，而非统计显著性。绝不要解释原型；观察他们在哪里卡住。

调用： 使用

design-sprint

技能，传入PRODUCT.md中的MVP范围。要求用户提供周一的问题梳理图、How Might We重构方案、获胜概念的故事板，以及包含记录网格（每位参与者用对勾/叉号/波浪线标记）的五幕访谈脚本。暂停时将批准的脚本记录在docs/EXPERIMENTS.md的sprint卡片中，确保跨会话保留。

与用户共同决策（实验返回后）： 测试的流程是否可直接使用？是否需要调整？是否暴露出需求问题，需回到阶段1？哪些困惑需要修复？

产出物： 创建docs/DESIGN.md，包含

## Design Direction

；扩展docs/EXPERIMENTS.md的

## Experiment Cards

，添加sprint测试结果及结论。更新追踪文件。

完成标志： DESIGN.md记录了设计方向，EXPERIMENTS.md包含sprint结果及结论，用户已选择继续/调整/返回阶段1。

Phase 3 — Draw the boundaries (clean-architecture)

阶段3 — 划定边界（clean-architecture）

Purpose: Isolate business rules so the database, framework, and providers stay swappable details.

Brief (fallback): Source code dependencies point inward — frameworks toward use cases toward entities. Business rules must not import the framework or ORM. Use cases define interfaces (e.g. InvoiceRepository); infrastructure implements them; controllers translate an HTTP request into a plain request object and receive a plain response — no framework type crosses the boundary. Diagnostic: can you test the business rules with no database, web server, or framework running? Four circles are typical, not sacred — draw boundaries only at points of volatility.

Invoke: Use the

clean-architecture

skill with the validated MVP scope from PRODUCT.md. Ask for the layer map, the core use case with its request/response models, and the repository interfaces it depends on.

Decide with the user: Where are the real volatility boundaries (database, third-party APIs, delivery mechanism)? Full four layers, or collapse adapters and frameworks for a small app?

Artifact: Create docs/ARCHITECTURE.md with

## System Context

and

## Layer Map & Dependency Rule

(layers, what depends on what, a violations table). Update the tracker.

Done when: ARCHITECTURE.md names the layers, the Dependency Rule direction is explicit, and the core business rule is testable with no infrastructure.

目标： 隔离业务规则，使数据库、框架和服务提供商成为可替换的细节。

备选简要说明： 源代码依赖指向内部——框架指向用例，用例指向实体。业务规则不得导入框架或ORM。用例定义接口（如InvoiceRepository）；基础设施实现接口；控制器将HTTP请求转换为普通请求对象，并接收普通响应——框架类型不得跨越边界。验证方法：能否在无数据库、Web服务器或框架运行的情况下测试业务规则？四层结构是常见方案，但并非必须——仅在易变点划定边界。

调用： 使用

clean-architecture

技能，传入PRODUCT.md中已验证的MVP范围。要求用户提供层映射、核心用例及其请求/响应模型，以及用例依赖的仓库接口。

与用户共同决策： 真正的易变边界在哪里（数据库、第三方API、交付机制）？使用完整四层结构，还是为小型应用合并适配器和框架层？

产出物： 创建docs/ARCHITECTURE.md，包含

## System Context

和

## Layer Map & Dependency Rule

（层级、依赖关系、违规表）。更新追踪文件。

完成标志： ARCHITECTURE.md明确了层级，依赖规则方向清晰，核心业务规则无需基础设施即可测试。

Phase 4 — Model the domain (domain-driven-design)

阶段4 — 建模领域（domain-driven-design）

Purpose: Make the code speak the business so a domain expert could read it and spot what is wrong.

Brief (fallback): The model is the code. Build a Ubiquitous Language — name things after domain concepts, not technical roles (an

InvoiceDraft.finalize()

beats a

DataProcessor.process()

); hard-to-name is a design signal. Bounded contexts: a word means one thing inside a boundary ("Customer" in billing need not equal "Customer" in support). Aggregates: a cluster with one root that enforces invariants — keep them small, reference other aggregates by ID. Avoid the anemic model; push behavior into entities and value objects.

Invoke: Use the

domain-driven-design

skill with ARCHITECTURE.md's layer map. Ask for the ubiquitous language, the bounded contexts and context map, and the core aggregate with the invariants its root enforces.

Decide with the user: What is the core domain (your competitive edge) versus generic subdomains (auth, email, payments) to buy or use open source? Where does the same word legitimately mean different things across contexts?

Artifact: Extend docs/ARCHITECTURE.md: add

## Bounded Contexts & Context Map

and

## Domain Glossary (Ubiquitous Language)

(term | meaning | code name). Update the tracker.

Done when: the glossary names the core concepts, contexts and relationships are mapped, and the repository interface sits in the domain layer per Phase 3.

目标： 让代码体现业务逻辑，使领域专家能读懂代码并发现问题。

备选简要说明： 模型即代码。构建通用语言——以领域概念命名，而非技术角色（

InvoiceDraft.finalize()

优于

DataProcessor.process()

）；难以命名是设计信号。限界上下文：同一词汇在边界内只有一种含义（计费中的“Customer”无需与支持中的“Customer”一致）。聚合：包含一个根实体的集群，用于维护不变量——保持聚合小型化，通过ID引用其他聚合。避免贫血模型；将行为推送到实体和值对象中。

调用： 使用

domain-driven-design

技能，传入ARCHITECTURE.md中的层映射。要求用户提供通用语言、限界上下文及上下文映射，以及核心聚合及其根实体维护的不变量。

与用户共同决策： 核心领域（你的竞争优势）是什么？通用子领域（认证、邮件、支付）是购买还是使用开源方案？哪些词汇在不同上下文中有合理的不同含义？

产出物： 扩展docs/ARCHITECTURE.md：添加

## Bounded Contexts & Context Map

和

## Domain Glossary (Ubiquitous Language)

（术语 | 含义 | 代码名称）。更新追踪文件。

完成标志： 术语表明确了核心概念，上下文及关系已映射，仓库接口位于阶段3定义的领域层。

Phase 5 — Write code to be read (clean-code)

阶段5 — 编写易读代码（clean-code）

Purpose: Keep every function readable and tested as the codebase grows.

Brief (fallback): Code is read far more than written. Small functions that do one thing at a single level of abstraction; intention-revealing names; no flag arguments (a smell — the function does two things); commands separate from queries; a well-named extracted function beats a comment. Tests are first-class — dirty tests are worse than none. Write them F.I.R.S.T. (Fast, Independent, Repeatable, Self-validating, Timely) with behavior-based names like shouldRejectNegativeTotal.

Invoke: Use the

clean-code

skill with the core module from Phases 3-4. Ask for a score-and-fix review against the rules and clean unit tests (arrange-act-assert, descriptive names, a builder helper) for the core use case.

Decide with the user: What quality bar gates a commit — function size, name clarity, no swallowed exceptions? Which happy-path and failure cases must the first tests cover?

Artifact: Create docs/TESTING.md with

## Test Strategy

(pyramid, tooling, what green gates) and

## Safety Net Map

(module | pinned behaviors | test files | gaps). Update the tracker.

Done when: TESTING.md states the strategy, the core use case has passing behavior-named tests that need no database, and the commit quality bar is recorded.

目标： 随着代码库增长，保持每个函数易读且经过测试。

备选简要说明： 代码的阅读次数远多于编写次数。函数要小，只做一件事且处于同一抽象层级；名称要能体现意图；避免标志参数（这是一种坏味道——说明函数做了两件事）；命令与查询分离；命名清晰的提取函数优于注释。测试是一等公民——混乱的测试不如没有。编写F.I.R.S.T.（快速、独立、可重复、自验证、及时）测试，使用基于行为的命名，如shouldRejectNegativeTotal。

调用： 使用

clean-code

技能，传入阶段3-4的核心模块。要求用户根据规则进行评分和修复，并为核心用例编写清晰的单元测试（Arrange-Act-Assert结构、描述性名称、构建器助手）。

与用户共同决策： 提交代码的质量标准是什么——函数大小、名称清晰度、无吞异常？首次测试必须覆盖哪些正常路径和异常路径？

产出物： 创建docs/TESTING.md，包含

## Test Strategy

（测试金字塔、工具、通过标准）和

## Safety Net Map

（模块 | 固定行为 | 测试文件 | 缺口）。更新追踪文件。

完成标志： TESTING.md明确了测试策略，核心用例有基于行为命名的通过测试且无需数据库，提交质量标准已记录。

Phase 6 — Install the meta-disciplines (pragmatic-programmer)

阶段6 — 建立元规范（pragmatic-programmer）

Purpose: Adopt the habits that keep the codebase easy to change over years.

Brief (fallback): Fire a tracer bullet — one thin real slice through every layer (UI to use case to database and back), kept, to surface integration bugs on day two. DRY applies to knowledge only, not coincidental similarity. Orthogonality: changing the database must not touch the UI. Reversibility: wrap third-party SDKs behind your own interfaces so Stripe or a model provider swaps without touching business logic. Broken windows: fix the first hack or board it up with a tracked ticket — never leave silent rot.

Invoke: Use the

pragmatic-programmer

skill with ARCHITECTURE.md and the core use case. Ask for the thinnest end-to-end tracer-bullet design and an adapter interface for each third-party dependency.

Decide with the user: What is the tracer-bullet slice? Is the broken-windows policy zero-tolerance with tracked tickets? Which dependencies get adapter interfaces now versus later?

Artifact: Extend docs/TESTING.md (

## CI Gates

) and docs/TECH-DEBT.md (

## Debt Budget & Broken-Windows Policy

and

## Adopted Conventions

). Update the tracker.

Done when: the tracer bullet is specified end-to-end, adapter interfaces are named for each provider, and the broken-windows policy is written down.

目标： 养成能让代码库多年保持易变更的习惯。

备选简要说明： 发射追踪子弹——构建贯穿所有层级（UI到用例到数据库再返回）的完整薄切片并保留，以便在第二天发现集成问题。DRY原则仅适用于知识，而非偶然相似性。正交性：更改数据库不得影响UI。可逆性：将第三方SDK包装在自己的接口后，这样替换Stripe或模型提供商无需修改业务逻辑。破窗理论：修复第一个漏洞，或用追踪工单标记——绝不要留下隐性腐烂。

调用： 使用

pragmatic-programmer

技能，传入ARCHITECTURE.md和核心用例。要求用户提供最薄的端到端追踪子弹设计，以及每个第三方依赖的适配器接口。

与用户共同决策： 追踪子弹的切片是什么？破窗策略是否为零容忍并使用追踪工单？哪些依赖现在需要适配器接口，哪些可以推迟？

产出物： 扩展docs/TESTING.md（

## CI Gates

）和docs/TECH-DEBT.md（

## Debt Budget & Broken-Windows Policy

和

## Adopted Conventions

）。更新追踪文件。

完成标志： 已明确端到端的追踪子弹，为每个提供商命名了适配器接口，破窗策略已书面记录。

Phase 7 — Size it honestly (system-design)

阶段7 — 合理评估规模（system-design）

Purpose: Estimate the real load and prove what you do NOT need to build yet.

Brief (fallback): Start from requirements, not solutions. QPS = daily active users x actions/day / 86,400, peak 2-5x average; storage = records/day x record size x retention. For a few hundred users the math almost always says one well-indexed database plus a cache. Scale in order: vertical first, then read replicas, then cache aside, shard last. Reach for a queue to absorb spikes and decouple slow work (e.g. photo OCR) from the request path only when an estimate or real bottleneck justifies it.

Invoke: Use the

system-design

skill with the load numbers from intake. Ask for a back-of-the-envelope QPS and storage estimate and an explicit list of techniques you do NOT need yet.

Decide with the user: Given the estimate, which scaling do you deliberately defer? Which real bottleneck, if any, justifies a cache or queue now?

Artifact: Extend docs/ARCHITECTURE.md: add

## Data & Storage Decisions

and

## Decision Log

(date | decision | why | alternatives rejected), recording each "not yet" as a decision. Update the tracker.

Done when: the capacity estimate is recorded, the deferred scaling techniques are listed explicitly, and any cache or queue is justified by a number.

目标： 估算实际负载，明确哪些内容无需立即构建。

备选简要说明： 从需求出发，而非解决方案。QPS = 日活跃用户数 × 每日操作数 / 86400，峰值为平均值的2-5倍；存储 = 每日记录数 × 记录大小 × 保留时间。对于数百用户规模，计算结果几乎总是一个索引良好的数据库加缓存。扩容顺序：先垂直扩容，再读副本，然后缓存，最后分片。仅当估算或实际瓶颈证明必要时，才使用队列吸收峰值并将慢任务（如照片OCR）与请求路径解耦。

调用： 使用

system-design

技能，传入信息收集阶段的负载数据。要求用户提供粗略的QPS和存储估算，以及明确的无需立即使用的技术列表。

与用户共同决策： 根据估算，你有意推迟哪些扩容措施？是否有实际瓶颈需要现在添加缓存或队列？

产出物： 扩展docs/ARCHITECTURE.md：添加

## Data & Storage Decisions

和

## Decision Log

（日期 | 决策 | 原因 | 拒绝的备选方案），将每个“暂不实施”记录为决策。更新追踪文件。

完成标志： 已记录容量估算，明确列出推迟的扩容技术，缓存或队列的添加有数据支撑。

Phase 8 — Make it feel native (ios-hig-design) — iOS only

阶段8 — 打造原生体验（ios-hig-design）—— 仅适用于iOS

Purpose: Make an iPhone client feel native — the basis of iOS users' trust. Run only when shipping a native iOS client (decided at intake); skip otherwise.

Brief (fallback): Three pillars — clarity, deference, depth. Respect safe areas (Dynamic Island, home indicator); every touch target at least 44x44 pt; semantic colors (Color(.label), Color(.systemBackground)) so Dark Mode is automatic; semantic text styles for Dynamic Type; native navigation — tab bars for primary destinations, NavigationStack for drill-down, sheets for focused tasks, never a hamburger menu. Accessibility is first-class: a label on every control, and VoiceOver can complete every task.

Invoke: Use the

ios-hig-design

skill with the app's key screens. Ask for a HIG review of safe areas, 44pt targets, semantic colors and type, native navigation, and accessibility labels.

Decide with the user: Which screens are in scope for the first review? Any deliberate platform deviations, and are they justified?

Artifact: Extend docs/DESIGN.md: add

## Components

(component | decision | status) and

## UX Audit Findings

(issue | heuristic | severity 0-4 | fix | status). Update the tracker.

Done when: each in-scope screen is reviewed, findings are logged with severity, and accessibility gaps are captured as fixes.

目标： 让iPhone客户端具有原生体验——这是iOS用户信任的基础。仅在发布原生iOS客户端时运行（信息收集阶段确定）；否则跳过。

备选简要说明： 三大支柱——清晰、遵从、深度。尊重安全区域（灵动岛、主屏幕指示器）；每个触摸目标至少44×44 pt；使用语义颜色（Color(.label)、Color(.systemBackground)）自动适配深色模式；使用语义文本样式适配动态字体；使用原生导航——标签栏用于主目的地，NavigationStack用于深度导航，弹窗用于聚焦任务，绝不要使用汉堡菜单。无障碍是一等公民：每个控件都有标签，VoiceOver可完成所有任务。

调用： 使用

ios-hig-design

技能，传入应用的关键屏幕。要求用户对安全区域、44pt触摸目标、语义颜色和字体、原生导航、无障碍标签进行HIG审查。

与用户共同决策： 首次审查涵盖哪些屏幕？是否有意偏离平台规范，是否有合理理由？

产出物： 扩展docs/DESIGN.md：添加

## Components

（组件 | 决策 | 状态）和

## UX Audit Findings

（问题 | 启发式 | 严重程度0-4 | 修复方案 | 状态）。更新追踪文件。

完成标志： 所有纳入范围的屏幕已审查，问题已记录严重程度，无障碍缺口已作为修复方案捕获。

Phase 9 — Ship on a cadence (37signals-way)

阶段9 — 按节奏发布（37signals-way）

Purpose: Ship a focused v1 on fixed time that fights feature creep.

Brief (fallback): Build half a product, not a half-assed one. Shape work before betting it: rough enough for design freedom, solved enough to remove big unknowns, bounded by an appetite ("this is worth two weeks") — not an estimate. Fix the time and cut scope to fit, never the reverse. Bet shaped pitches into fixed cycles; a circuit breaker kills anything unfinished at the deadline. Opinionated software: every preference offered is a decision refused — pick sensible defaults; the default answer to a feature is a respectful "not now".

Invoke: Use the

37signals-way

skill with the MVP scope from PRODUCT.md. Ask for the next feature shaped into a pitch (problem, appetite, breadboard, rabbit holes, no-gos) and a v1 cut list.

Decide with the user: What is the appetite for the next feature? Which v1 features get cut, and which user-facing preferences become opinionated defaults?

Artifact: Extend docs/PRODUCT.md (

## Outcome Roadmap

) and docs/STRATEGY.md (

## No-List

— what we explicitly will not do). Update the tracker.

Done when: the next feature has a shaped pitch with an appetite, the v1 cut list is in STRATEGY.md's No-List, and the roadmap reflects fixed-time / flexible-scope.

目标： 在固定时间内发布聚焦的v1版本，对抗功能蔓延。

备选简要说明： 构建半个完整产品，而非半吊子产品。在投入资源前先规划工作：足够粗略以保留设计自由度，足够明确以消除重大未知，以“意愿”（“这值得两周时间”）而非估算为边界。固定时间，裁剪范围以适配，绝不要反过来。将规划好的任务投入固定周期；截止日期时未完成的任务直接终止。有主见的软件：每提供一个选项就是拒绝一个决策——选择合理的默认值；对新功能的默认回答是礼貌的“暂不支持”。

调用： 使用

37signals-way

技能，传入PRODUCT.md中的MVP范围。要求用户将下一个功能规划为提案（问题、意愿、草图、潜在陷阱、禁止事项），并提供v1裁剪列表。

与用户共同决策： 下一个功能的时间意愿是什么？哪些v1功能被裁剪，哪些用户偏好被设为有主见的默认值？

产出物： 扩展docs/PRODUCT.md（

## Outcome Roadmap

）和docs/STRATEGY.md（

## No-List

——明确不做的事情）。更新追踪文件。

完成标志： 下一个功能已有带时间意愿的规划提案，v1裁剪列表已记录在STRATEGY.md的No-List中，路线图体现了固定时间/灵活范围。

Phase 10 — Treat complexity as the enemy (software-design-philosophy)

阶段10 — 视复杂性为敌人（software-design-philosophy）

Purpose: Hold complexity down across every module — the lens over all the other phases.

Brief (fallback): Complexity is anything about structure that makes a system hard to understand and change. Prefer deep modules — powerful functionality behind a simple interface — over shallow ones; judge a module by functionality divided by interface complexity, not line count. This corrects Clean Code's "small" and DDD's many concepts tipping into classitis (swarms of one-method shallow classes). Strategic over tactical: invest a steady 10-20% extra on design, because early shortcuts compound exactly as the team and codebase grow.

Invoke: Use the

software-design-philosophy

skill with the modules from Phases 3-6. Ask for a deep-vs-shallow evaluation flagging shallow classes, pass-through methods, and information leaking across boundaries, plus where to consolidate.

Decide with the user: Which shallow modules should merge into deeper ones? Where is tactical shortcutting accruing debt worth the strategic 10-20% now?

Artifact: Extend docs/TECH-DEBT.md (

## Smell Inventory

: smell | location | refactoring | status) and docs/ARCHITECTURE.md (

## Decision Log

). Update the tracker.

Done when: shallow modules and leaks are logged in the Smell Inventory, consolidation decisions are recorded, and the strategic-vs-tactical stance is agreed.

目标： 控制每个模块的复杂性——这是所有其他阶段的指导原则。

备选简要说明： 复杂性是指任何使系统难以理解和变更的结构特性。优先选择深度模块——简单接口背后提供强大功能——而非浅模块；以功能与接口复杂度的比值评判模块，而非行数。这纠正了Clean Code中“小型”和DDD中过多概念导致的类爆炸（大量仅含一个方法的浅类）。战略优于战术：持续投入10-20%的额外精力用于设计，因为早期的捷径会随着团队和代码库的增长而不断放大。

调用： 使用

software-design-philosophy

技能，传入阶段3-6的模块。要求用户进行深度vs浅度评估，标记浅类、透传方法、跨边界信息泄露，以及需要合并的地方。

与用户共同决策： 哪些浅模块应合并为深度模块？哪些战术捷径产生的债务值得现在投入战略层面的10-20%精力修复？

产出物： 扩展docs/TECH-DEBT.md（

## Smell Inventory

: 坏味道 | 位置 | 重构方案 | 状态）和docs/ARCHITECTURE.md（

## Decision Log

）。更新追踪文件。

完成标志： 浅模块和信息泄露已记录在坏味道清单中，合并决策已记录，战略vs战术立场已达成一致。

Optional Phases

可选阶段

Skill	Add when	Artifact
jobs-to-be-done	the job the app is hired for is fuzzy or contested	Creates docs/CUSTOMER.md
mom-test	assumptions need customer conversations, not opinions	Extends docs/CUSTOMER.md
lean-ux	the team wants hypothesis-driven UX instead of heavy specs	Extends docs/EXPERIMENTS.md
ux-heuristics	the first usable build needs a usability pass	Extends docs/DESIGN.md
hooked-ux	the product depends on habitual repeat usage	Extends docs/PRODUCT.md
design-everyday-things	core flows confuse test users	Extends docs/DESIGN.md
continuous-discovery	post-launch, to keep weekly customer contact	Extends docs/CUSTOMER.md
inspired-product	a team forms around the product and needs vision and outcome roadmaps	Extends docs/PRODUCT.md

Optional phases follow the same operating rules — load and use each listed skill exactly as a core phase would; insert where the Add-when condition first becomes true.

技能	添加时机	产出物
jobs-to-be-done	应用的核心价值模糊或存在争议	创建docs/CUSTOMER.md
mom-test	需要通过客户对话而非观点验证假设	扩展docs/CUSTOMER.md
lean-ux	团队希望采用基于假设的UX而非详细规格	扩展docs/EXPERIMENTS.md
ux-heuristics	首个可用版本需要可用性审查	扩展docs/DESIGN.md
hooked-ux	产品依赖用户习惯性重复使用	扩展docs/PRODUCT.md
design-everyday-things	核心流程让测试用户感到困惑	扩展docs/DESIGN.md
continuous-discovery	发布后需保持每周与客户沟通	扩展docs/CUSTOMER.md
inspired-product	围绕产品组建团队，需要愿景和成果路线图	扩展docs/PRODUCT.md

可选阶段遵循相同的操作规则——完全按照核心阶段的方式加载和使用每个列出的技能；在“添加时机”条件首次满足时插入。

Common Mistakes

常见错误

Mistake	Fix
Building the architecture before validating the idea	Run Phase 1 first — validation is cheap, a rewrite is not ( `lean-startup` ).
Treating "MVP" as a license to write garbage	Ship the smallest thing to learn, then build the real thing well once greenlit; minimum is not low quality ( `lean-startup` ).
Letting the framework dictate the architecture	Keep frameworks in the outer ring as plugins; no ORM types cross use-case boundaries ( `clean-architecture` ).
The anemic domain model	Push behavior into entities and value objects, not fat service classes ( `domain-driven-design` ).
Classitis — over-applying "small"	Judge modules by depth (functionality per unit of interface), not line count ( `software-design-philosophy` ).
Premature scaling	Do the estimate; one database plus a cache carries most apps far — shard last ( `system-design` ).

错误	修复方案
在验证想法前先构建架构	先运行阶段1——验证成本低，重写成本高（ `lean-startup` ）。
将“MVP”视为编写糟糕代码的借口	发布最小可行版本以学习，验证通过后再高质量构建实际产品；“最小”不等于低质量（ `lean-startup` ）。
让框架主导架构	将框架放在外层作为插件；ORM类型不得跨越用例边界（ `clean-architecture` ）。
贫血领域模型	将行为推送到实体和值对象中，而非臃肿的服务类（ `domain-driven-design` ）。
类爆炸——过度追求“小型”	以深度（单位接口的功能）而非行数评判模块（ `software-design-philosophy` ）。
过早扩容	进行估算；一个数据库加缓存足以支撑大多数应用——最后再考虑分片（ `system-design` ）。

Completing the Journey

流程完成

Exit checklist:

PRODUCT.md states a validated MVP and vision; EXPERIMENTS.md holds a run experiment with a recorded verdict.
ARCHITECTURE.md passes the Dependency Rule test and names the core domain, contexts, and capacity estimate.
TESTING.md shows the core use case tested with no infrastructure and the tracer bullet running end-to-end.
STRATEGY.md's No-List and a shaped next feature exist if shipping continues.

Close the tracker: every phase

done

skipped: reason

, Key Decisions captured, and Next Actions carried into the artifacts (not left in the tracker). Forward routing:

When the idea underneath the app turns out to be unvalidated, or is really a commercial-model question, continue with the
```
create-business
```
skill.
When the app grows past its first architecture and the structure itself becomes the hard problem, continue with the
```
design-code-architecture
```
skill.

退出检查清单：

PRODUCT.md明确了已验证的MVP和愿景；EXPERIMENTS.md包含已执行的实验及记录的结论。
ARCHITECTURE.md通过依赖规则测试，明确了核心领域、上下文和容量估算。
TESTING.md显示核心用例无需基础设施即可测试，追踪子弹已端到端运行。
若继续发布，STRATEGY.md的No-List和下一个规划好的功能已存在。

关闭追踪文件：每个阶段标记为

done

或

skipped: reason

，关键决策已捕获，下一步行动已纳入产出物（而非留在追踪文件中）。后续指引：

若应用背后的想法未验证，或实际是商业模式问题，继续使用
```
create-business
```
技能。
若应用增长超出初始架构，结构本身成为难题，继续使用
```
design-code-architecture
```
技能。