文档驱动开发（Structured Dev Flow）v2.1

快速上手（30 秒）

1. 先定档：接到任务先判定复杂度档位 T0–T4（见下表），这决定后面走多少流程。
2. 再读图：项目已有 docs/ 时，先读三份全局文档（PROJECT-MAP.md → PROJECT-OVERVIEW.md → CHANGELOG.md 顶部），按图定点深读，不要全量扫描目录和代码（铁律⑥，省时间也省 token）。
3. 再执行：T0 直接答；T1 改完就报；T2 起必须维护测试用例库；T3/T4 走完整文档流水线。含 UI 页面时，交付前必须过 UI 验收（真实点一遍 + 设计检查）。
4. 文档与测试都按版本存档：每个版本的 PRD、交互、系统设计、原型、测试用例、变更日志、升级目标统一放在 docs/vX.X/ 下。

五档复杂度路由（核心）

> UI 验收（A 页面交互功能实测 / B UI 设计检查）在 T1–T4 全部档位强制，只是范围不同——最小集 / 改动页 / 全量页。详见下方「UI 验收（含页面项目强制）」。

判定不准时的兜底规则（命中任一即升档）：

• 涉及文件数 ≥ 5 → 至少 T2
• 涉及数据库迁移 / 认证 / 支付 / 公开 API → 至少 T3
• 用户描述出现"重构""迁移""从零""做个 App" → 至少 T3
• 会话预计长到需要跨上下文压缩 → 至少 T3
• 拿不准就升一档，并在执行开场向用户说明档位与理由；用户可要求降档，降档后按低档执行并在汇报中注明裁剪了什么。

不适用场景

以下任务不触发本流程：纯问答/调研/写作；一次性临时脚本；数据分析、表格处理等不产出代码的任务；只改配置/文案且无功能行为的改动。边界模糊时按"是否产出需要测试和交付的代码"判断：是 → 走本流程，否 → 不走。

六条铁律（所有档位通用）

1. 文档先行：任何代码改动之前，对应文档必须先写好并确认。禁止先写代码再补文档；发现已写了代码而文档缺失，立即停手补齐再继续。（T1 的最小落地：动手前 2~3 句话说清改什么、为什么、影响哪些模块。）
2. 版本克制：只有 UI 大规模改版（视觉体系整体更换，或超过一半页面重构）或 功能大规模升级（新增/重构超过约 1/3 功能模块，或核心流程/架构改变）才升大版本（v1.0 → v2.0）。其余一律只升小版本（v1.0 → v1.0.1）。升大版本必须先向用户说明理由并获确认。
3. 测透再交（累积回归）：T2 及以上必须维护版本化测试用例库，且当前版本的测试集 = 上一版本全部有效用例（继承）+ 本版新增/修改用例。跑一遍当前版本测试即等于"冒烟 + 全量回归"，老功能被改坏必然暴露。同时按本次改动 diff 检索历史版本文档，列出关联影响清单（执行见 references/04 第 0.5.2 节）逐项加深回归。冒烟全绿前禁止展开详测。
4. 交付即用：必须产出打包好的成品（构建产物/安装包/可直接导入的目录），用户拿到即可运行测试，不允许只给源码。T0/T1 无交付物时跳过。
5. 环节闭环：文档 → 开发 → 测试 → 交付。进入下一环节前先核验上一环节完成标志；上一环节未完成，禁止开始下一环节。（T1 允许四环节在对话内一次性完成。）
6. 地图常新：T1 起每个项目必须在 docs/ 下维护三份全局文档——项目地图（东西在哪）、项目总览（现在什么状态）、变更日志（怎么变成这样的）。开场先读（定档后第一件事，按图定点深读，禁止全量扫描目录与代码），收尾必更（命中更新触发点却没更新 → 禁止交付）。规范见 references/14。

版本化文档体系（T2 起强制）

每个版本的所有产物——文档、测试用例、变更日志、原型、升级目标——统一存入 docs/vX.X/：

