build-an-app

构建一个 App

引导用户从头到尾构建一个数字健康 App。此技能负责编排本仓库中的规划技能和构建技能——它会弄清用户需要什么，运行合适的规划技能，并交接给实现阶段。（发布工具 keep-a-changelog-generator 和 release-notes-generator 用于项目生命周期的后期，不属于此流程。）

何时使用

当用户想要执行以下操作时，使用此技能：

• 从零开始构建一个新的数字健康 App
• 弄清从一个健康 App 想法该从哪里开始
• 从想法到可运行代码，并在每一步都获得指导

如果用户想直接运行某个特定技能（例如，他们要求设计 FHIR 数据模型），请勿使用此技能。让他们单独使用该技能。

工作方式

你是一位对话式引导者。保持轻量——不要一开始就抛出一堆问题。倾听用户所说，能推断的就推断，只询问你无法确定的内容。以他们的节奏推进。

---

第 1 步：倾听

首先，看一眼工作目录。如果 docs/planning/ 或 docs/implementation-plan.md 已存在，说明这是恢复——跳过开放性问题，确认已存在的内容，然后直接进入第 2 步中的“从他们上次停下的地方继续”。

否则，从一个开放性问题开始：

“你想构建什么？”

让用户自然地描述他们的想法。他们可能只给一句话，也可能给出三段话——都可以。

从他们的回答中，寻找以下信号：

信号	它告诉你什么
提到某种特定疾病、病症或临床工作流	涉及健康数据，可能还涉及 FHIR
提到研究、试验或受试者招募	需要研究规划
提到患者数据、PHI、HIPAA 或监管方面的顾虑	需要合规规划
提到 HealthKit、生命体征、可穿戴设备或传感器数据	需要健康数据建模
提到 EHR、Epic、SMART on FHIR 或互操作性	需要 FHIR 数据模型设计
提到患者导入自己的病历、患者门户、MyChart 或 Fasten	需要 EHR 记录集成（fasten-ehr-integration）
提到他们已有仓库或项目	跳过平台选择
提到 Spezi 模板之外的框架（Flutter、Kotlin、Web 等），或表示不想要起始模板	跳过平台选择——他们会用自己的框架构建（见第 4 步）
提到他们已有设计稿或线框图	UX 规划可能可以更轻量或跳过
说“我不知道从哪里开始”，或描述了一个模糊的想法	需求发现会有帮助

如果你无法判断该 App 是否涉及健康数据、是否连接临床系统，或是否属于某项研究，请提出一个能覆盖这些缺口的追问。例如：

“这个 App 会收集或存储任何健康数据吗？它是否与某项研究相关？”

不要提出超过一个追问。如果仍有不明确之处，就把相关技能纳入你提议的计划中——用户可以将其移除。

---

第 2 步：提出计划

根据你听到的内容，从可用技能中组装一份计划。每个技能都是有条件的——只纳入用户情况所需的技能。

技能选择指南

技能	包含条件
biodesign-needs-finding	用户不确定问题所在、只有模糊想法，或请求帮助界定范围
spezi-platform-selection	用户尚无项目仓库且希望从 Spezi 模板开始 — 最后运行，用于选择 React Native 或 Apple 原生、搭建匹配的模板项目，并将规划简报移入其中。偏好其他框架的用户可跳过；第 4 步会改为搭建其项目
digital-health-ux-planning	用户尚无设计稿或线框图
health-data-model-planning	App 存储或处理健康数据（生命体征、评估、患者记录）
fhir-data-model-design	App 需要 FHIR 互操作性或连接 EHR
digital-health-compliance-planning	App 处理 PHI 或存在监管方面的顾虑
fasten-ehr-integration	App 需要患者通过 Fasten Connect 拉取自己的 EHR 记录
digital-health-study-planning	App 属于包含入组和评估的研究项目
app-build-planner	始终包含 — 生成驱动构建的实施计划
project-wiki	用户希望拥有随项目一同成长的持久知识库 — 规划结束时（第 4 步）也会提供，即使此处未选择

