create-yss-spec 2.2.7 → 2.2.9

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -0,0 +1,1014 @@
+# YSS 用户手册
+
+第一次使用 YSS，不需要先读完所有规则。
+
+先用 CLI 准备项目，再完成一次只读检查。等你知道当前在哪一步、还缺什么，再按本手册继续。
+
+## 这本手册适合谁
+
+- 第一次打开 YSS 项目，不知道从哪里开始。
+- 听说过 Spec、Ticket，但不清楚它们有什么用。
+- 需求只有一两句话，不知道应该先问什么。
+- 团队准备开发，需要确认前端、后端和测试怎样配合。
+- 想新建、接管或更新 YSS 项目。
+
+## 看完能做什么
+
+- 用 CLI 创建、接管或更新项目。
+- 在项目准备好后，完成一次不会修改文件的检查。
+- 看懂 Agent 给出的当前阶段、阻塞原因和下一步。
+- 把模糊需求整理成能写 Spec 的内容。
+- 知道什么时候可以开发，什么时候必须先停下。
+- 用同一套方法处理新功能、小改动和 Bug。
+- 正确使用 `create-yss-spec` 创建、接管或更新项目。
+
+## 先找到你要做的事
+
+| 你的情况 | 直接看这里 | 你会得到什么 |
+|---|---|---|
+| 还没有 YSS 项目 | [先用 CLI 准备项目](#先用-cli-准备项目) | 创建项目的最短命令和成功结果 |
+| 第一次使用 | [三分钟开始](#三分钟开始) | 一段可以直接复制的只读检查提示词 |
+| 需求还很模糊 | [需求没说清楚时怎么问](#需求没说清楚时怎么问) | 固定的追问顺序和记录格式 |
+| 想看完整过程 | [用“模型发布”走一遍完整流程](#用模型发布走一遍完整流程) | 从需求到发布的虚构示例 |
+| 团队准备开发 | [团队怎么配合](#团队怎么配合) | 新功能、小改动、Bug 的处理方法 |
+| 新建或接管项目 | [创建、接管和更新项目](#创建接管和更新项目) | `create-yss-spec` 的实际命令 |
+| 遇到专业词 | [新手术语卡](#新手术语卡) | 常用状态和正式名称的普通话解释 |
+
+## 先用 CLI 准备项目
+
+还没有项目时，先运行 CLI。后面的生命周期检查都在生成好的项目目录中执行。
+
+### 第一步：确认本机可以运行 Node.js 和 npm
+
+```bash
+node --version
+npm --version
+```
+
+两个命令都能输出版本号，才能继续。
+
+如果提示找不到命令，请先安装符合项目要求的 Node.js。
+
+### 第二步：创建项目
+
+在准备存放项目的父目录中运行：
+
+```bash
+npm create yss-spec@latest
+```
+
+按提示填写项目名称、业务领域和目标目录。
+
+需要一次写明参数时，可以运行：
+
+```bash
+npx create-yss-spec@latest \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --target-dir "./project" \
+  --git-init
+```
+
+### 第三步：确认初始化成功
+
+进入新项目目录，检查下面几项：
+
+- 根目录存在 `yss-project.yaml`。
+- `repository_mode` 为 `project-instance`。
+- 根目录存在 `CONTEXT.md`、`AGENTS.md` 和 `docs/`。
+- `.yss-template.json` 已记录模板版本信息。
+
+如果这些文件缺失，请先处理 CLI 报错，不要继续做生命周期分诊。
+
+### 已经有项目怎么办
+
+| 当前情况 | 先做什么 | 详细说明 |
+|---|---|---|
+| 现有项目还没有 YSS 模板 | 使用 `attach --dry-run` 预览，再确认写入 | [接管已有项目](#接管已有项目) |
+| 已经存在 `.yss-template.json` | 使用 `sync --dry-run` 预览，再同步 | [更新模板](#更新模板) |
+
+不要在已有 `.yss-template.json` 的项目中重复运行 `attach`。
+
+## 开始前准备
+
+CLI 初始化、接管或同步成功后，再准备：
+
+1. 进入项目根目录。
+2. 确认 `yss-project.yaml` 和 `CONTEXT.md` 可以打开。
+3. 确认 `yss-project.yaml` 中的 `repository_mode` 为 `project-instance`。
+4. 准备当前功能已有的文档、Ticket 或代码位置。
+
+第四项暂时没有也可以开始。先让 Agent 告诉你缺什么。
+
+> 本手册使用“模型发布”作为虚构示例。不要因为教程把它写入任何项目的 `CONTEXT.md`。只有真实项目确实存在这个业务概念，并由业务方确认中文名称、含义和 PascalCase 英文标识后，才能登记。
+
+## 三分钟开始
+
+### 第一步：确认仓库身份
+
+打开根目录的 `yss-project.yaml`。
+
+| 看到的内容 | 表示什么 | 你要做什么 |
+|---|---|---|
+| `repository_mode: project-instance` | 这是实际产品项目 | 可以继续检查功能 |
+| `repository_mode: template-source` | 这是模板源 | 只维护模板，不创建真实产品的 Spec、原型或 Ticket |
+| 文件缺失或值不合法 | 仓库身份不清楚 | 先停止，让 Agent 做迁移检查 |
+
+### 第二步：让 Agent 只做检查
+
+在 `project-instance` 中，把下面这段话发给 Agent：
+
+```text
+使用 yss-product-lifecycle，以 route 模式检查“模型发布”功能。
+请先读取 yss-project.yaml、CONTEXT.md 和当前已有资料。
+本轮只读，不要修改文件。
+请用普通话告诉我：
+1. 现在走到哪一步；
+2. 哪些资料还能继续使用；
+3. 还缺什么；
+4. 下一步只做哪一件事。
+正式 ID 放在普通话解释后面。
+```
+
+`route` 的意思是“只检查，不写文件”。第一次使用时优先选它。
+
+### 第三步：检查回答
+
+一份能用的回答至少要说明：
+
+- 当前处于哪一步。
+- 功能会影响页面、接口、后端、数据还是多个仓库。
+- 哪些资料存在、缺失或已经过期。
+- 有没有功能父 Ticket 和垂直切片 Ticket。
+- 当前小任务是否已经具备开发条件（`ready-for-agent`）。
+- 下一步具体做什么。
+- 为什么现在要暂停或可以继续。
+
+如果回答只说“可以开始开发”，却没有依据，请让 Agent 重新检查。
+
+### 三分钟检查成功后，你应该知道
+
+- 当前仓库是不是 `project-instance`。
+- 当前功能走到了哪一步。
+- 哪些问题还没有答案。
+- 下一步只需要完成什么。
+
+只要这四项说不清，就不要直接让 Agent 写代码。
+
+## 四种使用模式
+
+| 模式 | 普通话解释 | 什么时候用 | 会不会写文件 |
+|---|---|---|---|
+| `route` | 看现状和下一步 | 第一次检查、范围变化后 | 不会 |
+| `orchestrate` | 按当前范围继续推进 | 已经确认可以补文档或执行工作 | 会，但只能在约定范围内 |
+| `resume` | 中断后重新核对再继续 | 会签完成、补充资料或更换 Agent 后 | 会，但先检查状态 |
+| `audit` | 独立检查有没有漏项 | 审查阶段或怀疑状态不对时 | 不会 |
+
+需要继续推进时，可以发送：
+
+```text
+继续使用 yss-product-lifecycle，以 orchestrate 模式推进“模型发布”。
+只处理当前功能范围。
+遇到需要确认、发现新影响、资料过期或需要额外授权时停下。
+每完成一步，请告诉我改了什么、证据在哪里、下一步是什么。
+```
+
+## 可选：使用个人 Codex Plugin
+
+本节介绍的是个人、本机的可选工具，不属于 YSS 模板交付物。它不会自动安装到其他成员的环境，也不会改变项目的事实源、生命周期阶段或门禁。
+
+### 适合谁
+
+当前示例插件 `yss-backend-harness` 只服务后端工程角色。产品、项目、前端和测试角色应使用各自职责对应的工具或 Plugin，不要把后端插件当成全团队通用插件。
+
+### 安装和触发
+
+在已经安装 Codex、并且本机存在 `personal` marketplace 的环境中执行：
+
+```bash
+codex plugin add yss-backend-harness@personal
+```
+
+安装后刷新或重启 Codex，再在已登记的实现仓库中调用。例如：
+
+```text
+请读取当前 YSS 任务包和 Slice Contract，按 role.backend-engineer 生成或执行后端任务。
+```
+
+插件只能在以下条件满足后执行具体实现：
+
+- 仓库是 `project-instance`，不是 `template-source`；
+- 实现仓库、项目根目录、分支和验证命令已经登记；
+- OpenAPI 已 Freeze，或已记录无 API 影响；
+- Slice Contract 已批准并处于 `ready-for-agent`；
+- 任务包明确了允许写入的路径、行为和测试 seam。
+
+### 插件不会替代什么
+
+Plugin 是运行时适配器，不是新的事实源。它不会替代 `yss-product-lifecycle`、`yss-router` 或 `tdd`，不会设置 `ready-for-agent`，不会 Freeze OpenAPI，也不能承担独立审查。
+
+执行结果应包含 `Workflow Execution Result`（例如 `completed`、`blocked`、`needs-human` 或 `failed`）及对应证据。发现路径越界、合同过期、影响面变化或证据缺失时，应停止并回到路由流程。
+
+### 不可用时怎么办
+
+如果插件未安装、版本不兼容或执行失败，回退到通用的 `yss-router + tdd` 流程，并记录阻塞原因和实际验证命令。不要为了绕过插件故障而跳过生命周期门禁。
+
+### 其他应用的接入建议
+
+应用接入按项目需要逐步增加，不作为模板默认依赖：
+
+1. GitHub 或 GitLab：代码、分支、MR/PR 和 CI。
+2. Jira 或 Linear：父 Ticket、Slice Ticket、状态和责任人。
+3. GitHub Actions、GitLab CI 或 Jenkins：自动执行模板、前端和后端验证。
+4. Confluence、Notion 或飞书文档：团队说明和知识库，但不得替代仓库事实源。
+5. Figma：仅在产品设计和 UI 实现阶段接入。
+6. Slack、Teams 或企业微信：仅发送阻塞、审查和发布通知，不承载正式决策。
+7. Sentry、Grafana 或 Datadog：仅在具体产品实例上线后接入运行监控。
+
+推荐顺序是：本地 Git + Codex/Plugin → Git 平台 → Issue tracker → CI/CD → 知识库 → 设计、通知和监控。
+
+## 一张表看懂完整路线
+
+| 你要解决的问题 | 正式阶段 | 完成后应该看到什么 |
+|---|---|---|
+| 先弄清仓库和现状 | 入口分诊 `stage.entry-triage` | 仓库身份、影响范围、最近可信阶段 |
+| 把想法问清楚 | Discovery `stage.discovery` | 用户、目标、范围、非目标、成功标准 |
+| 写成可以确认的说明 | Spec / 功能架构 `stage.spec-architecture` | Spec、总体设计、功能架构 |
+| 把页面和状态想清楚 | 产品设计 `stage.product-design` | 页面流、状态矩阵、原型和确认记录 |
+| 定好接口、数据和工程约定 | 系统 / 数据架构与工程契约 `stage.system-data-engineering` | OpenAPI、数据设计、工程准备信息和审查记录 |
+| 拆成可以单独完成的小任务 | Ticket 正式化 `stage.ticket-formalization` | 功能父 Ticket、垂直切片和实现合同 |
+| 按合同实现和测试 | 垂直切片实现 `stage.vertical-slice-implementation` | 代码、测试和实际命令结果 |
+| 独立检查并发布 | 验证 / 发布 / 复盘 `stage.verification-release-retrospective` | 审查、当次验证、发布和回滚记录 |
+
+主阶段不能删除。
+
+某项检查确实与当前功能无关时，记录“不适用”（`not-applicable`）和原因。不要为了凑齐目录创建空文档。
+
+## 用“模型发布”走一遍完整流程
+
+下面只是教学示例。
+
+假设建模人员现在只能保存草稿。团队希望增加发布功能，让下游系统读取稳定版本。
+
+一开始，发布后能不能修改、要不要审批、失败后能不能重试，都没有答案。因此不能直接写代码。
+
+### 第一步：只读分诊
+
+先用前面的 `route` 提示词检查仓库和已有资料。
+
+这个示例可能影响 UI、API、Backend 和 Data。如果前后端位于不同仓库，还会有 Cross-repo 影响。
+
+成功时你会看到：
+
+- 仓库身份合法。
+- 当前阶段和最近可信阶段已经说明。
+- Agent 没有修改文件。
+- 下一步指向需求澄清，而不是直接实现。
+
+正式信息：
+
+- 阶段：`stage.entry-triage`
+- 工作单元：`work-unit.entry-triage`
+- 检查点：`gate.repository-identity-valid`
+
+### 第二步：把需求问清楚
+
+先确认用户和目标：
+
+- 用户：建模人员。
+- 目标：把检查通过的草稿变成下游可以读取的稳定版本。
+- 成功：页面显示发布成功，下游读取到新版本。
+
+再确认边界：
+
+| 问题 | 示例答案 |
+|---|---|
+| 发布后能否直接修改 | 不能，修改要产生新草稿 |
+| 是否需要审批 | 本次 MVP 不做审批 |
+| 发布失败怎么办 | 保留草稿，允许重试 |
+| 下游读取哪个版本 | 只读取最后一个发布成功的版本 |
+| 本次不做什么 | 不做定时发布，不做批量发布 |
+
+示例答案不能替代真实业务决定。
+
+成功时，已确认、待确认、非目标和外部事实已经分开记录。不确定的问题没有被 Agent 擅自决定。
+
+正式信息：
+
+- 阶段：`stage.discovery`
+- 工作单元：`work-unit.discovery-opportunity`、`work-unit.discovery-requirements`、`work-unit.domain-strategy-design`、`work-unit.stage-decision`
+
+### 第三步：写 Spec
+
+Spec 可以先理解为“功能说明书”。它至少写清：
+
+1. 为什么要做。
+2. 谁可以操作。
+3. 操作前必须满足什么条件。
+4. 成功、失败和重试时发生什么。
+5. 本次明确不做什么。
+6. 用户和测试从哪里看到结果。
+
+Spec 初稿通常使用 `ready-for-human`。这表示还要确认，不表示可以开发。
+
+成功时，用户问题、范围、主流程、异常流程和验收标准都可以被复述，Spec 基线已经完成需要的会签。
+
+正式信息：
+
+- 阶段：`stage.spec-architecture`
+- 工作单元：`work-unit.spec-synthesis`
+- 检查点：`gate.spec-baseline-approved`
+
+### 第四步：把页面和状态画清楚
+
+如果功能会改变页面、导航、操作流程、权限体验或状态展示，需要补产品设计。
+
+“模型发布”至少要考虑：
+
+- 发布按钮什么时候可用。
+- 发布中、成功和失败怎么显示。
+- 没有权限时怎么提示。
+- 失败后能不能重试。
+- 窄屏下是否还能完成操作。
+
+成功时，交互说明、状态矩阵、低保真和高保真原型相互一致，并有评审、浏览器验证和用户确认记录。
+
+正式信息：
+
+- 阶段：`stage.product-design`
+- 工作单元：`work-unit.prototype-design`
+- 检查点：`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation`
+
+### 第五步：定接口、数据和工程约定
+
+有 API 影响时，先写 OpenAPI 3.1 Draft。
+
+Draft 只是草案。评审通过后才能 Freeze。Freeze 可以理解为“接口版本已经确认，前后端按同一份约定实现”。
+
+还要回答：
+
+- 草稿版本和发布版本怎样区分。
+- 什么状态允许发布。
+- 重复请求怎样处理。
+- 失败是否留下中间状态。
+- 下游怎样保证只拿到成功版本。
+
+同时登记实现仓库、项目根、分支、CI、前端 `pnpm` 命令、后端 `./mvnw` 命令、发布顺序和回滚点。
+
+没有 API 影响时，留下明确记录，不要创建空 OpenAPI 文件。
+
+正式信息：
+
+- 阶段：`stage.system-data-engineering`
+- 工作单元：`work-unit.technical-analysis`
+- 常见检查点：`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed`
+
+### 第六步：拆成可以实现的 Ticket
+
+先创建功能父 Ticket，用来汇总整个功能。
+
+再按用户能看到的结果拆垂直切片：
+
+| 切片 | 用户能看到的结果 | 主要验证 |
+|---|---|---|
+| 提交发布 | 建模人员提交请求并看到明确状态 | API 契约测试、页面状态测试 |
+| 读取发布版本 | 下游只读取最后一个成功版本 | 后端行为测试、数据验证 |
+| 失败后重试 | 失败不破坏草稿，用户可以重试 | 失败路径和幂等测试 |
+
+不要只拆成“写 Controller”“写页面”“建表”。这种任务不能单独证明用户结果。
+
+切片进入 `ready-for-agent` 前必须确认：
+
+- 需要的检查点已经批准或明确不适用。
+- 当前 Slice Implementation Contract 已批准并保存。
+- 阻塞关系已经关闭。
+- 实现仓库和验证命令已经登记。
+- 有 UI 影响时，前端实现还原计划已经通过检查。
+
+正式信息：
+
+- 阶段：`stage.ticket-formalization`
+- 工作单元：`work-unit.ticket-decomposition`
+- 检查点：`gate.slice-contract-approved`、`gate.slice-ready-for-agent`
+
+### 第七步：按合同实现
+
+每次只实现一个 `ready-for-agent` 切片。
+
+前端：
+
+- 让 `yss-router` 选择当前页面需要的专项 skill。
+- 以 `yss-ui`、`yss-page-module-development` 和 `tdd` 为主。
+- 只修改合同允许的路径。
+- 实际运行已登记的 `pnpm` 命令。
+
+后端：
+
+- 按影响选择 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller` 和 `yss-dto`。
+- 先写失败测试，再实现最小代码。
+- 只修改合同允许的路径。
+- 实际运行项目根目录的 `./mvnw`。
+
+Agent 应返回合同版本、修改文件、实际命令、退出码和证据位置。
+
+发现资料过期、新影响或违反合同时，Agent 必须停下并重新分诊。
+
+### 第八步：独立审查、发布和复盘
+
+1. 审查前固定一个不再变化的候选快照。
+2. 由非实现者使用 `code-review` 审查。
+3. 对同一候选重新运行测试、构建和关键流程检查。
+4. 准备发布步骤、监控、回滚方法和负责人。
+5. 由生物人决定 `gate.release-ready`。
+6. 出现返工或重要问题时记录复盘。
+
+审查可能给出：
+
+- `violation`：实现违反当前合同，修复后重新检查。
+- `drift`：资料和实现不一致，回到路由重新判断。
+- `new_impacts`：出现新的 UI、API、数据或风险影响，回到路由补分析。
+
+成功时，同一候选已经通过独立审查和当次验证，发布和回滚证据可以读取。
+
+## 需求没说清楚时怎么问
+
+当一句需求可以有多种理解时，先问清楚，再写 Spec、接口或代码。
+
+### 先用普通话说明问题
+
+不推荐：
+
+```text
+做一个模型发布功能。
+```
+
+推荐：
+
+```text
+建模人员现在只能保存草稿。
+我们希望增加发布功能，让下游系统读取稳定版本。
+我还不确定发布后能不能修改、是否需要审批、失败后怎么处理。
+```
+
+第二种写法说明了用户、现状、目标和不确定点，Agent 才知道应该问什么。
+
+### 按这个顺序追问
+
+#### 1. 谁在使用
+
+- 谁发起操作？
+- 谁查看结果？
+- 谁不能操作？
+- 不同角色看到的内容是否一样？
+
+#### 2. 用户要完成什么
+
+- 用户开始操作前处于什么状态？
+- 用户做了什么？
+- 什么结果表示成功？
+- 成功后下一步是什么？
+
+#### 3. 哪些内容不做
+
+- 本次 MVP 不包括什么？
+- 哪些角色、页面或流程以后再做？
+- 哪些旧行为保持不变？
+
+#### 4. 失败时怎么办
+
+- 输入不合法时怎么提示？
+- 没有权限时怎么提示？
+- 外部服务失败时能不能重试？
+- 重试会不会产生重复数据？
+- 失败后怎样恢复？
+
+#### 5. 怎么验收
+
+不要只写“发布成功”。要写用户能看到或测试能读取的结果。
+
+例如：
+
+- 页面显示已发布版本号。
+- 刷新后状态仍为已发布。
+- 下游查询接口返回新版本。
+- 发布失败时保留草稿，并显示可重试提示。
+
+### 一轮只问一个主题
+
+不要一次扔出十几个问题。
+
+先问用户和目标。得到可用答案后，再问流程、边界、失败和验收。
+
+不推荐：
+
+> 请补充角色、权限、状态、流程、异常、接口、表结构和测试方案。
+
+推荐：
+
+> 先确认用户。谁可以发布模型？谁只能查看结果？
+
+### 把形容词改成可以检查的结果
+
+| 模糊说法 | 继续追问 | 可用答案示例 |
+|---|---|---|
+| 发布要快 | 多久算快，在哪个环境测 | 95% 请求在 3 秒内返回受理结果 |
+| 操作要安全 | 要防止什么问题 | 重复点击不会创建两个发布版本 |
+| 权限要控制 | 谁能做，谁不能做 | 建模人员可发布，访客只能查看 |
+| 失败要友好 | 用户看到什么，能做什么 | 保留草稿，显示原因和重试入口 |
+| 支持回滚 | 回到哪里，影响谁 | 恢复到上一个成功版本，下游下一次查询生效 |
+
+只有真实业务方确认后，示例答案才能成为需求。
+
+### 用“开始、动作、结果”检查流程
+
+| 开始 | 动作 | 结果 |
+|---|---|---|
+| 模型为可发布草稿 | 点击发布并确认 | 页面进入发布中 |
+| 发布中 | 系统处理完成 | 显示发布成功和版本号 |
+| 发布中 | 系统处理失败 | 返回草稿，显示原因和重试入口 |
+
+有一格写不出来，说明需求还没有问清楚。
+
+### 分开记录不同类型的信息
+
+| 类型 | 表示什么 | 怎么处理 |
+|---|---|---|
+| 已确认 | 已由业务方、产品或权威资料确认 | 可以进入后续文档 |
+| 待确认 | 暂时没有答案 | 写负责人和确认时间，不让 Agent 猜 |
+| 非目标 | 本次明确不做 | 用来控制范围 |
+| 外部事实 | 来自法规、第三方 API、竞品或技术资料 | 用 `research` 或 `competitive-intelligence` 核对 |
+| 猜测 | 还没有人确认的推测 | 保持为待确认 |
+
+### 处理稳定术语
+
+只有术语含义和使用范围都确认后，才提议写入项目实例的 `CONTEXT.md`。
+
+记录时包含：
+
+- 中文术语。
+- 简短含义。
+- PascalCase 英文标识。
+- 禁用的中文和英文别名。
+
+不要把 Vue 组件、Java 类、表名、接口路径、临时计划或猜测写进词汇表。
+
+### 什么时候需要 ADR
+
+ADR 是架构决策记录。
+
+只有同时满足下面三项时才写：
+
+1. 决定很难回滚。
+2. 没有上下文时，未来读者会困惑。
+3. 团队确实比较过不同方案。
+
+发布版本是否永久不可变，可能需要 ADR。按钮放左边还是右边，通常不需要。
+
+### 推荐的需求记录格式
+
+```markdown
+## 本轮结论
+
+### 已确认
+- ...
+
+### 待确认
+- 问题：
+  负责人：
+  计划确认时间：
+
+### 非目标
+- ...
+
+### 外部事实
+- 事实：
+  来源：
+
+### 稳定术语建议
+- 中文术语：
+  英文标识：
+  含义：
+  禁用别名：
+
+### ADR 建议
+- 无 / 建议记录：
+
+### 下一步
+- ...
+```
+
+### 什么时候可以停止追问
+
+满足下面条件时，可以把结果交给 `yss-product-lifecycle` 检查：
+
+- 用户和目标明确。
+- 主流程能写成“开始、动作、结果”。
+- 失败、权限和恢复路径有答案。
+- 非目标已经记录。
+- 验收结果可以观察。
+- 待确认问题不会影响下一阶段，或已经明确阻塞。
+
+默认由 `yss-product-lifecycle` 运行 `work-unit.discovery-requirements`。
+
+`grill-with-docs`、`to-spec`、`to-tickets` 和 `implement` 只是用户明确点名时使用的兼容入口。它们不能跳过前置检查。
+
+## 团队怎么配合
+
+### 先判断任务类型
+
+| 你的情况 | 从哪里开始 | 重点检查 |
+|---|---|---|
+| 全新产品或新模块 | Discovery | 用户、MVP、非目标、成功标准 |
+| 已有功能的小迭代 | 最近仍然可信的阶段 | 哪些上游内容受到影响 |
+| 可复现 Bug | Bug 诊断 | 复现步骤、失败测试、回归范围 |
+| 技术探索或 spike | 只读调查 | 是否值得做、风险和建议 |
+| 高风险行为变化 | 既有冻结基线 | Spec Delta、架构、契约和回滚 |
+
+### 全新功能
+
+按完整主链推进。不要先写页面或接口。
+
+成功时，每一步都有可读取的结果和审查结论，Ticket 能单独实现和验证。
+
+### 已有功能的小改动
+
+小改动不用机械重跑全部流程，但必须重新判断影响。
+
+1. 用 `route` 找到最近仍然可信的阶段。
+2. 写清这次改什么、不改什么。
+3. 只补受影响的 Spec、设计、API、Ticket 和验证。
+4. 上游内容变化后，重新检查下游资料是否过期。
+5. 再判断切片能否进入 `ready-for-agent`。
+
+“发布成功后增加复制版本号按钮”可能只影响 UI。
+
+“发布后允许回滚”会改变业务行为、状态、API、数据和测试，不能当成小文案修改。
+
+### Bug
+
+1. 用 `diagnosing-bugs` 写出稳定复现步骤。
+2. 找到用户能看到的失败结果。
+3. 用 `tdd` 先写失败测试。
+4. 实现最小修复。
+5. 运行受影响范围的回归测试。
+6. 发现需求或契约错误时，停止修复并重新分诊。
+
+成功时，同一个测试在修复前失败、修复后通过，相邻行为没有回退。
+
+### 技术探索或 spike
+
+可以调查代码、做最小实验、比较方案，但不要直接交付业务代码。
+
+探索结束时要回答：
+
+- 方案能不能做。
+- 主要风险是什么。
+- 会影响哪些页面、接口、数据或仓库。
+- 建议继续、放弃还是另开正式功能。
+
+### 每类文档只回答一类问题
+
+| 文档 | 它回答什么 | 不要写什么 |
+|---|---|---|
+| `CONTEXT.md` | 稳定业务术语叫什么 | 临时方案、表名、类名 |
+| Discovery | 为什么做、为谁做、MVP 是什么 | 详细实现 |
+| Spec | 做什么、边界是什么、怎样验收 | 大段代码 |
+| 产品设计 | 页面怎样走、有哪些状态 | 后端内部结构 |
+| OpenAPI | 前后端怎样交换数据 | 页面布局 |
+| 架构 / ADR | 边界、数据、风险和关键取舍 | 普通 CRUD 细节 |
+| Ticket | 当前小任务做什么、怎样验证 | 整个产品的重复说明 |
+| 发布记录 | 怎样发布、观察和回滚 | 未完成需求 |
+
+### 团队什么时候加入
+
+| 角色 | 提前参与什么 | 交付前重点检查 |
+|---|---|---|
+| 需求经理 | 用户、范围、术语、成功标准 | Spec 是否还能被业务复述 |
+| 产品经理 | 优先级、页面流、状态、原型及商业约束、交付承诺和发布窗口 | 实现是否偏离已确认体验；对外承诺是否经过生物人批准 |
+| 前端工程师 | 原型可行性、API 是否好用 | 页面状态、截图、console、`pnpm` |
+| 后端工程师 | API、数据、领域规则、工程准备 | 行为测试、契约、`./mvnw` |
+| 测试工程师 | 测试入口、异常和恢复路径 | 独立审查、当次验证 |
+| 项目经理 | Ticket、依赖、仓库和风险 | 候选、发布顺序和回滚点 |
+
+角色可以由不同 Agent 运行时承载。实现者不能审查自己的候选。
+
+### 前端开发前后要检查什么
+
+开发前：
+
+- Spec、状态矩阵和原型已经批准并且可以读取。
+- OpenAPI 已 Freeze，或已有无 API 影响记录。
+- 当前垂直切片是 `ready-for-agent`。
+- `frontend_implementation_plan` 已通过检查。
+
+完成前：
+
+- 实际运行登记的 `pnpm` 测试、type-check、lint 和 build。
+- 检查桌面和窄屏。
+- 覆盖加载、空态、错误、权限、成功和失败恢复。
+- 保存截图或视觉回归、交互、console warning 和退出码。
+
+只跑 type-check 不能证明页面已经符合设计。
+
+### 后端开发前后要检查什么
+
+开发前：
+
+- OpenAPI 已 Freeze。
+- 领域规则和数据边界已经说明。
+- 当前垂直切片和实现合同都是当前版本。
+
+开发时按影响选择必要 skill。常见依赖方向是：
+
+```text
+yss-domain
+-> yss-application
+-> yss-repository / yss-mybatis
+-> yss-web-controller / yss-dto
+```
+
+这不表示要为每一层创建一个 Ticket。
+
+完成前：
+
+- 用公开行为写测试。
+- 实际运行项目根目录的 `./mvnw`。
+- 检查 DTO 的真实 HTTP / JSON 形状。
+- 检查异常、校验、幂等和事务边界。
+
+### 开发、合并和发布前的检查
+
+开发前：
+
+- 仓库身份合法。
+- 需求、Spec、设计和 API 没有未解释的矛盾。
+- 实现仓库与验证命令已经登记。
+- 垂直切片满足 `ready-for-agent`。
+
+合并前：
+
+- 实现者已完成本切片测试。
+- 非实现者审查同一候选。
+- 命中的 UI、API、Backend、Data 范围都有证据。
+- `violation` 已修复，`drift` 和 `new_impacts` 已重新分诊。
+
+发布前：
+
+- 对同一候选重新执行验证。
+- 发布、监控和回滚步骤可以执行。
+- 未解决风险有负责人和日期。
+- `gate.release-ready` 由生物人裁决。
+
+### 可以直接复制的团队提示词
+
+新功能分诊：
+
+```text
+使用 yss-product-lifecycle，以 route 模式检查“<功能名>”。
+本轮只读。请用普通话说明当前阶段、缺失内容、影响范围和下一步。
+正式 ID 放在解释后面。
+```
+
+小改动：
+
+```text
+检查“<改动>”相对当前 Spec、设计、API 和 Ticket 的影响。
+只补受影响内容。发现资料过期或新影响时停下并说明原因。
+```
+
+Bug：
+
+```text
+使用 diagnosing-bugs 复现“<问题>”，记录输入、实际结果和预期结果。
+复现稳定后使用 tdd 写失败测试并完成最小修复。
+```
+
+准备实现：
+
+```text
+检查当前垂直切片是否满足 ready-for-agent。
+请列出合同版本、允许写入路径、必需技能和实际验证命令。
+条件不齐时不要实现。
+```
+
+## 创建、接管和更新项目
+
+`create-yss-spec` 用来创建或补齐 YSS 研发管理项目。
+
+CLI 源码由独立项目 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec) 维护。本节只说明怎么使用。
+
+> CLI 不会替你创建前端、后端、远程 Git 仓库、CI 或 Ticket Board。
+
+### 使用前准备
+
+1. 安装符合项目要求的 Node.js 和 npm。
+2. 运行 `git status --short`，记录当前 Git 状态。
+3. 已有项目建议先创建分支或记录当前 commit。
+4. 再次确认目标目录。
+
+### 选对命令
+
+| 你的情况 | 使用方式 |
+|---|---|
+| 新建项目 | `npm create yss-spec@latest` |
+| 给已有项目补上模板 | `attach` |
+| 更新已经接入的模板 | `sync` |
+
+### 新建项目
+
+最简单的方式：
+
+```bash
+npm create yss-spec@latest
+```
+
+需要明确参数时：
+
+```bash
+npx create-yss-spec@latest \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --target-dir "./project" \
+  --git-init
+```
+
+成功后会看到：
+
+- 目标目录已经创建。
+- 根目录存在 `yss-project.yaml`。
+- `repository_mode` 为 `project-instance`。
+- `.yss-template.json` 使用 metadata schema v2，并记录 `templateCommit`。
+
+只想预览时加 `--dry-run`。预览不会创建目录，也不会删除文件。
+
+### 接管已有项目
+
+`attach` 只补充模板管理的文件。业务代码、用户文件和 `.git` 会保留。
+
+先预览：
+
+```bash
+npx create-yss-spec@latest attach \
+  --target-dir . \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --dry-run
+```
+
+看懂预览结果：
+
+| 状态 | 表示什么 | 你要做什么 |
+|---|---|---|
+| `missing` | 文件不存在，可以新增 | 通常可以继续 |
+| `matched` | 文件与模板一致 | 无需处理 |
+| `conflict` | 本地内容和模板不同 | 先看差异，再决定是否覆盖 |
+| `unsafe` | CLI 无法确认能否安全处理 | 停下并人工确认，`--force` 也不能跳过 |
+
+确认写入：
+
+```bash
+npx create-yss-spec@latest attach \
+  --target-dir . \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --apply
+```
+
+只有确认要覆盖 `conflict` 时，才追加 `--force`。
+
+`--dry-run` 和 `--apply` 不能一起使用。已有 `.yss-template.json` 的项目不要重复 `attach`，请使用 `sync`。
+
+### 更新模板
+
+先预览：
+
+```bash
+npx create-yss-spec@latest sync \
+  --target-dir . \
+  --dry-run
+```
+
+确认后执行：
+
+```bash
+npx create-yss-spec@latest sync \
+  --target-dir .
+```
+
+普通同步会：
+
+- 新增缺失文件。
+- 更新没有被本地修改的受管文件。
+- 报告冲突，不直接覆盖。
+- 报告模板已经删除的文件，但默认不删除。
+- 保留与模板无关的文件。
+
+确认要覆盖受管冲突时才使用 `sync --force`。CLI 会先备份。验证失败时会回滚文件，并保留旧 metadata。
+
+### 命令完成后检查
+
+依次运行：
+
+```bash
+git status --short
+scripts/sync-skills --check
+scripts/update-skill-lock --check
+scripts/verify-template
+```
+
+成功时：
+
+- 命令退出码为 `0`。
+- 模板检查全部通过。
+- `git status --short` 只显示你预期的变更。
+- 你知道备份或回滚信息在哪里。
+
+安装、参数、`attach`、`sync` 或 npm 发布问题，请到 `create-yss-spec` 仓库反馈。
+
+模板内容、流程文档、Agent skills 或 `scripts/verify-template` 问题，请在本模板仓库处理。
+
+## 新手术语卡
+
+| 术语 | 先这样理解 |
+|---|---|
+| Agent | 帮你执行特定工作步骤的 AI 协作者 |
+| `yss-product-lifecycle` | 帮你判断当前进度和下一步的流程助手 |
+| Spec | 把“要解决什么、怎样验收”写清楚的功能说明书 |
+| Ticket | 一项可以跟踪的工作 |
+| 功能父 Ticket | 汇总整个功能资料、状态和阻塞项的 Ticket |
+| 垂直切片 Ticket | 能单独完成、单独测试的一小段功能 |
+| 工作单元 `work-unit.*` | 一次范围明确、有输入和输出的工作 |
+| 检查点 `gate.*` | 继续之前必须通过的检查 |
+| `ready-for-human` | 内容还要等人或指定角色确认 |
+| `ready-for-agent` | 当前垂直切片的开发条件已经齐全 |
+| OpenAPI Draft | 还在评审的接口草案 |
+| OpenAPI Freeze | 接口已经确认，前后端可以按它实现 |
+| Fresh Verification | 完成前重新执行的测试或检查 |
+
+### 五种 Ticket 状态
+
+| 状态 | 普通话解释 | 能不能直接开发 |
+|---|---|---|
+| `needs-triage` | 还没分清要做什么 | 不能 |
+| `needs-info` | 缺资料或缺决定 | 不能 |
+| `ready-for-human` | 等人或指定角色确认 | 不能 |
+| `ready-for-agent` | 当前垂直切片已具备实现条件 | 可以 |
+| `wontfix` | 明确不做 | 不适用 |
+
+`ready-for-agent` 只给垂直切片 Ticket。不要给 Spec 初稿、原型或 OpenAPI Draft 使用。
+
+## 常见卡点
+
+### Agent 一上来就准备改文件
+
+重新说明：“使用 `route` 模式，本轮只读。”
+
+### 回答里的专业词太多
+
+让 Agent 先用普通话解释，再附上正式 ID。不要删除正式 ID，后续排查还会用到。
+
+### 文件存在，是不是就能继续
+
+不是。还要检查内容是否经过审查、是否过期、上游资料是否变化。
+
+### OpenAPI Draft 还没评审，前后端已经开始写
+
+先停止实现。完成 Draft Review、必要设计审查和 OpenAPI Freeze 后，再拆可以实现的切片。
+
+### Ticket 很多，却无法单独验收
+
+按用户能看到的结果重新拆垂直切片。不要只按前端、后端或数据库分层拆任务。
+
+### 实现者说“已经测试过”
+
+要求提供实际命令、退出码和候选引用。完成或发布前还要重新运行。
+
+### 用户总说“都可以”
+
+给出两个具体场景，让他选择，并说明各自影响。不要替他决定。
+
+### `--force` 仍然失败
+
+检查是否出现 `unsafe` 或无法判断归属的冲突。它们必须人工处理。
+
+## 最终成功标志
+
+一个功能准备发布时，你应该能找到：
+
+- 已确认的用户问题、范围和成功标准。
+- 当前版本的 Spec、设计和 API 约定。
+- 功能父 Ticket 和可以单独验证的垂直切片。
+- 已批准的实现合同。
+- 实际测试命令和退出码。
+- 非实现者的审查结论。
+- 发布、监控和回滚记录。
+
+少一项时，Agent 应明确说明缺什么，不要只说“已经完成”。
+
+## 下一步
+
+第一次使用时，回到[三分钟开始](#三分钟开始)，先完成一次只读 `route` 检查。
+
+需要核对正式规则时，请查看[生命周期注册表](../process/lifecycle-registry.yaml)、[流程裁剪指南](../process/harness-process-tailoring.md)、[技能注册表](../agents/yss-skill-registry.yaml)、[数字人角色注册表](../agents/digital-human-roles.yaml)和 [Ticket 状态说明](../agents/triage-labels.md)。
+
+这些文件负责定义正式事实。本手册只负责把它们讲明白。