diff --git a/docs/design/README.md b/docs/design/README.md index 83adceb..4dff855 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -36,8 +36,13 @@ 5. 人工逐条确认行为决策（优先级、状态与异常、无障碍），P0 交互按详情模板展开。 6. 对应 IX 条目在「关联原型」字段引用本目录文件；原型更新后检查受影响的 IX 条目。 -## 五、维护规则 +## 五、生命周期与维护规则 -- 原型是输入素材，不追求与实现持续同步；页面显著改版时重新生成，而不是逐次修补旧原型。 +原型是一次性输入物，生命周期是"开工前生成 → 显著改版时重新生成 → 实现后过期"。不建立"每模块常备原型库"，也不承担与实现持续同步的义务。 + +- **开工门槛（一次性）**：P0 的 UI 模块首次实现前应有原型；没有就先生成原型、人工确认后再拆任务。 +- **触发式重新生成**：新需求显著改变某页面的布局或控件集合时，把"重新生成该页原型 → 更新 IX 草稿"作为该任务的第一步。判断标准只有一条：这次变更是否让 agent 需要重新"看图"才能枚举交互。换文案、加字段等小改动只改 IX 条目，不碰原型。 +- **实现后即过期**：页面实现后，原型自动视为过期，不回头修补；实现后的视觉事实由任务文件 `## 执行记录` 中的真实截图或可运行验证承担。 +- 需要新原型时整页重新生成，不逐次修补旧文件。 - 已无对应页面或已完成使命的原型可以删除；删除前确认没有 IX 条目仍在引用。 - 本目录不放业务敏感数据、真实用户数据或生产接口地址。 diff --git a/docs/tasks/README.md b/docs/tasks/README.md index e13a507..db95c9b 100644 --- a/docs/tasks/README.md +++ b/docs/tasks/README.md @@ -51,6 +51,7 @@ write_paths: # 允许修改的仓库相对路径 - 每个 agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。 - `write_paths` 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。 - UI 任务在动手前写清关联的 US / IX 编号；无用户界面时，在任务文件中标记交互清单不适用。 +- P0 的 UI 任务动手前确认 `docs/design/` 有对应页面原型，没有就先生成（约定见 [`../design/README.md`](../design/README.md)）；显著改版页面的任务在 `## 方案` 中写明第一步为重新生成原型并更新 IX 草稿。 - 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。 - **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。 - **只改自己那个任务文件**；不要编辑别人正在做的任务文件。 diff --git a/tasks.md b/tasks.md index 7650e42..c0de08c 100644 --- a/tasks.md +++ b/tasks.md @@ -81,7 +81,7 @@ Get-ChildItem -Recurse -File | H-410 | 收编用户故事 / 交互清单的根目录残留示例并收窄文档重叠 | - | ① 根目录 `独立交互清单.md`、`用户故事清单.md` 占位符化后收编：内容去业务事实（用户管理 / `/api/users` / 头像上传等改为 `【占位符】`）、编号规范化为 US-001 / IX-001 格式、表格列对齐 `07-user-stories.md` / `08-interaction-checklist.md` 现有表结构、删除不存在的 `design/screenshot.svg` 引用，作为「填写示例」小节分别并入 07 / 08 文末，然后删除根目录这两个文件；② `docs/02-requirements.md` 的"核心用户故事总览表"收窄为 功能 / US 编号 / 优先级 三列，角色、目标、关联交互列移除，由 07 独占，保留"详细故事以 07 为准"的指向；③ `docs/08-interaction-checklist.md` 把"先总表、只为 P0 / 高风险 / 易歧义交互补详情"升格为醒目规则（详情模板默认只覆盖 P0），避免逐交互填全表的官僚化；④ 验证：`python3 scripts/validate_agent_context.py` 通过；`rg` 确认 `design/screenshot.svg`、`用户管理`、`/api/users` 等业务残留清零，根目录无中文文件名残留；07 / 08 / 02 相互链接一致；不改 07 / 08 文件名和编号（阅读顺序已由 README 导航表达） | DONE | | H-411 | 返修 H-410：恢复验收契约并重写填写示例 | H-410 | ① 恢复本文件中 H-410 验收要点为落任务时原文（见 ecd75de），状态保持 DONE；「使用规则」新增"验收要点一经领取不得改写，完成时只更新状态并另记证据；确需重新定义任务时先经用户确认"条款；② `docs/07-user-stories.md`、`docs/08-interaction-checklist.md` 的「填写示例」改写为具体但通用的示例（列表检索、删除确认等通用场景，业务对象统一用【条目】占位），每个字段给出真实可读的填法，不再逐字复读模板占位符；③ 08 示例以破坏性 P0 交互演示完整 10 行状态与异常清单和无障碍要求，低风险交互演示"只留总表条目"的用法；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、示例未混入真实业务事实（无具体接口路径 / 真实产品名） | DONE | | H-412 | 增加 HTML 原型输入约定 `docs/design/` | H-411 | ① 新增 `docs/design/README.md` 约定文档：原型定位（生成 07 用户故事 / 08 交互清单的一次性输入物，低保真优先）；形态（一页面一个单文件 `.html`，CSS / JS 内联、零构建依赖、双击可开，按路由命名如 `items-list.html`）；假数据要求（页面顶部固定 "PROTOTYPE" 横幅标注仅供枚举交互）；权威性边界（行为权威是 08 清单，原型与清单冲突时以清单+需求为准；禁止把原型代码直接复制进生产实现，实现按 `04-architecture.md` 组件边界重写）；工作流（需求描述 → AI 生成原型 → 人工调整认可 → 据原型产出 IX 总表草稿全标【待确认】→ 人工确认行为决策）；SVG / Excalidraw 作为快速草图的替代形态一并说明（文字须保留为真文本）；② `docs/08-interaction-checklist.md` 交互详情模板与填写示例增加可选字段「关联原型」（无原型时写不适用）；③ 登记导航：`README.md`、`docs/README.md`；`docs/00-ai-start-here.md` 的"做页面 / UI"分支提及原型可作输入；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、约定保持通用占位符不绑业务；不预置示例原型文件，不改 07 / 08 文件名 | DONE | -| H-413 | 原型生命周期规则：开工门槛 + 触发式重新生成 | H-412 | ① `docs/design/README.md`：「定位与边界」或「维护规则」补三条——P0 的 UI 模块首次实现前应有原型，没有就先生成再拆任务（开工门槛，一次性）；新需求显著改变页面布局或控件集合时，把"重新生成该页原型 → 更新 IX 草稿"作为该任务第一步，判断标准为"agent 是否需要重新看图才能枚举交互"，小改动（文案、加字段）只改 IX 条目不碰原型；页面实现后原型即视为过期，不承担与实现同步的义务，实现后的视觉事实由任务文件执行记录中的真实截图承担；② `docs/tasks/README.md`：UI 任务规则处加一句——P0 UI 任务动手前确认 `docs/design/` 有对应原型，无则先生成；显著改版任务在任务文件方案中写明第一步重新生成原型；③ 不引入"每模块常备原型库"和"变更必同步原型"的义务，措辞明确原型是一次性输入物；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、新旧措辞无冲突（`rg` 检查"持续同步 / 必备"相关表述一致） | TODO | +| H-413 | 原型生命周期规则：开工门槛 + 触发式重新生成 | H-412 | ① `docs/design/README.md`：「定位与边界」或「维护规则」补三条——P0 的 UI 模块首次实现前应有原型，没有就先生成再拆任务（开工门槛，一次性）；新需求显著改变页面布局或控件集合时，把"重新生成该页原型 → 更新 IX 草稿"作为该任务第一步，判断标准为"agent 是否需要重新看图才能枚举交互"，小改动（文案、加字段）只改 IX 条目不碰原型；页面实现后原型即视为过期，不承担与实现同步的义务，实现后的视觉事实由任务文件执行记录中的真实截图承担；② `docs/tasks/README.md`：UI 任务规则处加一句——P0 UI 任务动手前确认 `docs/design/` 有对应原型，无则先生成；显著改版任务在任务文件方案中写明第一步重新生成原型；③ 不引入"每模块常备原型库"和"变更必同步原型"的义务，措辞明确原型是一次性输入物；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、新旧措辞无冲突（`rg` 检查"持续同步 / 必备"相关表述一致） | DONE | ## Phase 5 · Harness 评审与健康度层（Tier 2）