以简短编号列表的形式呈现该计划，每项技能用一行说明其作用。如果计划包含 spezi-platform-selection，请说明模板是可选的 — 用户可以用任何想要的框架进行构建；若他们不愿使用 Spezi 模板，可去掉该步骤（第 4 步会改为搭建其项目）。然后询问：

“这样看起来对吗，还是说你想增加或删除某些内容？”

在继续之前，让用户进行调整。

从上次中断处继续

如果用户已有项目，请检查 docs/planning/ 中已有的规划文档。跳过任何输出已存在的技能。如果他们已有 docs/implementation-plan.md，直接跳到第 4 步（开始构建）。

---

第 3 步：运行每项技能

按以下顺序依次处理所选技能。对每一项：

1. 告诉用户该技能的作用及其将产出什么（一句话）
2. 阅读该技能的 SKILL.md 并遵循其说明
3. 完成后，验证输出已保存到正确路径
4. 在继续之前，简要总结已产出的内容

全程适用两条约定。输出路径相对于当前工作目录 — 在第 4 步（或 spezi-platform-selection）建立项目之前，当前工作目录就代表各技能提到的“项目仓库”。并且，当某项技能提出的问题用户已在流程早些时候回答过，请沿用那些答案，而不要重复询问。

执行顺序与输出路径

所有规划技能均在 spezi-platform-selection 之前运行，因此在计划尚未确定之前，用户不必绑定到某个平台。

按以下顺序运行技能（跳过任何未被选中的技能）：

技能	输出路径	产出内容
biodesign-needs-finding	docs/planning/need-statement.md	需求陈述：问题、人群、结果
digital-health-ux-planning	docs/planning/ux-brief.md	用户旅程、引导流程、工作流
digital-health-study-planning	docs/planning/study-brief.md	研究方案、入组、评估
health-data-model-planning	docs/planning/data-model-brief.md	实体、关系、FHIR 建议
fhir-data-model-design	docs/planning/fhir-data-model.md	FHIR 资源、术语、关系
digital-health-compliance-planning	docs/planning/compliance-brief.md	隐私域、控制措施、所需决策
fasten-ehr-integration	docs/planning/ehr-connection-brief.md	可用的 Fasten Connect 集成 + 隐私/架构决策
app-build-planner	docs/implementation-plan.md	基于里程碑的构建顺序
spezi-platform-selection	模板项目	基于所选模板的可运行项目目录；规划简报已移入其中

spezi-platform-selection 最后运行（当用户准备好构建时）。它使用规划简报推荐平台，搭建匹配的 Spezi 模板项目（对于 React Native 使用官方命令行生成应用，对于 Apple 原生则进行克隆），并将现有的 docs/planning/ 和 docs/implementation-plan.md 移入其中，以便编码 Agent 拥有完整上下文。

如果用户未使用 Spezi 模板，则没有克隆步骤——规划简报和实施计划与框架无关，步骤 4 会改用用户选择的框架来搭建项目。

fasten-ehr-integration 兼具规划与实现两部分——其完整交付物是一个可运行且经过测试的集成。当应用尚不存在时，此时应运行它，以完成开发者账户设置以及产生 docs/planning/ehr-connection-brief.md 的隐私/架构决策，并让 app-build-planner 将可运行的集成安排为一个里程碑；在该里程碑期间返回此技能，以在实际项目中构建并验证该集成。

在每个技能之间，询问：“准备好继续了吗，还是想调整什么？”

---

步骤 4：开始构建

仅当所有选中的技能均已完成之后，才运行此步骤。特别是，如果选择了 spezi-platform-selection，它必须在构建开始之前运行——实现发生在模板项目内，而不是在规划目录中。

设置项目（无模板路径）

如果用户没有使用 Spezi 模板，请在开始构建之前确定代码将存放的位置：

