分阶段功能交付

将一个需求拆成可独立验收、可独立提交的阶段。每次只执行当前阶段；默认在用户自测、确认并提交后进入下一阶段。用户明确接受具体未验证项或失败风险时，按“验收证据与放行”处理，不得将放行写成测试通过。已有项目默认采用“增量迭代”模式，不重复搭建项目基础设施，也不把无关重构混入当前阶段。

触发确认与退出

• 用户已经明确要求分阶段开发、逐阶段验收、用户自测后继续或每阶段独立提交时，直接启动本流程，不重复询问。
• 用户的提示词或意图已经触发本 Skill，但是否采用分阶段交付仍不明确时，只询问一次是否启用本流程。用户确认后继续；用户拒绝后立即退出本 Skill，按普通开发流程处理，且不再重复询问。
• 不得仅因功能规模较大而自动触发本 Skill，也不得把“先做计划”“检查提交”等单一表达直接等同于用户已经要求分阶段交付。

授权解释

• 本 Skill 的开发门禁仅用于实际分阶段开发；用户分析、审查或修改 Skill 本身时，不启动阶段交付流程。
• 一次明确回复可以同时确认模式、计划和指定阶段启动；已经满足的授权不得重复询问。启用流程本身不等于批准尚未展示的实施计划。
• “采用单阶段方案，开始吧”同时确认已展示的方案并授权该阶段；“计划可以，开始第一阶段”授权第一阶段；“计划可以，暂时别做”只确认计划。
• “验收通过，已提交，继续第二阶段”表示验收确认并授权第二阶段，仍需核对提交证据。仅“继续”不能证明执行过自测或完成了提交。

先确定交付模式

• 已有项目迭代（默认）：先读取项目规则、当前规格/计划、相关调用链和工作区状态；复用已有目录、组件、接口层、状态管理和测试约定，只补本次需求所需的计划与记录。
• 新项目或基础设施变更：只有需求确实涉及新项目、技术栈切换、跨模块架构调整或质量基础设施时，才增加架构、脚手架、CI 等阶段。
• 快速修补：文案、样式、单点校验等低风险改动可走快速通道，但仍需给出验证结果、自测路线、commit 描述并暂停等待用户确认。

模式选择写入规格或对话记录；不确定时按已有项目迭代处理，不凭空创建新基础设施。

项目约定优先门禁

在新增目录、分层、共享状态/数据层、Service、API 模块或模块组织方式前，必须先完成一次项目结构检索：

1. 读取项目级 AGENTS.md、架构文档和编码约定；
2. 搜索同业务域及相邻业务域的同类实现，确认现有目录、命名和依赖方向；
3. 在规格或对话计划中记录“复用位置、未复用原因、拟新增位置和职责边界”。

默认复用项目已有模式。仅凭通用经验、个人偏好或其他项目的结构，不得新建目录或引入新的分层。项目没有明确模式时，优先选择最接近的既有实现；完全找不到可复用模式时，先向用户说明候选方案和影响，得到确认后再创建。

该门禁是跨项目通用流程，不要求每个项目重复添加同一条规则；项目级文档只负责提供该项目自己的目录和依赖约定。

启动流程

1. 读取项目级 AGENTS.md、已有规格、测试约定、相关代码和当前 Git 状态。
2. 从现有上下文明确需求目标、非目标、关键交互、数据边界和验收标准；已有明确答案不重复询问，存在实质歧义时一次只问一个问题。
3. 在写生产代码前，完成“项目约定优先门禁”；按项目规则决定是否落盘。需要跨会话、用户明确要求留档或已有流程要求时，优先复用项目已有的规格和测试记录目录；项目没有约定时，创建需求总览 .spec/active/YYYY-MM-DD-<feature-slug>.md，再按 记录规范 为当前阶段创建独立规格与测试记录。项目明确采用对话内计划时，不强行新增文件，但必须在对话中维护同等信息。
4. 把实现拆成有依赖顺序的阶段。每个阶段应构成一个可独立理解、验证和提交的变更单元，原则上对应一个 commit。
5. 向用户展示计划并等待明确确认。确认前不实现生产代码；确认同时包含阶段启动要求时，直接进入指定阶段。

记录管理