<项目根>/docs/
├── CHANGELOG.md                 # 项目级变更总日志（跨版本）
├── ROADMAP.md                   # 升级目标与版本规划
└── v1.0/                        # 每个大版本一套完整文档
    ├── 00-release-goal.md       # 本版升级目标（为什么做、做到什么程度算成）
    ├── 01-research.md           # 调研（T3/T4）
    ├── 02-prd.md                # 产品文档
    ├── 03-interaction.md        # 交互文档
    ├── prototype/               # HTML 交互原型
    │   ├── index.html           # 总览：token 展示板 + 页面导航 + 主流程入口
    │   └── page-01-xxx.html
    ├── 04-system-design.md      # 系统设计
    ├── testcases/               # ★ 测试用例库（版本累积，核心资产）
    │   ├── 00-cumulative-matrix.md   # 累积矩阵：继承/新增/修改/废弃 一览
    │   ├── 01-smoke-suite.md         # 冒烟套件（从用例库抽取的 P0 子集）
    │   ├── tc-module-a.md            # 按模块存用例
    │   └── tc-module-b.md
    ├── 05-function-test-report.md    # 测试执行结果
    ├── 06-ui-test-report.md          # UI 测试结果
    ├── 07-ux-review-report.md        # UX 校验结果
    └── CHANGELOG.md                  # 本版变更日志

版本升级的文档操作

• 升大版本（铁律②两种情形且经用户确认）：新建 v2.0/ 文件夹，从上一版本完整复制后修订，禁止覆盖旧版本。
• testcases/ 必须整目录复制 —— 这是累积回归的物理载体。
• 升小版本（其余一切改动）：不新建文件夹，受影响文档头部版本号 v1.0 → v1.0.1，变更记录追加一行；用例库同目录增量更新。
• 每个文档头部写版本号、日期、状态、变更记录表。
• 用户明确要求不写文档文件时，改为在对话中输出，但测试用例仍需落盘（铁律③）。

升级目标（00-release-goal.md）

T2 起每个版本开写，回答四个问题：本版要解决什么 → 验收标准（可勾选）→ 明确不做的事 → 与上一版的关系（纯增量 / 重构 / 修复）。模板见 references/13-version-doc-system.md。

项目全局文档（铁律⑥的落地，T1 起）

> 详细规范读 references/14-project-global-docs.md。

docs/vX.X/ 是时间切片（翻到某版本就知道那一版做了什么），三件套是横切索引（不管哪个版本，先知道东西在哪、现在什么状态）。两者互补，缺一不可。

开场读图 SOP（定档后第一件事，禁止跳过）

① 读 PROJECT-MAP.md        （全读）
② 读 PROJECT-OVERVIEW.md   （全读）
③ 读 CHANGELOG.md 顶部      （只看最近两段，不通读历史）
④ 按 MAP 的「常见任务定位表」定点深读具体文件
   —— 只读本次相关的；禁止 ls -R / 全量 grep / 逐个文件打开扫

省 token 的三条硬约束：目录遍历只在建/更新 MAP 时做一次；只有 MAP 指向的文件才读；读时优先定位段落而非整文件通读。

收尾更新触发点（命中即更新，否则禁止交付）

一致性红线：地图里写的路径必须真实存在。发现地图与实际不符 = 缺陷，立即修——过期的地图比没地图更危险，因为你会信它。

老项目/新项目接入：新项目在系统设计定稿后立即建；老项目从本次改动开始建，不补写历史（CHANGELOG 注明"此前无文档记录"）。扫描生成的地图必须人工校正。

UI 验收（含页面项目强制，T1–T4）

> 总入口 references/05；A 详单 references/15；B 详单 references/16。

交付物里有能打开的页面（网页/小程序/App/桌面端/HTML 原型），就必须过这道关。 历史上返工最多的就是它：按钮渲染出来了但没绑事件、被遮罩盖住点不到、提交卡 loading、跳转 404、控制台一片红——这些读代码 100% 发现不了，所以执行方式是被强制的。

