create-yss-spec 1.0.0

package/template/docs/user-guide/grill-with-docs-best-practices.md

@@ -0,0 +1,275 @@
+# grill-with-docs 最佳实践
+
+本文补充 [grill-with-docs 使用手册](./grill-with-docs-guide.md)，用于约束长期使用 `grill-with-docs` 时的工作习惯、产物边界和常见反模式。
+
+## 1. 核心原则
+
+### 1.1 追问优先于生成
+
+`grill-with-docs` 的目标不是马上写一份漂亮文档，而是把需求里的模糊点问出来。
+
+好的使用方式：
+
+```text
+请先连续追问，不要直接生成 PRD。
+```
+
+不好的使用方式：
+
+```text
+我有个想法，直接帮我生成完整 PRD。
+```
+
+如果 AI 开始替你补全关键业务规则，要把它拉回来：
+
+```text
+这个规则不要猜，请作为待确认问题列出。
+```
+
+### 1.2 术语稳定后立刻沉淀
+
+当一个业务概念已经确定，就写入 `CONTEXT.md`。不要等整轮讨论结束再批量整理，因为批量整理容易把“已确认”和“仍在猜”混在一起。
+
+写入标准：
+
+- 是本项目特有的业务语言。
+- 定义能用一两句话说清。
+- 有同义词或容易误用的词需要规避。
+- 后续 PRD、OpenAPI、代码、测试都会复用。
+
+不写入：
+
+- 通用技术词。
+- 类名、表名、字段名。
+- 临时讨论结论。
+- 尚未确认的猜测。
+
+### 1.3 ADR 要少而准
+
+ADR 不是会议纪要，也不是方案全文。它只记录难以回滚、非显而易见、经过真实取舍的决定。
+
+在 grill 中出现这类问题时才考虑 ADR：
+
+- 将来改掉成本很高。
+- 未来维护者会疑惑为什么这样做。
+- 当时有多个可行选择。
+
+如果只是“常规实现方式”，不要写 ADR。
+
+### 1.4 不要把 grill 当实现计划
+
+`grill-with-docs` 产出的不是开发任务清单。它负责澄清：
+
+- 谁用。
+- 做什么。
+- 为什么做。
+- 不做什么。
+- 业务词怎么定义。
+- 哪些决定需要记录。
+
+实施计划应交给：
+
+- `to-prd`
+- `writing-plans`
+- `Issue`
+- `yss-router`
+
+## 2. 推荐追问维度
+
+### 2.1 用户与角色
+
+必须问清：
+
+- 谁是主要用户。
+- 谁配置，谁审批，谁查看结果。
+- 管理员和普通业务用户的边界。
+- 实施人员是否有特殊操作入口。
+
+示例：
+
+```text
+模型发布是建模人员自己发布，还是需要平台管理员审批？
+```
+
+### 2.2 业务对象和状态
+
+必须问清：
+
+- 核心对象是什么。
+- 对象有哪些状态。
+- 状态能否回退。
+- 状态变化是否产生审计记录。
+
+示例：
+
+```text
+草稿版本发布后，是生成一个新的发布版本，还是直接把草稿状态改为已发布？
+```
+
+### 2.3 边界和非目标
+
+必须问清：
+
+- 第一版做什么。
+- 第一版明确不做什么。
+- 哪些能力只是竞品参考，不进入 MVP。
+- 哪些能力必须人工确认。
+
+示例：
+
+```text
+模型发布第一版是否包含审批流、回滚、血缘影响分析和通知？
+```
+
+### 2.4 异常和失败路径
+
+必须问清：
+
+- 校验失败怎么提示。
+- 并发编辑怎么处理。
+- 下游引用时发布失败怎么办。
+- 权限不足、网络失败、数据不存在如何反馈。
+
+示例：
+
+```text
+如果发布时字段校验失败，用户需要看到字段级错误，还是只看到整体失败原因？
+```
+
+### 2.5 验收和可验证性
+
+必须问清：
+
+- 什么结果算完成。
+- 哪些场景必须自动化测试。
+- 哪些场景必须人工验收。
+- 哪些日志、审计、实施记录需要保留。
+
+示例：
+
+```text
+发布成功后，如何证明下游只能引用发布版本，不能引用草稿版本？
+```
+
+## 3. 与产品全生命周期结合
+
+### 3.1 竞品分析之后
+
+竞品分析给出“行业常见能力”和“差异化机会”，grill 负责把它变成你的产品边界。
+
+推荐输入：
+
+```text
+使用 grill-with-docs，基于 docs/discovery/reports/model-management-competitive-matrix.md，
+追问哪些竞品能力进入 MVP，哪些作为非目标。
+```
+
+输出应能支撑 discovery 和 PRD。
+
+### 3.2 PRD 之前
+
+PRD 之前使用 grill，可以降低“AI 代替产品经理做决定”的风险。
+
+推荐输出：
+
+- 已确认用户故事。
+- 非目标范围。
+- 关键验收标准。
+- OpenAPI 影响初判。
+- 待人工确认问题。
+
+### 3.3 Issue 之前
+
+Issue 需要清晰 change 目标。如果目标还模糊，先 grill。
+
+进入 Issue 拆分前至少确认：
+
+- change 名称表达一个目标。
+- 主要行为和非目标清楚。
+- API 影响明确。
+- 是否触碰安全红线。
+- 是否存在需要 ADR 的取舍。
+
+### 3.4 YSS 实现之前
+
+进入 `yss-router` 前，grill 应该已经解决业务问题，不应再把业务规则留给专项实现技能猜。
+
+进入实现前至少确认：
+
+- 页面或接口服务的业务目的。
+- 领域对象和状态。
+- 验收标准。
+- OpenAPI 影响。
+- 前后端职责边界。
+
+## 4. 输出格式建议
+
+每轮 grill 结束时，建议要求 AI 输出：
+
+```markdown
+## 本轮结论
+
+### 已确认
+- ...
+
+### 待确认
+- ...
+
+### 非目标
+- ...
+
+### 术语沉淀
+- `CONTEXT.md`: ...
+
+### ADR 建议
+- 无 / 建议新增 `docs/adr/000N-xxx.md`
+
+### 下一步
+- ...
+```
+
+如果存在待确认问题，不要直接进入实现。
+
+## 5. 常见反模式
+
+| 反模式 | 风险 | 改法 |
+|---|---|---|
+| AI 一次问十个问题 | 用户难回答，容易敷衍 | 一次聚焦一个主题，必要时一个关键问题一轮 |
+| AI 替业务做决定 | 关键规则来自猜测 | 标为待确认 |
+| 术语都写进 CONTEXT.md | 词汇表膨胀失真 | 只写稳定业务语言 |
+| ADR 写成大方案 | 后续没人读 | 只记录决定和原因 |
+| grill 之后直接开发 | PRD / OpenAPI / change 丢失 | 先进入 PRD 或 Issue |
+| 只问正常路径 | 异常场景上线后暴露 | 必问失败、并发、权限、回滚 |
+| 把实现细节写入 glossary | 领域语言污染 | 实现细节放 PRD、设计或 ADR |
+
+## 6. 检查清单
+
+### 开始 grill 前
+
+- [ ] 已说明业务背景。
+- [ ] 已提供已有材料路径。
+- [ ] 已说明希望澄清的主题。
+- [ ] 已授权是否可以更新 `CONTEXT.md`。
+- [ ] 已说明是否需要 ADR 建议。
+
+### grill 过程中
+
+- [ ] 不确定的问题标记为待确认。
+- [ ] 稳定术语及时写入 `CONTEXT.md`。
+- [ ] 冲突术语被指出并解决。
+- [ ] 正常路径、异常路径、权限和边界都被问到。
+- [ ] 重大取舍按 ADR 三条件判断。
+
+### grill 结束后
+
+- [ ] 已确认范围和非目标。
+- [ ] 已列出待确认问题。
+- [ ] `CONTEXT.md` 没有实现细节。
+- [ ] ADR 只记录必要决定。
+- [ ] 已明确下一步是 discovery、PRD、OpenAPI、Issue 还是实现路由。
+
+## 7. 一句话原则
+
+```text
+grill-with-docs 的成果不是“问了很多问题”，而是让后续 PRD、规格和代码不再靠猜。
+```