• 开始流程时确定记录载体（文件或对话）；本 Skill 中的“规格、测试记录、总览、回写”均指该载体，不因后续章节要求而强制切换。
• 采用文件记录时，创建、拆分或归档前读取 记录规范。普通多阶段需求使用总览索引、阶段规格和阶段测试；快速通道见下文。
• 优先复用项目目录；无约定时规格使用 .spec/active/，人工测试记录使用 .spec/tests/。复用已有文件名，不机械重命名历史记录。
• 先更新记录再交付；返修分类、提交核对、进度与归档分别遵循对应章节，不复制另一套政策。

规格中的进度结构

规格必须包含实施进度区，并按阶段维护任务级复选框。每个阶段至少分别记录：

• 实现任务；
• 自动或静态验证；
• 用户自测（执行情况、反馈或明确的用户陈述）；
• 用户确认（验收结论）；
• commit 状态（经核对的 hash 与标题）；
• 风险接受（存在时单独记录具体项目、影响和用户原话）。

已完成事项标记 [x]，未完成事项保留 [ ]。按已取得的证据更新，代码完成、Git 提交或要求继续都不能代替用户自测证据。

验收证据与放行

• 默认阶段验收与提交收口要求：必要验证完成、用户自测通过、用户确认、阶段提交核对通过。
• 启动下一阶段时，除上一阶段已按默认条件或风险接受政策收口外，还需用户明确授权进入该阶段。最后一个阶段收口后直接进行最终一致性检查，不要求用户授权不存在的下一阶段。
• 用户明确陈述已按路线自测或提供自测结果时，可记录用户自测完成；“验收通过”可记录确认，但未说明自测执行情况时，不能直接勾选自测。
• 存在未验证项或新增失败时，先说明具体项目、影响和后续验证/修复安排。只有用户明确接受这些风险并确认当前阶段结果，才能例外收口；启动下一阶段另需明确继续授权。沉默、提交或笼统“继续”均不构成风险接受。
• 放行不改变测试结果和自测复选框，只单独记录用户接受风险、验收结论，以及存在下一阶段时的继续授权。阶段提交核对要求仍然保留。
• 有未验证项或失败风险接受的需求，只能标为“交付完成（附未验证项/已知失败）”；后续补齐验证或修复后才可标为“全部验收通过”。

轻量需求快速通道

当改动范围小、风险低、验收结果单一，且不涉及新增接口契约、数据迁移、跨模块状态、新依赖或敏感操作时，可以在计划中合并为一个阶段。在计划中说明快速通道判断依据，随计划一并确认，不单独增加一次询问。

快速通道允许将目标、变更、验证结果、自测路线和进度写入一份简短记录，沿用已确定的文件或对话载体，不强制另建阶段测试文件。自测只包含适用场景；例如纯按钮文案修改检查显示、布局和原点击行为，不编造失败输入场景。简单改动不强制统计结构指标，但保留必要验证、用户验收、commit 描述、提交核对和明确暂停。只要改动出现跨模块影响、复杂状态、外部副作用或难以独立回退，就恢复普通分阶段流程。

阶段执行门禁

1. 开始阶段前，按“授权解释”确认已有阶段启动授权；记录阶段起始 HEAD（无提交时注明）、分支、工作区及暂存区已有改动。
2. 修改前采集验证基线：运行与阶段风险匹配的相关检查，记录命令、环境、结果和已有失败。已有结果仅在对应代码版本、环境和检查范围仍适用时复用。无法取得基线时标记“基线未知”，修改后的首次运行不能倒推为基线；不为取基线擅自清理、覆盖用户改动或切换工作区。
3. 只做当前阶段目标所需的最小变更，不提前实现后续阶段。预列文件清单是预计范围；根因涉及共享 helper、类型或调用方时，检查所有调用方并更新实际文件清单与回归范围。改变其他业务行为或扩大需求边界时，按“需求变更处理”重新确认。
4. 复用项目既有组件、工具、接口层和约定；不猜测缺失的服务端 URL、method、字段或错误码。
5. 实现完成后执行与风险匹配的类型检查、lint、测试、构建或浏览器验证。失败时只修当前阶段，并记录真实阻塞项。
6. 按“阶段完成闭环”更新对应记录并交付，按“验收证据与放行”等待用户处理；不得默认推进下一阶段。