各档强度

三条硬规矩

1. 必须真实操作："代码走查未发现异常"不能充当"功能测试通过"。环境确实不支持时，标注「未实跑，待用户确认」并列入遗留清单，不得替用户勾通过。
2. 测产物不测源码：Web 测构建产物跑起来的服务，客户端测安装后的实例。
3. 阻塞清零才准交付：A/B 阻塞项任一未清零，或报告缺失 → UI 验收未闭环 → 禁止进入交付（铁律⑤）。

B 部分的配色人体工学要点（最容易被忽略的一组）

• 不用纯黑配纯白（#000+#fff 眩光）；深色模式用近黑近白（如底 #12141a / 字 #e8eaed）
• 高饱和色不铺大面积（建议 ≤20% 视口），只用于强调
• 深色背景下避免小号蓝/紫字（短波长色差像差导致边缘发虚）
• 红绿不作为唯一区分（男性红绿色盲约 8%），颜色 + 图标/文字双编码
• 无 >3Hz 闪烁；动效 200–300ms，支持 prefers-reduced-motion

测试用例库（铁律③的落地，T2 起强制）

> 详细规范读 references/11-test-case-library.md，执行清单读 references/04-function-test-checklist.md。

三个核心机制：

1. 用例是资产，不是一次性清单。 每条用例有稳定 ID（TC-<模块>-<序号>）、优先级、引入版本、状态（active/deprecated）。写一次，后续每个版本复用。
2. 版本累积继承。 升版时把上一版 testcases/ 整目录复制到新版，标记"继承"；本版新增用例追加，变更用例保留旧的标 deprecated + 新增替代用例（不原地改写，保留追溯）。00-cumulative-matrix.md 记录：继承 N 条 / 新增 M 条 / 修改 K 条 / 废弃 J 条 / 合计。
3. 冒烟套件 = 用例库的子集。 从 active 用例中挑 P0 happy path 标 smoke: Y，抽成 01-smoke-suite.md。冒烟套件随版本同步膨胀——上版冒烟用例全部保留，本版新增 P0 补入。跑一遍冒烟 = 快速确认新老主链路都没坏。

因此：跑当前版本测试 = 冒烟 + 全量回归，无需单独设计回归测试。

版本控制规则（git，T1 起通用）

总原则：一切版本控制操作（init / commit / tag）默认都要过用户门禁——先向用户说明拟做什么、为什么，用户同意后才执行；用户拒绝或不回应时跳过，在汇报中注明。项目没有版本控制时不擅自引入，除非用户明确要求。

编码前检查（写任何代码前必做）

1. 检查项目是否有版本控制（.git 目录 / git rev-parse）。
2. 无版本控制：直接继续开发，汇报中注明。不主动询问、不擅自初始化——仅用户明确要求时执行 git init + .gitignore + 首次提交（信息须经用户确认）。
3. 有版本控制，两项检查：
   - git status 有未提交内容 → 报告改动清单，由用户决定是否提交、如何拆分；
   - git tag 对照 docs 版本文件夹，缺 tag → 报告，是否补打由用户确认。
   - 全部处理完毕才允许写代码。

tag 与文档版本对应（硬性）

tag 命名 = 文档版本号：大版本 v1.0、小修订 v1.0.1。一套 docs/vX.X 对应同名 tag，禁止出现"文档已到 v1.2 而仓库没有对应 tag"。

交付后收尾

交付完成、用户确认后，提交收尾方案：改动清单 + commit message 草稿 + 拟打 tag 名（与文档版本一致），经用户同意后执行，随后汇报 commit 与 tag 名。

T1 执行细则：微改动

核心：读图 → 说清 → 改 → 验 → 报。零确认门禁，不读 references 下任何文件（本档流程自足）。只有三种情况停下来问：① 会删除/覆盖用户数据或破坏现有功能；② 多种差异巨大的方案且选错代价高；③ 版本控制需要用户决策。

