npm - create-yss-spec - Versions diffs - 2.2.7 → 2.2.8 - Mend

create-yss-spec 2.2.7 → 2.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (130) hide show

package/template/docs/user-guide//351/234/200/346/261/202/346/276/204/346/270/205/346/214/207/345/215/227.md DELETED Viewed

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

package/template/docs/user-guide//351/234/200/346/261/202/346/276/204/346/270/205/346/234/200/344/275/263/345/256/236/350/267/265.md DELETED Viewed

@@ -1,275 +0,0 @@
-# grill-with-docs 最佳实践
-本文补充 [grill-with-docs 使用手册](./需求澄清指南.md)，用于约束长期使用 `grill-with-docs` 时的工作习惯、产物边界和常见反模式。
-## 1. 核心原则
-### 1.1 追问优先于生成
-`grill-with-docs` 的目标不是马上写一份漂亮文档，而是把需求里的模糊点问出来。
-好的使用方式：
-```text
-请先连续追问，不要直接生成 Spec。
-```
-不好的使用方式：
-```text
-我有个想法，直接帮我生成完整 Spec。
-```
-如果 AI 开始替你补全关键业务规则，要把它拉回来：
-```text
-这个规则不要猜，请作为待确认问题列出。
-```
-### 1.2 术语稳定后立刻沉淀
-当一个业务概念已经确定，就写入 `CONTEXT.md`。不要等整轮讨论结束再批量整理，因为批量整理容易把“已确认”和“仍在猜”混在一起。
-写入标准：
-- 是本项目特有的业务语言。
-- 定义能用一两句话说清。
-- 有同义词或容易误用的词需要规避。
-- 后续 Spec、OpenAPI、代码、测试都会复用。
-不写入：
-- 通用技术词。
-- 类名、表名、字段名。
-- 临时讨论结论。
-- 尚未确认的猜测。
-### 1.3 ADR 要少而准
-ADR 不是会议纪要，也不是方案全文。它只记录难以回滚、非显而易见、经过真实取舍的决定。
-在 grill 中出现这类问题时才考虑 ADR：
-- 将来改掉成本很高。
-- 未来维护者会疑惑为什么这样做。
-- 当时有多个可行选择。
-如果只是“常规实现方式”，不要写 ADR。
-### 1.4 不要把 grill 当实现计划
-`grill-with-docs` 产出的不是开发任务清单。它负责澄清：
-- 谁用。
-- 做什么。
-- 为什么做。
-- 不做什么。
-- 业务词怎么定义。
-- 哪些决定需要记录。
-实施计划应交给：
-- `to-spec`
-- `writing-plans`
-- `Ticket`
-- `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/.scratch/model-management/discovery/reports/model-management-competitive-matrix.md`，
-追问哪些竞品能力进入 MVP，哪些作为非目标。
-```
-输出应能支撑 discovery 和 Spec。
-### 3.2 Spec 之前
-Spec 之前使用 grill，可以降低“AI 代替产品经理做决定”的风险。
-推荐输出：
-- 已确认用户故事。
-- 非目标范围。
-- 关键验收标准。
-- OpenAPI 影响初判。
-- 待人工确认问题。
-### 3.3 Ticket 之前
-Ticket 需要清晰 change 目标。如果目标还模糊，先 grill。
-进入 Ticket 拆分前至少确认：
-- 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 | 词汇表膨胀失真 | 只写已确认的业务术语，并带 PascalCase `英文标识` |
-| ADR 写成大方案 | 后续没人读 | 只记录决定和原因 |
-| grill 之后直接开发 | Spec / OpenAPI / change 丢失 | 先进入 Spec 或 Ticket |
-| 只问正常路径 | 异常场景上线后暴露 | 必问失败、并发、权限、回滚 |
-| 把实现细节写入 glossary | 领域语言污染 | 实现细节放 Spec、设计或 ADR |
-## 6. 检查清单
-### 开始 grill 前
-- [ ] 已说明业务背景。
-- [ ] 已提供已有材料路径。
-- [ ] 已说明希望澄清的主题。
-- [ ] 已授权是否可以更新 `CONTEXT.md`。
-- [ ] 已说明是否需要 ADR 建议。
-### grill 过程中
-- [ ] 不确定的问题标记为待确认。
-- [ ] 稳定业务术语及时写入 `CONTEXT.md`，并填写 PascalCase `英文标识`。
-- [ ] 冲突术语被指出并解决。
-- [ ] 正常路径、异常路径、权限和边界都被问到。
-- [ ] 重大取舍按 ADR 三条件判断。
-### grill 结束后
-- [ ] 已确认范围和非目标。
-- [ ] 已列出待确认问题。
-- [ ] `CONTEXT.md` 没有类全名、表名或接口路径；业务术语有英文标识词干。
-- [ ] ADR 只记录必要决定。
-- [ ] 已明确下一步是 discovery、Spec、OpenAPI、Ticket 还是实现路由。
-## 7. 一句话原则
-```text
-grill-with-docs 的成果不是“问了很多问题”，而是让后续 Spec、规格和代码不再靠猜。
-```