接口契约门禁

涉及接口时，在实现前读取用户指定或项目约定的最新接口文档，并逐项核对：请求路径与方法、请求字段、响应字段、枚举/单位、版本字段、错误处理和权限。最新契约优先于旧代码、旧测试和猜测；文档没有的字段不得自行补造。

阶段规格中必须记录接口映射表和未具备条件（例如服务端未部署、权限未开通），需求总览只保留接口状态摘要和阶段链接。接口响应为空、业务无数据和请求失败要分别处理；错误提示只保留一条明确来源，避免服务端错误与前端手动提示重复弹出。契约变更必须同步更新类型、适配器、调用方和阶段测试记录。

阶段完成闭环

阶段交付不是“代码写完”就完成，必须按以下顺序收口：

1. 对比验证结果：使用修改前的基线判断失败来源；基线未知时保留不确定性，按下文验证结果分类处理，不推定为既有失败。
2. 先同步记录再交付：更新实现边界、遗留问题、验证结果、自测路线和阶段索引；用户自测、确认及提交只按已有证据勾选。
3. 提交前核对：用户准备提交或已暂存时，按“Git 边界”检查暂存内容，提供检查摘要；已有失败不能隐藏，无关改动不擅自处理。
4. 提交后核对和回写：按“Git 边界”定位实际阶段提交，再更新 hash、标题及提交状态；不得直接把最新提交当作阶段提交。
5. 进入下一阶段：按“验收证据与放行”分别核对自测、确认、风险接受、提交和继续授权，先回写上一阶段状态，再开始下一阶段；缺少必要条件时说明具体缺项并暂停。
6. 最终一致性检查：按“完成与归档”核对整体事实与结果，不将风险接受写成全部通过。

项目已有适用测试框架时，非平凡纯逻辑、状态转换、边界校验和错误恢复应优先增加或更新自动化测试。若不适合自动化测试，应记录具体原因和替代验证。项目没有测试框架时，使用最小可运行断言或自检；不得仅为当前需求擅自引入测试框架、测试依赖或大批 fixtures。

验证结果按每个检查项分别记录，汇总不得隐藏部分失败或未执行项：

• 通过：该检查项本次实际运行通过；基线失败已修复时注明修复情况。其他检查项的失败仍单独保留。
• 既有失败：基线中已经存在，本阶段未新增或扩大影响；记录原始错误和未处理原因。
• 新增失败：本阶段引入或扩大影响；默认阻塞阶段验收，先修复并复测。无法修复时报告阻塞项；例外放行仅按“验收证据与放行”处理，结果仍记为失败。
• 来源未确认的失败：基线未知或证据不足，不能判定既有/新增；记录原因与定位安排，默认阻塞验收，例外放行同上。
• 未执行/未验证：记录缺少的环境、权限、依赖或其他具体原因，不记为通过；影响验收标准的项目默认阻塞验收，例外放行同上。

不得只因为“相关测试命令执行过”就把整组测试写成通过。对无法稳定运行的测试，记录失败发生在收集、初始化还是断言阶段，并说明是否覆盖到业务行为。

用户自测默认使用项目已有的真实业务入口，并按项目形态选择验证方式：前端使用页面或交互入口，后端使用接口、任务、消息、数据库状态或日志，客户端使用设备行为、本地数据或生命周期场景，CLI/脚本使用命令行输入输出和退出码。若接口、权限或环境尚未具备，导致部分路径无法在当前入口触发，应如实列为未验证项并放入后续联调阶段；不得自行创建专用自测页面、开发路由、Mock 控件、中间件例外或临时验证入口。只有用户明确要求增加验证工具时，才能另行设计并实施。

用户自测反馈按“用户反馈与返修”分类、回写和复验，不得只口头回复“已修改”。

Bug 修复归档规则

• 当前阶段尚未提交时，多个 Bug 纳入当前阶段规格和测试记录，统一修复、统一复测，并随当前阶段一起提交。
• 当前阶段已经提交时，同一阶段、同一轮验收发现的多个实现缺陷合并为一个修复批次，创建一份修正规格和一份修复测试记录，并使用一个独立的 fix commit。
• Bug 如果实际属于新需求、范围变化或新的阶段目标，不并入修复批次，按需求变更重新规划阶段。