package/template/docs/user-guide/grill-with-docs-guide.md

@@ -0,0 +1,229 @@
+# grill-with-docs 使用手册
+
+本文面向使用本模板的产品、全栈开发、设计和实施人员。`grill-with-docs` 是一个需求和设计阶段的强访谈入口：它通过连续追问把模糊想法压实，同时用 `domain-modeling` 把稳定术语写入 `CONTEXT.md`，把少数关键取舍沉淀为 ADR。
+
+一句话：
+
+```text
+grill-with-docs = 追问清楚 + 同步沉淀领域语言和关键决策
+```
+
+## 1. 它解决什么问题
+
+没有 grill 时，需求经常会这样失真：
+
+- “模型发布”到底是按钮、流程、版本冻结，还是对外生效机制，没有说清。
+- “管理员”“实施人员”“建模人员”混用，权限边界不清。
+- AI 直接写 PRD，但关键边界来自猜测。
+- 重要取舍只留在聊天里，后续实现和复盘找不到依据。
+
+`grill-with-docs` 的价值是先把这些问题问透，再进入 PRD、OpenAPI、Issue 或开发。
+
+## 2. 什么时候使用
+
+适合使用：
+
+| 场景 | 典型信号 | 下一步产物 |
+|---|---|---|
+| 新产品 / 新模块 | “我要新建工程”“做数据中台模型管理” | discovery、PRD、`CONTEXT.md` |
+| 模糊需求 | “支持模型发布”“加个审批” | 明确范围、非目标、验收标准 |
+| 领域术语混乱 | 同一个概念有多个叫法 | 更新 `CONTEXT.md` |
+| 关键取舍出现 | 版本能否回滚、发布是否可撤销 | 必要时写 ADR |
+| 进入 PRD 前 | 已有想法但边界不稳 | `to-prd` 输入 |
+| 进入 Issue 前 | change 目标还不够清晰 | proposal / design 输入 |
+
+不适合使用：
+
+- 只是 typo、文案或局部样式调整。
+- 已有清晰 PRD、OpenAPI 和任务，只需要执行。
+- Bug 已经可复现，应先用 `systematic-debugging`。
+- 单纯整理已有会议纪要，不需要追问或改变领域模型。
+
+## 3. 输入和输出
+
+### 3.1 输入
+
+最少给出：
+
+- 业务想法或问题。
+- 当前用户角色。
+- 你认为的成功结果。
+- 已有材料路径，例如 discovery、PRD、竞品分析、OpenAPI、现有页面。
+
+更好的输入：
+
+```text
+使用 grill-with-docs，帮我澄清“模型发布与版本冻结”。
+背景：数据中台模型管理中，建模人员可以编辑草稿模型，发布后供下游引用。
+我不确定：发布后是否允许回滚、字段是否还能改、失败如何提示。
+请边追问边沉淀 CONTEXT.md 和必要 ADR。
+```
+
+### 3.2 输出
+
+一次好的 grill 会输出：
+
+- 被澄清的问题列表。
+- 已确认的用户、场景、范围和非目标。
+- 稳定术语更新到 `CONTEXT.md`。
+- 确有必要时，新增或建议 ADR。
+- 下一步建议：继续 discovery、生成 PRD、更新 OpenAPI、创建 Issue change，或进入实现路由。
+
+## 4. 推荐流程
+
+```text
+已有想法 / 竞品分析 / discovery 草稿
+-> grill-with-docs
+-> 更新 CONTEXT.md
+-> 必要时新增 ADR
+-> to-prd 或 PRD 文档
+-> API 影响分析 / 契约草案
+-> review-only OpenAPI Draft（如需要）
+-> 工程基线 / 系统 / 数据架构设计
+-> 设计审查
+-> OpenAPI Freeze
+-> writing-plans / yss-router / YSS skills
+```
+
+### Step 1: 说明问题
+
+```text
+使用 grill-with-docs，帮我澄清“<feature>”。
+请重点追问用户角色、业务闭环、范围、非目标、异常场景、验收标准和术语。
+```
+
+### Step 2: 逐轮回答
+
+grill 的重点是“被问住”。遇到不确定的问题，不要让 AI 替你决定，可以明确说：
+
+```text
+这个点暂不确定，请记录为待确认，不要写入 CONTEXT.md。
+```
+
+或者：
+
+```text
+这个术语已经确定，请更新到 CONTEXT.md。
+```
+
+### Step 3: 收敛为资产
+
+当问题被问清楚后，让 AI 输出收敛结果：
+
+```text
+请总结本轮 grill 结果：
+1. 已确认范围
+2. 非目标范围
+3. 已更新术语
+4. 需要人工确认的问题
+5. 下一步建议进入 PRD、OpenAPI 还是 Issue
+```
+
+## 5. 与 CONTEXT.md 的关系
+
+`CONTEXT.md` 只记录稳定业务语言，不记录实现细节。
+
+应该写入：
+
+- 业务对象：模型、字段、草稿版本、发布版本。
+- 状态含义：冻结、发布、撤销、失效。
+- 角色和责任：建模人员、实施顾问、平台管理员。
+- 避免用语：同义词、容易混淆的叫法。
+
+不应该写入：
+
+- Java 类名、Vue 组件名、表名、接口路径。
+- 临时计划。
+- 未确认猜测。
+- 具体实现方案。
+
+示例：
+
+```text
+模型发布：
+将草稿版本冻结为可被下游引用的发布版本。
+_Avoid_: 上线、提交、保存
+```
+
+## 6. 与 ADR 的关系
+
+不是每个讨论结论都要写 ADR。只有同时满足三点时才写：
+
+1. 难以回滚。
+2. 没有上下文时会让未来读者困惑。
+3. 经过真实取舍。
+
+适合写 ADR：
+
+- 发布版本是否永久不可变。
+- 模型版本是否允许回滚。
+- 模型发布采用审批流还是直接发布。
+- 多租户模型隔离策略。
+
+不适合写 ADR：
+
+- 页面按钮放左边还是右边。
+- 常规 CRUD 字段。
+- 临时实验结论。
+
+## 7. 与其它技能的关系
+
+| 阶段 | 先用 | 后接 |
+|---|---|---|
+| 机会探索后澄清 | `grill-with-docs` | discovery / PRD |
+| PRD 前 | `grill-with-docs` | `to-prd` |
+| Issue 拆分前 | `grill-with-docs` | `to-issues` |
+| 正式变更技术设计前 | `grill-with-docs` 只在需求边界仍不清时使用 | `issue` / `需求澄清` |
+| 实现前 | `grill-with-docs` 只在需求不清时使用 | `writing-plans` / `yss-router` |
+| Bug | 通常不用 | `systematic-debugging` |
+
+推荐组合：
+
+```text
+yss-product-lifecycle
+-> grill-with-docs
+-> to-prd
+-> OpenAPI
+-> Issue
+->  Matt skills / YSS skills
+```
+
+## 8. 常用提示词
+
+```text
+使用 grill-with-docs，帮我澄清“数据中台模型管理”的 MVP 边界。
+请边追问边判断哪些术语可以写入 CONTEXT.md。
+```
+
+```text
+使用 grill-with-docs，围绕“模型发布与版本冻结”做需求拷问。
+重点追问发布后可变性、回滚、权限、失败提示、下游引用影响。
+```
+
+```text
+使用 grill-with-docs，检查这份 PRD 还有哪些边界没问清。
+如果发现稳定术语，更新 CONTEXT.md；如果出现重大取舍，建议是否需要 ADR。
+```
+
+```text
+使用 grill-with-docs，帮我把这个功能进入 Issue 拆分前的问题问完。
+输出：已确认范围、未确认问题、术语变更、ADR 建议、下一步 prompt。
+```
+
+## 9. 最小闭环
+
+如果只记一条：
+
+```text
+先让 AI 追问到你说清楚，再让 AI 写 PRD 或代码。
+```
+
+对应资产：
+
+```text
+CONTEXT.md
+docs/adr/
+docs/discovery/
+docs/requirements/
+docs/requirements/issues/
+```