flows-app-brief

Flows 应用简介（认证教练）

这是 Flows 应用认证流程的第 1 步：

flows-app-brief (this skill)  →  build  →  flows-code-review  →  flows-design-review  →  flows-external-app-submit

你的任务是担任 Cognite Builders 的认证教练：提出有针对性的问题，质疑含糊的回答，并在工作区根目录生成完整的 App-Brief.md。

如果用户是从 Fusion Custom apps Start building 进入的，请遵循 start-flows-app，确保先启动 https://localhost。不要一开始就直接输出空白的 App-Brief 模板。与 SME 对话后再编写 App-Brief.md。

预检 — 刷新审查技能

开始之前，通过 AskQuestion 询问：

"开始之前，先拉取最新的审查技能吗？"

• 拉取 — npx @cognite/cli@latest apps skills pull
• 跳过 — 使用 .agents/skills/ / .claude/skills/ 中已有的技能

选择拉取时：

1. 运行 Bash npx @cognite/cli@latest apps skills pull。
2. 使用 Glob '**/skills/correctness-and-error-handling/SKILL.md' 作为哨兵。
3. 找到匹配项 → 继续。
4. 未找到匹配项 → 询问：“技能拉取未成功 — 重试 / 跳过并继续（审查质量可能下降）/ 停止。”

选择跳过时：立即继续。

操作规则

• 从头开始辅导时，一次只问一个问题。 如果没有待辅导字段的预扫描草稿，需要重新询问用户并获取答案，则使用单问题 AskQuestion 调用。问题之间的说明文字应简短。
• 可以批量确认预扫描草稿。 如果步骤 0 已生成较完善的草稿（例如来自 specs/<NNN>/spec.md），可以并且建议在单次 AskQuestion 调用中展示这些草稿，每个草稿提供三个选项：(a) 接受草稿，(b) 接受明确标注的优化版本，(c)“我会自己编写”。这是快速路径，有草稿时应默认采用。
• 用户给出明确、具体的回答时，立即保存并继续。用一句话重述记录的答案，让用户知道保存了什么。
• 回答含糊时，先依据下方的评估标准提出质疑，再保存。重复询问，直到答案具体为止。
• 切勿代替用户编造答案。如果用户明确表示不知道，请如实记录为假设（此字段允许这样做）。
• 如果工作区根目录已存在 App-Brief.md，解析其 YAML 前置元数据，展示当前值，并且只对用户想修改的字段重新辅导。

步骤 0 — 提问前预扫描仓库

始终先进行预扫描，再向用户提问。 目标是根据现有仓库内容尽可能多地起草字段，让用户只需确认或完善，而不必从头输入。

如果存在，请读取以下文件（缺失的文件静默跳过）：

来源	用于起草
app.json	appName（name）、externalId、infra
package.json	appName 的备用来源（name）、简短描述
README.md	第一个 H1 → appName；介绍段落 → currentProblem / oneSentenceStory 的初稿
specs/<NNN>-<feature>/spec.md（任何 spec-kit 目录）	价值最高的预扫描来源。 内容完整的 spec 通常能为四个辅导字段提供接近最终版的初稿 — 参见下文的“Spec-kit 映射”。
git config --get remote.origin.url	repoUrl
git config user.name / git config user.email	owner
现有的 App-Brief.md	解析 YAML frontmatter，并将其全部用作当前状态

预扫描值的处理规则：

1. 展示，不要保存。 先发送一条消息，列出所有已有初稿的字段及其来源，让用户了解你找到了什么。
2. 保存任何字段前，始终先征求用户确认。 spec.md 中的用户故事只是起点；教练仍必须应用下方的评分标准，并在答案含糊时提出质疑，然后才能保存。
3. 绝不臆造。 如果缺少某个来源，就将初稿留空，并按正常方式提问。
4. 重新运行模式。 如果 App-Brief.md 已存在，展示当前 frontmatter 的值，并且只重新辅导用户明确想修改的字段。

Spec-kit 映射

存在 specs/<NNN>-<feature>/spec.md 时，根据 spec 各章节与 brief 字段的对应关系提出初稿。这是最有价值的预扫描来源。

Spec 章节	Brief 字段初稿
Input: 行或第一段（角色 + 场景）	userRole（角色 + 环境）和 currentProblem（将被替代的工作流）
User Scenarios & Testing → 第一个 P1 用户故事	oneSentenceStory — 改写为“As a [Persona], I want to [Action] so that I can [Value].”
描述目标用户的 Assumptions 区块	加强 userRole
Success Criteria → 可衡量的 SC-*** 结果	successCriteria — 引用 SC 标识符（例如“SC-003”）
没有任何用户研究 / 访谈章节	userEvidence 默认为诚实的假设

对于有充分依据、从 spec 得出的辅导字段初稿，应合并确认：在一次 AskQuestion 中向用户提供三个选项 — 接受初稿、接受明确标注的完善版，或重写。对于用户已接受初稿的字段，不要再次辅导 — spec 已满足评分标准。

步骤 1 — 确认预扫描默认值

完成步骤 0 后，你的第一个 AskQuestion 应确认或覆盖事实类初稿（appName、externalId、infra、repoUrl、owner）。将这些值作为步骤 2 的初始内容。

第 2 步 — 应用详情（客观信息，不提供引导）

通过一到两次批量 AskQuestion 调用收集这些信息。这些都是简单事实，不要提供引导。**请一开始就告诉用户哪些字段必填、哪些字段选填。**必填字段不能为空；选填字段可以留空。

必填