代码结构与数据生命周期门禁

涉及复杂模块、共享数据或异步流程时，在编码前读取 结构与生命周期审查，记录职责、数据权威来源、生命周期和拆分判断；交付前核对实际实现。简单文案、样式等改动无需机械统计。数量指标只作为预警，不作为质量结论，不据此强制新增分层。

每阶段固定交付格式

普通阶段结束时提供以下内容；快速通道可合并为简短交付，但保留适用信息。内容应只描述当前阶段，不把后续计划或未验证结果写成已完成：

1. 变更总结

• 做了什么；
• 未做什么；
• 涉及文件；
• 遗留风险或后续依赖。

2. 验证结果

列出实际执行的命令或检查、通过/失败结果，以及未执行项目和原因。不得把代码审查或静态推断表述成真实浏览器验证。

3. 用户自测路线

必须可直接执行，并包含：

• 现有真实业务入口（页面、接口、任务、设备场景或命令行入口，按项目形态选择）；
• 前置条件；
• 明确且安全的测试数据；
• 编号操作步骤；
• 每一步对应的可见预期结果；
• 根据实际行为覆盖适用的成功、普通失败、边界输入、重复操作、关闭重开和受影响区域回归；影响验收但无法验证的场景标为未验证。无需为不适用场景编造步骤，存在歧义时简述排除理由。

涉及真实短信、付款、删除、权限或其他外部副作用时，只描述安全的手工步骤和风险；无法安全执行的项目明确留待合适环境验证，不自行建设 Mock 页面。

4. 建议 commit 描述

根据仓库历史和项目约定提供可直接使用的 commit 标题与正文摘要。优先遵循仓库已有提交格式；仓库没有明确规范时，可以推荐 Conventional Commit。示例：

用途： 提供当前阶段实际变更的提交标题与正文示例。

feat: 完成某功能的当前阶段

- 实现……
- 增加……
- 同步规格与测试记录

标题描述当前阶段形成的结果，不写笼统的“更新代码”。正文只包含本阶段实际变更。

5. 明确暂停

说明当前阶段等待的具体事项，下一阶段按“验收证据与放行”启动；未满足条件不得继续。

6. 提交前检查摘要

用户表示准备提交或已暂存时，补充当前阶段的提交边界检查：变更文件、暂存文件、未包含的无关改动、验证命令和已知风险。采用文件记录时，本阶段规格、测试记录和代码应一并提交；快速通道使用合并记录，对话记录不要求新增文件。Git 操作、提交识别与提交后回写遵循“Git 边界”。

Git 边界

• 默认不执行 git add、git commit、git commit --amend、push 或历史重写。
• 用户负责暂存和提交。只有用户明确授权相应操作与范围时才执行；此前明确且仍适用的授权有效，不因消息轮次要求重复授权。修改代码或要求继续阶段本身不授权 Git 写操作。
• 用户要求暂存时，只暂存其明确指定的阶段文件，并核对暂存区清单。
• 提交前读取 git status --short、git diff --cached --stat、git diff --cached --name-only 和完整 staged diff；核对当前阶段内容、记录及文件内混入的无关改动。允许包含已说明的前阶段 hash 回写，不允许混入其他功能；无关改动只提醒用户处理。
• 用户要求提交时，按上述核对后使用已给出的 commit 描述；不跳过 hooks。
• 用户提交后，优先核对其指定的 hash；未指定时，从阶段起始 HEAD 之后的历史中定位阶段提交（起始无提交时从根提交核对），不能默认采用最新提交。读取实际 hash、标题、diff，并与阶段目标、起始已有改动及当前工作区残留核对；文件清单不能证明内容完整。
• 出现额外无关提交时可跳过并说明；阶段内容被拆成多个提交、混入其他需求、无法定位，或起始提交已因历史变更不可用时，报告边界异常并等待用户确认，不自动重写历史。
• 阶段内可以多轮修复，但最终应归入该阶段的一个 commit。无文件变化时不创建空 commit。
• 阶段提交后补写 hash 属于新的文档变更，不宣称已包含在原功能 commit 中。默认可随下一阶段的记录提交纳入，明确注明前阶段回写；最后阶段统一形成文档收尾提交，或按用户要求单独提交。
• 只追踪阶段功能提交和修复提交的 hash；记录更新提交不要求再回写自身 hash，避免递归追加文档提交。未提交的记录更新如实列为待提交，不标记记录已经落地。
• 阶段提交后的代码修正按“Bug 修复归档规则”使用独立修复提交。除非用户明确要求，不使用 commit --amend 将新内容塞回原阶段 commit。