1. 读图（铁律⑥）：项目有 docs/ 时，先读 PROJECT-MAP.md + PROJECT-OVERVIEW.md + CHANGELOG.md 顶部，按图定位改动点；不扫全量目录与代码。项目没有三件套时不补建（T2 起才建），但本次若改动了目录结构，收尾时补一份 MAP。
2. 说明：动手前 2~3 句话写清改什么、为什么、影响哪些模块。
3. 定位与修改：先做版本控制检查，通过后直接改。公共接口注释随代码同步。
4. 验证：修改点验证（必做）+ 就近关联验证（必做，≤5 项，不落盘）。涉及可见 UI → 加做 UI 最小集：真实打开改动页 → 本页可点元素逐个点一遍 → 无乱码 → 正文对比度达标 → 无控制台报错。
5. 文档同步：项目有 docs 体系时，行为/契约变了 → 修订受影响文档 + 升小版本 + 变更记录追加一行；纯 bug 修复或样式微调 → 只升小版本 + 追加变更记录；文案标点级 → 不动文档。一律只升小版本（铁律②）。收尾按更新触发点表同步三件套（至少 CHANGELOG 一行；结构/模块变动时同步 MAP 与 OVERVIEW）。
6. 交付：涉及可运行产物时重新构建打包后交付。

汇报格式（几行内）：改了什么（文件+一句话）｜验证结果｜文档同步｜交付物路径｜风险（没有就不写）。

T2 执行细则：单点功能

在 T1 基础上增加三件事：精简设计说明、用例库更新、含 UI 时的 UI 验收。

0. 读图（铁律⑥）：项目有 docs/ 时按 SOP 读三件套；没有则本次建立（MAP 从当前目录生成 + 人工校正，OVERVIEW 只写当前状态，CHANGELOG 从本次开始记并注明"此前无文档记录"）。

1. 精简设计说明（铁律①）：动手前写清——改动范围、影响模块、接口/数据结构变化、明确不做什么。项目有 docs/vX.X/ 时追加到 CHANGELOG.md 与 00-release-goal.md；没有则对话内说明。

2. 编码：先做版本控制检查。严格按说明实现，偏离即走"缺陷回溯"。
3. 用例库更新（铁律③）：
   - 从上一版 testcases/ 复制继承（首次建立则新建）；
   - 为本次功能新增用例（正常路径 + 关键边界 + 异常）；
   - 更新 00-cumulative-matrix.md 与 01-smoke-suite.md（本次新增的 P0 补入冒烟套件）。
4. 测试执行：冒烟套件全跑（含继承的上版用例）→ 本模块详测 → 受影响功能回归。
5. UI 验收（交付物含页面时强制）：改动页 + 上下游一跳执行 A 页面交互功能测试与 B UI 设计检查，产出 06-ui-test-report.md 与 06b-ui-design-report.md；阻塞项清零才继续。
6. 文档同步 + 交付：同 T1（含按触发点表更新三件套），版本号只升小版本。

T3 / T4 执行细则：完整流程

核心：文档先行、原型先确认、接口有契约、用例可累积、缺陷可回溯、测透再交、交付即用。每阶段有产出物与门禁，上一阶段未过门禁不得进入下一阶段（铁律⑤）。

T3 允许裁剪：可将阶段一至三合并为一份精简设计文档、原型精简为单个 index.html，但必须动手前向用户说明并征得同意。阶段零在 T3 可做 30 分钟加速版，T4 必须完整。T4 额外强制用户验收（UAT）。

缺陷回溯与修复