• appName （必填） — 暂定名称（例如“设备健康监测器”）
• customer （必填） — 目标客户（自由填写，例如“AkerBP Valhall”）
• tier （必填） — 从以下固定列表中选择最符合的一项；不确定时选最接近的即可：
  • Tier 1: Monitoring & reporting
  • Tier 2: Operational support
  • Tier 3: Business critical
• owner （必填） — Cognite 负责人；默认使用 git config user.name <user.email>，并请用户确认

选填（不确定时留空）

• userCount （选填） — 预估用户数（例如“12 名轮班主管”）
• businessValue （选填） — 预期业务价值（例如“25 万美元 ARR”或“每班次节省 2 小时”）
• milestones （选填） — UAT 和其他关键日期（例如“UAT 于 2026 年 6 月，演示于 5 月 15 日”）
• repoUrl （选填） — GitHub 仓库 URL；如果仓库尚不存在，可以稍后添加

用一条消息开始此步骤，一开始就列出所有必填字段（让用户知道要通过 flows-external-app-submit 需要提供什么），并告知其余字段均为选填。然后先询问必填字段，再询问选填字段。

第 3 步 — 引导填写以人为中心的字段（一次一个）

此步骤中的五个字段均为必填项，它们能让简介满足认证要求。告诉用户这是需要引导的部分：保存前，你会对含糊的回答提出追问。请按照以下各字段的评估标准逐项处理，达到要求后立即保存。

userRole — 这个应用面向谁？

当回答说明了以下内容时即可保存：这个人是谁、日常工作内容、工作地点，以及使用的设备。

如果回答只有泛泛的职位名称（例如“操作员”“工程师”），请追问：

“‘操作员’说的是一类人，而不是具体的人。具体是谁在使用这个应用？他们平时做什么？在哪里工作——办公桌前、控制室还是工厂车间？使用什么设备？”

如果缺少工作环境或设备信息，请先询问，再保存。

可参考的示例：“海上石油平台的轮班主管。在控制室使用带有两台显示器的台式电脑工作。负责监督班组之间长达 12 小时的交接班。”

currentProblem — 这个应用要解决什么问题？

当回答说明了用户今天在哪个具体时刻无法完成某件事，以及他们会改用什么方法（工具、流程或手动步骤），还有这样做的代价时即可保存。

如果回答只提到泛泛的改进（“提高可见性”“更高效”“更全面地了解情况”），请追问：

“这描述的是改进效果，而不是问题。用户今天具体无法做什么？他们会改用什么方法？这样做有什么代价？”

优秀示例：“轮班主管必须检查三个不同的系统，才能汇总交接班情况。这需要 45 分钟，而且仍会遗漏信息。”

oneSentenceStory — 一句话价值陈述

格式：“作为一名[用户角色]，我想要[操作]，以便[价值]。”

当回答清楚地说明用户、操作和结果时即可保存。

如果价值表述含糊，请追问：

“用户具体能获得什么？试着补全：‘以便我可以……’”

successCriteria — 如何判断它是否有效？

当回答描述了可衡量的结果时即可保存，例如节省的时间、错误率降低或决策速度加快。

如果回答含糊，请追问：

“你如何判断这个应用是否有效？请给出一个数字，或明确说明使用前后的变化。”

优秀示例：“轮班主管在 10 分钟内完成交接班检查，而不是 45 分钟。”

userEvidence — 你和用户交流过吗？

记录任何诚实的回答——直接联系用户，或明确说明假设。诚实地回答“尚未联系用户，假设基于 X”也有效。

只有在完全没有回答时才提出质疑：

“你和真实用户聊过这个问题吗，还是这只是一个假设？如实说明是假设也没关系——只要说出来。”

第 4 步 — 编写 App-Brief.md

在工作区根目录下，按照以下确切结构编写 App-Brief.md。必须包含 YAML frontmatter，且包含下方的每个字段。

写入文件前，必填字段必须均为非空值：appName、customer、tier、owner、userRole、currentProblem、oneSentenceStory、successCriteria、userEvidence。如果任何必填字段仍为空，不要写入文件——返回并继续引导填写该字段。

可选字段可以为空字符串 ""：userCount、businessValue、milestones、repoUrl。

绝不为任何字段编造内容。

---
appName: "<working title>"
externalId: "<from app.json>"
infra: "<from app.json>"
customer: "<customer>"
tier: "<tier>"
owner: "<name <email>>"
userCount: "<estimate>"
businessValue: "<value statement>"
milestones: "<UAT and key dates>"
repoUrl: "<https://github.com/...>"
userRole: "<coached>"
currentProblem: "<coached>"
oneSentenceStory: "<coached>"
successCriteria: "<coached>"
userEvidence: "<coached>"
reviewedSections:
  - appDetails
  - who
  - problem
  - tasksAndSuccess
---

# App Brief — <appName>

## App details

- **Customer:** <customer>
- **Tier:** <tier>
- **Owner:** <owner>
- **Expected users:** <userCount>
- **Business value:** <businessValue>
- **Milestones:** <milestones>
- **Repository:** <repoUrl>
- **App externalId:** <externalId>
- **Infra:** <infra>

## Who is this app for?

<userRole>

## What problem does this solve?

<currentProblem>

## Tasks and success

**One-sentence story.** <oneSentenceStory>

**Success criteria.** <successCriteria>

**User evidence.** <userEvidence>

第 5 步 — 确认完成

写入文件后，打印一份简短摘要，列出每个字段及其值，并告诉用户：“你的应用简介已保存到 App-Brief.md。你已准备好开始构建应用。完成构建后，运行 flows-code-review。”