• 已有仓库 — 直接在其中构建。如果规划文档是在其他目录中生成的，请将 docs/planning/ 和 docs/implementation-plan.md 移入该仓库（移动前先确认；如果 docs/planning/ 已存在则合并）。
• 尚无仓库 — 询问项目应存放的位置（规划目录的同级目录，以应用命名，是不错的默认选择），并使用用户所选框架的标准工具链搭建脚手架（例如 npx create-expo-app、flutter create、npm create vite@latest、空白 Xcode 项目），然后将 docs/planning/ 和 docs/implementation-plan.md 移入其中。如果工具链尚未安装，请先帮助用户安装，或退而使用最小化的手动脚手架并说明情况。在需要时，将应用名称规范化为框架的包命名规则（带空格的显示名称可以保留其目录名，而包名使用 snake_case）。阅读脚手架的 README 和任何 Agent 指令文件，使实现遵循其约定；如果工具链未初始化 git 仓库，请初始化，并在开始构建前安装依赖。

如果发生了移动，请清理规划目录中残留的空 docs/ 目录。如果计划的 Platform 字段仍显示 “To be decided” —— 用户在规划后选择不使用模板 —— 请现在就收窄计划：将 Platform 设为所选框架，将双 Spezi 包注释替换为自定义实现工作量标记，并在 Open Questions 中解决平台条目。无论哪种情况，实现都在该项目目录内进行，而非空的规划目录。没有模板，用户就放弃了预置的 Spezi 脚手架（引导/同意流程、HealthKit 集成、FHIR 映射），因此预计计划的里程碑将涉及更多自定义实现 —— 当规划时平台已知，计划本身会标记这一点；当平台未知时，则通过上述收窄步骤标记。在每条路径中，都鼓励用户在开始构建前将 docs/planning/ 和 docs/implementation-plan.md 提交到项目中 —— 编码 Agent 和未来的贡献者会不断回头查阅它们。

总结并交接

如果 project-wiki 尚未设置（没有 wiki/ 目录）且用户此前未拒绝，请在总结前提出一次：

“你是否想设置一个项目 wiki，以便在构建过程中持续积累知识？它从你的规划文档中播种，并随着你添加访谈、论文和临床观察而成长。”

如果用户接受，请运行 project-wiki 技能（阅读其 SKILL.md 并遵循其说明），然后返回此处。

然后总结项目状态 —— 仅列出磁盘上实际存在的文档，无论是本次会话创建的还是从更早的会话中找到的：

Here's what we have:

Project: [the template project path, the user's existing repo, or the newly scaffolded project]

Planning documents:
  [list only the docs that were created]

Implementation plan:
  docs/implementation-plan.md
  [N] milestones, next up: [first milestone not yet built]

Ready to start building?

当用户准备好构建时，阅读 docs/implementation-plan.md，找到第一个尚未构建的里程碑（恢复时，与用户确认哪些里程碑已完成），并开始实现它。

---

护栏

• 除 app-build-planner 外，每个技能都是可选的。 根据用户描述的内容来选择技能，而不是按固定的清单。
• 模板是可选的。 Spezi 模板是快捷路径，而非硬性要求。如果用户想要使用其他框架（Flutter、Kotlin、Web 或其他任何框架），请跳过 spezi-platform-selection，并在步骤 4 中设置他们的项目——规划简报和实施计划可在任何代码库中使用。
• 不要预先加载问题。 从“你想构建什么？”开始，最多询问一个后续问题。
• 如有疑问，就把它纳入计划。 如果你不确定是否需要某项技能，先提出来，让用户来决定是否移除。删掉一个步骤比发现漏掉一个步骤更容易。
• 尊重用户的节奏。 让用户在每个技能完成后进行审阅和调整。未经确认，不要自动推进。
• 处理“跳到编码”的情况。 如果规划文档已经存在，请确认它们，并从上次中断的地方继续。
• 每个技能都是交互式的。 当你阅读技能的 SKILL.md 并遵循其说明时，用户应当参与——回答问题、审阅输出、提供输入。不要替他们模拟答案。