• 任何阶段发现上游设计缺陷：定位文档 → 修正 → 变更记录追加一行 → 同步其他受影响文档 → 告知用户 → 继续。回溯是正常环节，不视为返工失败。
• 禁止代码与文档静默分叉：宁可暂停编码修文档，不允许实现偏离已确认设计。
• 每次修复三件事：① 同步修订文档并升小版本；② 三层回测（修改点 + 关联回归 + 核心流程整体回归）；③ 汇报改了什么、同步了哪些文档及版本号、回测结果。

阶段零：调研（开源项目 + 网络资料）

1. 读 references/00-opensource-research-template.md。
2. 多渠道检索（中英文各一轮），不局限于 GitHub：开源实现（GitHub/Gitee/npm/PyPI）、架构与设计资料（官方文档 Architecture 章节、InfoQ/掘金/Medium/公司技术博客）、产品与交互参考（ProductHunt、官网帮助文档）。
3. 评估：开源项目看 star 增长、维护时间、license、技术栈匹配、文档质量；架构资料看来源权威性、规模匹配度、是否生产验证。
4. 结论三选一：直接使用 / 借鉴设计（注明出处）/ 确认自研。有高分项目或成熟架构方案时优先借鉴。
5. 产出 docs/vX.X/01-research.md。门禁：用户确认调研结论。

阶段一：产品文档（PRD）

读 references/01-prd-template.md，写清目标用户与场景、核心问题、功能清单（P0/P1/P2）、不做的范围、成功指标。信息不足先列假设并标注，或提问关键缺口（≤3 个）。产出 02-prd.md。门禁：用户确认 PRD 要点。

阶段二：交互文档

读 references/02-interaction-template.md 与 references/07-design-guidelines.md。基于 P0/P1 产出页面清单、主流程图、每页元素与五态（默认/加载/空/错误/成功）、关键交互规则，写明设计 token。产出 03-interaction.md。门禁：用户确认交互流程。

阶段二·五：HTML 交互原型

读 references/09-ui-prototype-guidelines.md，参考 assets/example-prototype.html。token 1:1 转写为 :root CSS 变量，产出 prototype/：总览 index.html + 每页独立 HTML。硬性要求：纯静态单文件零依赖、样式全引用 token 变量、每页内置五态切换器、真实感中文假数据、移动端套 375px 设备壳、页面间可跳转、不写真实业务逻辑。

门禁：用 present_files 打开原型，必须附提醒话术——「这是开发前最后一道视觉确认关。现在改配色/布局/交互只要几分钟；等代码写完再改，成本翻好几倍还容易改漏。请重点过一遍：① 总览页配色字号；② 每页五种状态（点状态切换器）；③ 主流程从头点到尾。确认后这份原型就是编码基准，后面 UI 会逐页比对。」

用户提修改：改原型 → token/交互规则有变时同步修订 03-interaction.md（升小版本）→ 再次呈现。确认后原型冻结为视觉基准，才进入阶段三。

阶段三：系统设计

读 references/03-system-design-template.md。产出技术选型与理由、架构分层、模块划分、数据模型、接口定义（路径/入参/出参/错误码）、非功能设计。每个接口与 Service 方法写清"职责一句话 + 输入 + 输出 + 错误场景"。产出 04-system-design.md。门禁：用户确认技术方案——编码前最后文档门禁，确认前禁止写任何代码（铁律①）。

阶段四：编码

1. 编码前执行版本控制检查（同前）。
2. 用 TaskCreate 按模块拆分，一模块一任务。
3. 严格按文档实现，触发设计缺陷走"缺陷回溯"。
4. 每个对外接口与 Service 公共方法必须带注释（职责/参数/返回值/错误；复杂逻辑写"为什么"）。
5. UI 对照已冻结原型 1:1 还原；因技术限制确需偏离的，汇报中逐项说明。
6. 每完成一个模块自测主路径跑通再标记完成。完成后汇报功能清单、与文档的偏差及原因、回溯记录。

阶段五：功能测试（冒烟 + 详测 + 验收）

执行顺序固定：先冒烟 → 再详测 → 后验收。读 references/04-function-test-checklist.md，用例库规范读 references/11-test-case-library.md。