用户反馈与返修

用户在验收中报告问题时：

1. 暂停进入下一阶段，依据反馈证据判断需求变更、实现缺陷、环境问题或服务端问题；证据不足时明确待定位，不把所有反馈直接当作实现缺陷；
2. 实现缺陷按“阶段执行门禁”的目标边界定位共享根因并检查调用方，按“Bug 修复归档规则”选择当前阶段返修或提交后修复批次；需求变化按“需求变更处理”处理，环境/服务端问题记录依赖及责任边界；
3. 更新对应规格、测试记录与总览，重新打开受影响的验证和验收状态，保留既有历史结果；
4. 修复后重新验证，给出完整且适用的自测路线和更新后的 commit 描述；
5. 按“验收证据与放行”再次等待用户处理。

反馈涉及已确认阶段边界时，先暂停并说明影响；未经用户确认修订后的阶段计划，不擅自扩大改动范围。

需求变更处理

用户在实施过程中新增、撤回或修改需求时，先判断影响范围，再继续工作：

1. 只影响当前未提交阶段的调整，纳入当前阶段返修，并同步阶段规格、阶段测试记录、总览状态和自测路线；
2. 只影响尚未开始阶段的调整，更新剩余计划，不改写已经确认的历史结果；
3. 影响已确认但未提交阶段、阶段边界或整体方案的实质变化，明确列出受影响内容，重新打开相关阶段，并等待用户确认修订后的剩余计划；已提交阶段发生独立调整时新建带实际日期的补充修正规格与测试记录，并使用独立 commit；
4. 需求变化导致当前阶段不再能独立验证或提交时，重新拆分或合并阶段，并说明新的 commit 边界。

已完成记录用于保留真实过程，不因后续变化直接改成“从未完成”。被新需求推翻的事项应标记为已完成后变更，并链接或说明替代阶段。

完成与归档

• 所有阶段收口后核对：总览索引、阶段实现、验证结果、用户自测证据、确认/风险接受、实际功能/修复 commit 和工作区残留。无关工作区改动列明即可，不要求工作区完全干净；相关代码遗漏或边界异常不能标为完成。
• 按“验收证据与放行”区分“全部验收通过”和“交付完成（附未验证项/已知失败）”。记录回写尚未提交时注明“记录待提交”；代码与记录均落地后才标记整个流程完结。
• 全部阶段按默认验收条件收口，或用户明确接受剩余未验证项/已知失败并确认需求收口，且相关代码、记录均提交后，主动说明准确的完成状态，并询问用户是否归档；用户确认后执行。带风险归档不代表风险已消除，必须保留未验证项、已知失败、用户接受依据和后续处理安排。此前已有明确且仍适用的“完成后自动归档”授权时，无需再次询问是否归档。用户拒绝归档后保留原位置并标记完成，不重复询问；尚未回复时不移动文件。
• 归档前读取项目约定并检索已有归档目录及历史记录。归档位置明确且一致时按约定执行；没有约定、存在多个候选位置或规则与实际目录不一致时，说明现状、推荐位置及影响，让用户选择，确认前不创建目录或移动记录。已有自动归档授权不等于授权任意新归档位置。
• 无明确约定时，优先推荐当前规格目录同层级的归档位置，例如 docs/features/active/ 对应 docs/features/archive/；不自动切换到 .spec/archive/。是否归档与位置选择可以合并询问；测试记录的保留或移动范围一并说明。仅有对话记录时不创建归档目录，直接保留完成状态。
• 移动前确认关联文件范围，移动后更新总览、阶段、修复和测试记录之间受影响的相对链接及项目索引，并检查链接目标存在。归档细则见 记录规范。
• 归档和最终文档收尾均遵守“Git 边界”，不替用户默认暂存或提交。