docs(ui): add user stories and interaction checklists

2026-07-17 09:18:42 +08:00
parent 123849f5ee
commit 93cfb165c3
12 changed files with 229 additions and 20 deletions
@@ -19,6 +19,7 @@
 | [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | AI coding agent 的入口、阅读顺序、任务领取规则 |
 | [`docs/01-vision.md`](docs/01-vision.md) | 项目为什么做、为谁做、什么不做 |
 | [`docs/02-requirements.md`](docs/02-requirements.md) | 产品需求、用户故事、验收标准 |
+| [`docs/07-user-stories.md`](docs/07-user-stories.md) | 用户目标、业务价值、验收场景与 US / IX 追踪 |
 | [`docs/03-tech-stack.md`](docs/03-tech-stack.md) | 技术选型和运行命令 |
 | [`docs/04-architecture.md`](docs/04-architecture.md) | 系统结构、职责边界、数据模型、开发顺序 |
 | [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | AI 写代码前必须遵守的硬规则 |
@@ -27,6 +28,7 @@
 | [`docs/adoption-checklist.md`](docs/adoption-checklist.md) | 已有项目接入 harness 文档的迁移清单 |
 | [`docs/api.md`](docs/api.md) | API 合约模板 |
 | [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 |
+| [`docs/08-interaction-checklist.md`](docs/08-interaction-checklist.md) | UI 交互、状态反馈、无障碍与验收证据 |
 | [`docs/clean-state-checklist.md`](docs/clean-state-checklist.md) | 会话收尾检查清单，保证下一轮无需人工修复即可开工 |
 | [`docs/current-state.md`](docs/current-state.md) | 当前实现状态快照，防止计划和代码现实脱节 |
 | [`docs/agent-context.json`](docs/agent-context.json) | 机器可读上下文路由：最小必读、任务类型和 SHA 刷新规则 |
@@ -67,7 +69,7 @@

 新项目从零开始时，建议复制根目录入口文件和 `docs/` 目录（含 `docs/tasks/`），并按操作系统选择 `init.sh` 或 `init.ps1`。复制后按顺序处理：

-1. 从 `docs/01-vision.md` 和 `docs/02-requirements.md` 开始替换业务内容。
+1. 从 `docs/01-vision.md` 和 `docs/02-requirements.md` 开始替换业务内容；有 UI / UX 时，同时完成 `docs/07-user-stories.md` 和 `docs/08-interaction-checklist.md`。
 2. 在 `docs/03-tech-stack.md` 固定技术选型，不确定的选项标为待定。
 3. 在 `docs/04-architecture.md` 写清事实来源、数据模型、系统边界。
 4. 在 `docs/06-tasks.md` 拆出阶段路线图和建议任务；开工时按 `docs/tasks/README.md` 把任务落成 `docs/tasks/T-<编号>.md`，要求 AI 每轮只领取一个任务。
@@ -21,6 +21,8 @@
 7. [`tasks/README.md`](tasks/README.md)：任务文件约定（一任务一文件）；本轮任务从 `docs/tasks/` 领取。
 8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。

+若项目有页面、表单、移动端、桌面端或其他用户交互界面，首次接入还必须完成[用户故事清单](07-user-stories.md)和[交互清单](08-interaction-checklist.md)，再开始拆 UI 任务。
+
 日常会话不需要机械重读全部文档：

 1. 读取仓库级规则和 [`agent-context.json`](agent-context.json)。
@@ -112,6 +114,8 @@ MVP 不做：
 做页面 / UI：

 - 先看 `02-requirements.md` 的对应验收标准。
+- 再看 `07-user-stories.md` 的用户目标和验收场景。
+- 再看 `08-interaction-checklist.md` 的关联 IX 条目、状态和无障碍要求。
 - 再看 `routes.md` 的页面职责。
 - 最后看 `04-architecture.md` 的组件边界。

@@ -22,11 +22,11 @@

 ### 第一版 MVP（最小闭环）

-| 功能 | 用户能做什么 | 优先级 |
-| --- | --- | --- |
-| 【功能 1】 | 【用户动作和结果】 | P0 |
-| 【功能 2】 | 【用户动作和结果】 | P0 |
-| 【功能 3】 | 【用户动作和结果】 | P0 |
+| 功能 | 用户能做什么 | 优先级 | 关联用户故事 |
+| --- | --- | --- | --- |
+| 【功能 1】 | 【用户动作和结果】 | P0 | US-001 |
+| 【功能 2】 | 【用户动作和结果】 | P0 | US-002 |
+| 【功能 3】 | 【用户动作和结果】 | P0 | 【US 编号】 |

 ### 后续迭代

@@ -37,10 +37,18 @@

 ## 四、核心用户故事（MVP）

-1. 作为【角色】，我打开系统后能【第一步】。
-2. 我可以【关键动作】，并看到【结果】。
-3. 我可以【继续动作】，系统会【保存 / 同步 / 展示】。
-4. 当【异常场景】发生时，系统会【降级 / 提示 / 阻止错误】。
+详细故事以[用户故事清单](07-user-stories.md)为准；本文只维护与功能和优先级对应的总览，避免两处成为相互冲突的权威来源。
+
+| 用户故事 | 功能 | 角色 | 目标 / 结果 | 优先级 | 关联交互 |
+| --- | --- | --- | --- | --- | --- |
+| US-001 | 【功能 1】 | 【角色】 | 【用户想完成什么并得到什么】 | P0 | IX-001、IX-002 |
+| US-002 | 【功能 2】 | 【角色】 | 【用户想完成什么并得到什么】 | P0 | 【IX 编号 / 不适用】 |
+
+每条故事至少明确：
+
+1. 作为【角色】，我想要【完成目标】，从而【得到价值】。
+2. 当【异常、权限或边界场景】发生时，系统会【给出保护和下一步】。
+3. 有 UI 的故事把点击、输入、加载、校验、成功和失败反馈写入[交互清单](08-interaction-checklist.md)。

 ## 五、验收标准（MVP）

@@ -49,6 +57,7 @@
 - **【功能 1】**：【打开 / 点击 / 输入 / 保存 后，应看到什么结果】。
 - **【功能 2】**：【明确时间、状态、数据持久化或错误处理要求】。
 - **【功能 3】**：【跨刷新、跨设备、权限、边界情况等要求】。
+- 每条 P0 判据关联至少一个 US 编号；有用户界面的判据同时关联相关 IX 编号。

 ## 六、范围边界与决策

@@ -69,4 +78,4 @@
 - 【自动化边界风险】：【是否会自动点击、批量提交、爬取、发送消息或触发不可逆操作】。
 - 【隐私数据风险】：【是否处理个人信息、敏感文件、聊天记录、定位、联系方式等】。
 - 【合规风险】：【版权、平台条款、行业监管、数据跨境、审计留痕等是否需要确认】。
- 【待确认问题】：【谁来决策，什么时候需要决策】。
+- 【待确认问题】：【谁来决策，什么时候需要决策】。
@@ -13,6 +13,7 @@

 ## 1. 动手前

+- 涉及页面、表单、导航或用户可见状态时，先读取关联的 `07-user-stories.md`、`08-interaction-checklist.md`、`routes.md` 和验收标准。
 - 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
 - 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
 - 先找现有函数、组件、工具和测试，复用优先。
@@ -56,6 +57,7 @@
 - [ ] 对得上需求验收标准。
 - [ ] 没有夹带无关改动。
 - [ ] 涉及文档事实变化时，文档已同步。
+- [ ] 涉及 UI 时，已验证关联 US / IX 的正常、加载、异常、权限和无障碍要求，或记录明确的不适用理由。
 - [ ] 已在当前任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录` 记录跑过的命令和结果作为证据（约定见 [`tasks/README.md`](tasks/README.md)），不靠"代码已写"判定完成。
 - [ ] 回复里如实说明跑了什么命令、结果如何。

@@ -85,4 +87,4 @@ go test ./...

 ## 9. 拿不准就问

-问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
+问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
@@ -0,0 +1,77 @@
+# 用户故事清单
+
+> 本文记录“谁在什么场景下，为了获得什么价值，要完成什么目标”。它是产品需求的细化清单，不写接口、数据字段、组件实现或逐个按钮的行为。
+> 页面如何响应操作见[交互清单](08-interaction-checklist.md)；页面入口和导航见[路由与页面结构](routes.md)；接口形状以[API 合约](api.md)为准。
+
+## 一、何时使用
+
+- 有用户角色、业务目标或交互式界面的项目，必须为每个 P0 闭环维护用户故事。
+- 无图形界面的 CLI、批处理或纯基础设施项目，也可用本文描述操作者目标；没有界面交互时，不必建立交互清单。
+- 一个用户故事描述一个可感知的业务结果，不按“一个页面”“一个按钮”机械拆分。
+
+## 二、职责边界与关联
+
+| 信息 | 权威文档 | 说明 |
+| --- | --- | --- |
+| MVP 范围、优先级、非目标 | [需求](02-requirements.md) | 先定做什么，再细化故事。 |
+| 用户目标、场景与验收场景 | 本文 | 每个故事使用稳定的 US 编号。 |
+| 页面操作、状态与反馈 | [交互清单](08-interaction-checklist.md) | 每项交互使用稳定的 IX 编号，并回链 US。 |
+| 页面入口、导航与组件归属 | [路由与页面结构](routes.md) | 不在本文复制路由表。 |
+| 接口、事件与错误格式 | [API 合约](api.md) | 不在本文虚构接口路径或字段。 |
+
+- 用户故事 ID 使用 US-001、US-002 的形式；编号一经引用不要重用。
+- 一条用户故事可以关联多条交互；每条面向用户的 P0 交互都应回链至少一个用户故事。
+- 需求变化时，先更新[需求](02-requirements.md)，再同步本文和受影响的交互清单、任务验收。
+
+## 三、用户故事总表
+
+| ID | 标题 | 优先级 | 角色 | 要达成的目标 | 关联功能 | 关联交互 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| US-001 | 【一句话故事名】 | P0 | 【角色】 | 【用户结果】 | 【功能名】 | IX-001、IX-002 | 【待确认 / 已定】 |
+| US-002 | 【一句话故事名】 | P1 | 【角色】 | 【用户结果】 | 【功能名】 | 【IX 编号或不适用】 | 【待确认 / 已定】 |
+
+## 四、故事详情模板
+
+### US-001 【故事标题】
+
+- 优先级：【P0 / P1 / P2】
+- 关联功能：【02-requirements.md 中的功能名称】
+- 关联页面 / 入口：【路由、命令或入口名称】
+- 关联交互：【IX-001、IX-002；无 UI 时写不适用】
+- 角色：【谁】
+- 使用场景 / 前置条件：【何时、在什么限制下】
+
+**用户故事**
+
+作为【角色】，我想要【完成的目标】，从而【得到的价值】。
+
+**范围**
+
+- 包含：【本故事必须覆盖的结果】
+- 不包含：【明确不做或由其他故事承担的内容】
+
+**验收场景**
+
+1. 假如【前置条件】，当【用户目标相关的动作发生】，那么【用户可观察到的结果】。
+2. 假如【异常、权限或数据边界】，当【用户尝试目标】，那么【系统如何保护用户并给出下一步】。
+3. 假如【需要保存、同步或恢复】，当【用户离开再返回】，那么【应保留或应丢弃的结果】。
+
+**待确认**
+
+- 【业务规则、角色权限、数据边界或文案决策】
+
+## 五、编写规则
+
+- 先写角色、目标和价值，再写验收场景；不要把“点击某按钮”当作故事本身。
+- P0 故事必须可独立验收，并明确成功、失败或无权限时用户得到的结果。
+- 同一故事的细粒度点击、输入、加载、校验、确认与撤销，写入[交互清单](08-interaction-checklist.md)。
+- 未确认的规则写为【待确认】，不要让 agent 在代码中自行补全。
+- 需求、优先级或范围改变后，检查关联 US、IX、任务文件和验收标准是否仍一致。
+
+## 六、交付前检查
+
+- [ ] 每个 P0 功能至少关联一个 US 编号。
+- [ ] 每个故事都说明角色、目标、价值和可验证的验收场景。
+- [ ] UI 故事已关联对应 IX 编号；无 UI 的故事明确标为不适用。
+- [ ] 故事没有复制接口、字段或组件实现细节。
+- [ ] 范围、优先级与[需求](02-requirements.md)一致。
@@ -0,0 +1,95 @@
+# 交互清单
+
+> 本文把用户故事落成可实现、可测试的界面行为：用户如何触发、系统处于什么状态、如何反馈，以及失败时怎样恢复。
+> 本文适用于 Web、移动端、桌面端、插件和其他面向用户的交互界面；纯 CLI 或无界面项目可标记为不适用。
+
+## 一、职责边界
+
+| 信息 | 写在哪里 | 说明 |
+| --- | --- | --- |
+| 用户目标、价值与业务验收 | [用户故事清单](07-user-stories.md) | 本文中的每项 UI 交互回链一个或多个 US 编号。 |
+| MVP 范围与优先级 | [需求](02-requirements.md) | 交互清单不能扩大需求范围。 |
+| 页面入口、路由和组件归属 | [路由与页面结构](routes.md) | 不重复维护页面导航事实。 |
+| API、事件和错误格式 | [API 合约](api.md) | 这里只引用合约，不自行定义接口路径、字段或状态码。 |
+
+- 交互 ID 使用 IX-001、IX-002 的形式；编号一经引用不要重用。
+- 一项交互可以服务多个用户故事；一个故事通常包含多项交互。
+- 有用户可见动作、自动状态变化或关键系统反馈的 P0 页面，都应列入本文。
+
+## 二、交互总表
+
+先为每个页面或组件列出完整交互，再为高风险、P0 或容易产生歧义的交互补充详情。
+
+| ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| IX-001 | US-001 | 【页面 / 组件】 | 【点击 / 输入 / 键盘 / 自动】 | 【用户要完成什么】 | 【可观察到的结果】 | P0 | 【待确认 / 已定】 |
+| IX-002 | US-001、US-002 | 【页面 / 组件】 | 【触发方式】 | 【用户要完成什么】 | 【可观察到的结果】 | P1 | 【待确认 / 已定】 |
+
+## 三、交互详情模板
+
+### IX-001 【交互标题】
+
+- 关联用户故事：【US-001】
+- 关联需求 / 验收：【功能名或验收条目】
+- 页面 / 组件：【路由、界面名称或组件名称】
+- 目标角色：【角色】
+- 前置条件：【登录态、权限、数据存在性、网络或其他条件】
+- 触发方式：【点击 / 键盘 / 输入 / 手势 / 自动触发】
+- 用户操作：【用户具体做什么】
+- 服务 / 数据依赖：【引用 API、事件或本地模块合约；无则写不适用】
+
+**正常路径**
+
+1. 用户【操作】。
+2. 系统【立即可见的响应，例如聚焦、展开、禁用重复提交或显示进度】。
+3. 系统【完成后的状态变化、页面变化或数据刷新】。
+4. 用户看到【成功反馈、下一步入口或返回位置】。
+
+**状态与异常清单**
+
+| 场景 | 必须说明的行为 | 本交互约定 |
+| --- | --- | --- |
+| 默认 / 可操作 | 控件是否可见、可用，用户如何发现其用途 | 【填写】 |
+| 加载 / 提交中 | 是否禁用重复操作、进度如何表达、是否保留上下文 | 【填写】 |
+| 成功 | 数据、页面或焦点如何更新，用户如何确认完成 | 【填写】 |
+| 空状态 | 无数据时解释原因并给出可执行的下一步 | 【填写 / 不适用】 |
+| 输入校验 | 何时校验、错误显示位置、如何修复 | 【填写 / 不适用】 |
+| 服务或网络错误 | 可理解的错误、保留的数据、重试或恢复路径 | 【填写 / 不适用】 |
+| 权限不足 | 不静默失败，说明限制和可执行的下一步 | 【填写 / 不适用】 |
+| 冲突 / 重复提交 | 幂等、刷新或冲突解决方式 | 【填写 / 不适用】 |
+| 破坏性操作 | 是否确认、影响范围、取消、撤销或恢复方式 | 【填写 / 不适用】 |
+| 中断 / 离线 | 草稿、返回、关闭或网络恢复后的处理 | 【填写 / 不适用】 |
+
+**可访问性与多端要求**
+
+- 键盘与焦点：【Tab 顺序、Enter / Escape、路由变化后的焦点位置】
+- 语义与读屏：【控件名称、状态、错误和动态反馈如何被感知】
+- 触控与手势：【不依赖悬停或单一手势；最小可点击区域遵循项目平台规范】
+- 响应式 / 小屏：【窄屏、横屏、缩放或动态文字下的布局和操作】
+- 动效：【是否需要动效、动效表达什么，以及减少动态效果时的降级】
+
+**验收证据**
+
+- 手工验证：【角色、环境、操作和可观察结果】
+- 自动化验证：【测试层级、场景或命令】
+- 关联任务：【T-编号；尚未拆任务时写待创建】
+
+## 四、页面级检查清单
+
+每个有交互的页面或组件在交付前至少确认：
+
+- [ ] 已关联用户故事、页面 / 组件和验收条目。
+- [ ] 主操作与次要操作清晰，用户能预测操作后果。
+- [ ] 加载、成功、空、错误、权限和必要的确认 / 撤销场景都有约定。
+- [ ] 表单有可见标签、明确校验和可恢复的错误提示。
+- [ ] 不把颜色、悬停或手势作为唯一信息和操作方式。
+- [ ] 键盘、焦点、读屏、触控目标、缩放和小屏场景已说明或明确不适用。
+- [ ] 页面跳转、返回、关闭和中断后，用户不会丢失未说明的数据或上下文。
+- [ ] 交互没有引入[需求](02-requirements.md)之外的业务范围。
+
+## 五、维护规则
+
+- 先更新用户故事或需求，再更新受影响的 IX 条目。
+- 交互涉及接口、字段或错误格式变化时，同步更新[API 合约](api.md)；不要只在本文写成事实。
+- UI 任务的任务文件应列出相关 US / IX 编号，并把验证结果记录为完成证据。
+- 不确定的交互规则写为【待确认】，不要以示例行为替代产品决策。
@@ -19,6 +19,7 @@
 - [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
 - [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
 - [需求](02-requirements.md)：要什么、用户故事、验收标准，不写技术实现。
+- [用户故事清单](07-user-stories.md)：用户目标、业务价值、验收场景与 US / IX 关联。
 - [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。
 - [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
 - [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
@@ -27,6 +28,7 @@
 - [已有项目接入清单](adoption-checklist.md)：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。
 - [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
 - [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
+- [交互清单](08-interaction-checklist.md)：页面 / 组件交互、状态反馈、无障碍与验收证据。
 - [当前实现状态](current-state.md)：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。
 - [Agent 上下文清单](agent-context.md) / [`agent-context.json`](agent-context.json) / [`Schema`](agent-context.schema.json)：按任务类型选择文档、用提交 / 文件 SHA 避免重复读取。
 - [Gitea MCP 接入](gitea-mcp.md)：可选的共享文档、Issue / PR 协调、安全配置和断连降级规则。
@@ -29,7 +29,7 @@
 | `init.sh` 或 `init.ps1` | 标准启动与验证入口，按操作系统二选一 |
 | `scripts/validate_agent_context.py` | 零第三方依赖校验清单和引用路径 |

-推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`；`progress.md` 可选（历史归档 / 项目级大事记）。
+推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`；有 UI / UX 的项目再补 `docs/07-user-stories.md` 与 `docs/08-interaction-checklist.md`；`progress.md` 可选（历史归档 / 项目级大事记）。

 需要 Gitea 多 Agent 协作时，再复制 `docs/gitea-mcp.md`、`docs/gitea-collaboration.md`、`.gitea/` 模板、`scripts/setup_gitea_labels.py`、`scripts/audit_gitea_coordination.py`、离线治理脚本和测试；先只读预览远端标签差异，再由维护者显式 `--apply`。Actions 工作流仅在仓库已启用 Actions 且 runner 可用时生效。

@@ -20,10 +20,14 @@
      "README.md",
      "docs/README.md",
      "docs/01-vision.md",
-      "docs/02-requirements.md"
+      "docs/02-requirements.md",
+      "docs/07-user-stories.md",
+      "docs/08-interaction-checklist.md"
    ],
    "ui": [
      "docs/02-requirements.md",
+      "docs/07-user-stories.md",
+      "docs/08-interaction-checklist.md",
      "docs/routes.md",
      "docs/04-architecture.md"
    ],
@@ -4,12 +4,12 @@

 ## 页面路由

-| 路由 | 页面 | MVP 说明 |
-| --- | --- | --- |
-| `/` | 首页 / 列表页 | 展示主入口 |
-| `/items/{id}` | 详情页 | 展示单个资源详情 |
-| `/login` | 登录页 | 登录入口 |
-| `/settings` | 设置页 | 用户或系统配置 |
+| 路由 | 页面 | MVP 说明 | 关联用户故事 | 关联交互 |
+| --- | --- | --- | --- | --- |
+| `/` | 首页 / 列表页 | 展示主入口 | 【US 编号】 | 【IX 编号】 |
+| `/items/{id}` | 详情页 | 展示单个资源详情 | 【US 编号】 | 【IX 编号】 |
+| `/login` | 登录页 | 登录入口 | 【US 编号】 | 【IX 编号】 |
+| `/settings` | 设置页 | 用户或系统配置 | 【US 编号】 | 【IX 编号】 |

 ## 页面职责

@@ -31,6 +31,12 @@
 - 通过账号 API 建立会话。
 - 登录成功后返回原目标页或首页。

+## 交互关联
+
+- 每个有用户操作或自动状态变化的页面，关联[用户故事清单](07-user-stories.md)中的 US 编号和[交互清单](08-interaction-checklist.md)中的 IX 编号。
+- 本文只说明页面入口、职责和导航；加载、空、错误、权限、校验、确认、撤销和无障碍等具体行为以交互清单为准。
+- 路由、页面职责或导航规则变化后，检查受影响的 US、IX、API 合约和任务验收是否需要同步。
+
 ## 组件建议

 | 组件 | 归属 | 说明 |
@@ -37,6 +37,7 @@ write_paths:           # 允许修改的仓库相对路径
 ---

 ## 问题 / 背景
+## 关联需求与交互（如适用）
 ## 方案
 ## 验收要点
 ## 边界（不改什么）
@@ -49,6 +50,7 @@ write_paths:           # 允许修改的仓库相对路径
 - 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。
 - 每个 agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
 - `write_paths` 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。
+- UI 任务在动手前写清关联的 US / IX 编号；无用户界面时，在任务文件中标记交互清单不适用。
 - 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
 - **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
 - **只改自己那个任务文件**；不要编辑别人正在做的任务文件。
@@ -18,6 +18,12 @@ write_paths:

 （现象、根因、为什么要做）

+## 关联需求与交互（如适用）
+
+- 用户故事：【US-编号；无用户故事时说明原因】
+- 交互清单：【IX-编号；无 UI 时写不适用】
+- 相关页面 / 路由：【路径或不适用】
+
 ## 方案

 （怎么改，落到"改哪个文件、改成什么"）