1. 先冒烟：跑 testcases/01-smoke-suite.md 全量（已含上版继承的 P0 用例）。任一失败立即打回编码，修复后重跑；冒烟全绿前禁止展开详测。
2. 累积回归（铁律③）：当前版本用例库已继承上版全部 active 用例，逐条执行即为回归。关联影响分析用于识别需要加深测试的区域，不用于裁剪范围。
3. 再详测：对照 PRD 与用例库逐项验证正常路径、边界、异常、错误处理、数据一致性、接口契约、端到端与交叉场景。能自动化写自动化，不能则手动逐项记录。
4. 缺陷记录复现步骤、预期/实际、级别（阻塞/严重/一般/建议）；阻塞与严重修复后重测，所有修复执行三层回测。
5. 后验收：准入自查 → 准出标准核对 → 用户验收 UAT（T4 强制，T3 建议）：提供可运行产物 + 5~10 步走查路径，用户实际点一遍并明确确认。
6. 产出 docs/vX.X/05-function-test-report.md。门禁：冒烟全绿 + P0 全过 + 累积用例全过 + 阻塞/严重清零 + （T4）用户验收确认。

阶段六 A：页面交互功能测试（真实操作，强制）

读 references/05 第 0 节与 references/15。必须真实打开页面逐个点击——读代码不算测。逐页七步：打开 → 列可点元素 → 逐个点击并记录实际结果 → 表单 → 五态切换 → 抓控制台/网络 → 截图。对照交互文档验证元素与流程，同时逐页与已冻结 HTML 原型比对，有偏差即记缺陷。产出 06-ui-test-report.md（含逐页点击清单表）。

门禁：全量页面点击清单无一"点了没反应"；控制台零 error、资源无 404；阻塞/严重缺陷清零。未实跑的必须在报告标注并列入遗留清单。

阶段六 B：UI 设计检查（强制）

读 references/16。用截图 + 眯眼测试 + 灰度化 + 深浅色 + 放大/窄屏五种方法，查八个维度：文本与编码（乱码/占位符）、可读性（字号行高/对比度）、配色人体工学（纯黑纯白眩光/高饱和铺底/深底蓝紫小字/红绿单编码/闪烁）、空间密度、视觉层级、可点热区、token 一致性、响应式。产出 06b-ui-design-report.md。

门禁：阻塞项清零（乱码、正文对比度不达标、主 CTA 点不到、破版遮挡关键信息均属阻塞）；严重项排期并写入遗留清单。

> A 与 B 是同一道 UI 验收的两半：A 管"能不能用"，B 管"看得清、看得舒服、点得到"。两者都通过才进入阶段七。

阶段七：人机交互合理性校验

读 references/06-ux-review-checklist.md。站在真实用户视角走查学习成本、操作路径、文案清晰度、一致性、容错性、防呆。区分"缺陷"（必须修）与"改进建议"（列优先级由用户决定）。产出 07-ux-review-report.md 并做最终总结。

阶段八：交付打包（铁律④）

读 references/08-delivery-checklist.md。

1. 交付前核验四环节闭环（铁律⑤）：文档已确认且与实现一致 ✓ 编码完成 ✓ 测试报告通过（含累积回归与 UAT）✓ —— 缺任一项，回去补齐。另加两项硬性核验：UI 验收已闭环（有页面时：A/B 两份报告齐备且阻塞清零）✓、全局三件套已按触发点更新 ✓（铁律⑥）。
2. 按项目类型打包成用户可直接使用的产物，不允许只给源码。
3. 版本判定复核：满足铁律②大版本条件且用户确认 → 新建大版本文件夹（testcases 整目录复制）；否则只升小版本。
4. 交付物：构建产物 + 快速开始说明 + 对应文档版本号 + 遗留问题清单。用 present_files 一次性交付。
5. 交付后收尾：按版本控制规则提交收尾方案，经用户同意后执行提交与打 tag。

阶段跳转

禁止跳阶段。用户明确要求跳过时（阶段零只可加速），确认后跳过并在产出物中注明。回溯修正上游文档不视为跳阶段。

反模式与 FAQ

反模式（对照自查）

FAQ

Q1：怎么快速定档？
看三件事：改几个文件、有没有设计取舍、要不要新增页面/接口。单文件无取舍 = T1；≤3 文件有小取舍 = T2；≥4 文件或有架构取舍 = T3；从零或整体重构 = T4。拿不准就升一档并说明理由。

Q2：老项目没有 docs 体系，还要建用例库吗？
T2 起要。从本次改动开始建 docs/v1.0/testcases/，不必补写历史文档。老功能的用例可以在后续迭代中逐步补录——每次改到某模块就补该模块的用例，几个版本后自然覆盖完整。

Q3：用例越积越多，跑一遍太慢怎么办？
分层执行：冒烟套件（P0，分钟级）每次必跑；全量用例每个版本至少跑一次；执行报告里记录本版"继承/新增/修改/废弃"数量，便于评估膨胀速度。用例库按模块拆文件，只跑受影响模块是允许的，但版本发布前必须全量跑一次。

Q4：用户催得急，能不能先写代码后补文档？
不能，铁律①明确禁止。折中：把文档压缩到最小可确认粒度（几段话说清方案和接口），确认后立即编码——省篇幅，不省确认环节。

Q5：升大版本还是小版本拿不准？
一律升小版本。只有"UI 大规模改版"或"功能大规模升级"两种情形才考虑大版本，且须先说明理由并获确认。

Q6：T0 真的什么都不用做吗？
对。T0 不产出需交付的代码，走流程是纯粹的过度仪式化——SDD 最大的敌人不是文档质量，是"不该用的时候用了"。

Q7：references 这么多都要读吗？
不用。T0/T1 一个都不读；T2 读 11-test-case-library.md + 04-function-test-checklist.md；T3/T4 执行到某阶段才读对应文件。

Q8：v1.0 的"模式 A / 模式 B"和现在的 T0–T4 是什么关系？
语义映射：模式 B → 拆成 T1（微改动，原 B 的轻量部分）与 T2（单点功能，原 B 的重量部分，新增用例库要求）；模式 A → 拆成 T3（中大型功能，可裁剪）与 T4（从零项目，强制 UAT）；新增 T0 表示不触发流程。旧说法仍可理解，执行时按 T 档走。

Q9：老项目没有三件套，要不要把历史补全？
不补。铁律⑥要求的是"从现在起有地图"，不是"补写历史"。MAP 从当前目录扫描生成后人工校正，OVERVIEW 只写当前状态，CHANGELOG 从本次开始记并注明"此前无文档记录"。历史精度不影响当下使用——但当前状态必须准确。

Q10：项目没有 UI（纯后端 / 脚本 / 文档型 skill），UI 验收怎么办？
不适用，在交付清单里勾"不适用"并写一句理由即可。判定标准是交付物里有没有能打开的页面：HTML 原型也算（原型是设计基准，同样要能点、能看、无乱码）；纯 API/CLI/库/文档则不适用。

Q11：地图会不会越写越大，反而费 token？
有三道闸：① MAP 只列到二级目录 + 一句话职责；② 体量上限 MAP ≤200 行 / OVERVIEW ≤150 行，超了就瘦身（MAP 砍到二级，OVERVIEW 只留当前状态）；③ CHANGELOG 只看顶部两段，超过 200 行按年归档。三份合计通常 <10KB，一次读完远小于扫一遍项目的成本。

Resources

references 与 assets 仅供 T2 及以上按需读取；T0/T1 不读。

references/

> T1 的 UI 最小集与读图步骤已内联在本文档对应档位细则中，T1 不需要读 references（本档流程自足）。

assets/

• example-prototype.html — 示例原型（阶段二·五参考）

变更记录