hotline-tdd · git:20261026.24dfdd6 · 2026-10-26 · sha256 33a79c5b32968034
hotline-tdd git:20261026.24dfdd6A
Immutable. This exact content never changes and is served at /api/v1/blob/33a79c5b32968034.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_sbs7huw7dxzi7sca/33a79c5b3296803460f3407e5c41a7fadb284faba33c88d0cab93ec41b1b8a54.json
Then /plugin install hotline-tdd@markdownregistry-sbs7huw7dxzi7sca in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: hotline-tdd description: Use when implementing or fixing behavior in Hotline and you need to clarify acceptance criteria, choose the repository's real checks, or retry only the affected scope. --- # Hotline TDD ## 目的 本 Skill 将 Hotline 的需求澄清、规格确认、TDD、最小范围重试和交付评审串成一个可验证流程。它补充 Superpowers 的 `test-driven-development`,不替代仓库根目录 `AGENTS.md` 中的规则。 **核心原则:** 每个新行为先用测试表达,再观察测试按预期失败;用最小实现让它通过,最后运行本仓库适用的交付检查。 ## 适用范围 - 新功能、行为变更和 Bug 修复。 - 因测试失败而需要局部修复或重试的任务。 - 跨前后端或多阶段工作,需要把需求映射到测试和评审结果的任务。 纯文档修改按 `AGENTS.md` 核对路径、命令、端口、模块名称和验证命令;不要为纯文档内容伪造代码测试。 ## 流程 ### 1. 澄清需求 先阅读根目录 `AGENTS.md` 及相关子目录规则,再查看目标代码、现有测试和 Git 工作区状态。常规需求澄清和测试不得依赖读取 `.env`、真实数据库或凭据;只有任务明确要求诊断本地配置或数据时,才做最小只读检查,并确保真实值不出现在输出中。 把用户请求整理为可观察的验收条件,说明: - 哪些输入会触发行为,以及预期输出或状态。 - 哪些现有行为必须保留。 - 哪些内容不在本次范围。 - 哪些失败可以局部重试,哪些变化会影响其他任务。 如果答案会改变外部接口、持久化格式、权限、安全行为或交付范围,先向用户确认。小而明确的改动可直接陈述假设并继续。不要在每个 RED/GREEN 循环都请求批准。 ### 2. 确认规格和计划 为每项验收条件列出至少一个能验证它的行为测试,并标出实现文件与依赖关系。多步骤或跨模块任务使用 `brainstorming` 和 `writing-plans` 的流程;先让用户确认规格和计划,再实现。 一个测试应说明它捕捉哪种错误。优先检查真实行为,避免只断言源码文本、私有实现或 mock 调用次数。对本来就满足的行为,不要制造一个假的 RED。 ### 3. 记录基线并保护现有改动 开始编辑前查看 `git status --short`,区分本任务新改动与用户已有改动。只编辑本任务需要修改的部分,不覆盖、删除或重置用户已有改动。 先运行与目标相关、已有的测试,记录其结果。区分这次引入的失败与基线已有失败。不要为了清理基线失败而扩大本次改动范围。 如果用户已有实现代码在测试之前存在: - 保留该代码,先为目标行为补上测试。 - 若测试暴露缺陷,再由测试驱动最小修复。 - 若测试立即通过,说明行为已经存在;不要删除用户代码或改写测试来制造失败。 如果本任务中新写的实现先于测试,停止继续扩展;先为目标行为建立测试,再仅整理或重做本任务由 Agent 新增的实现。不得把用户已有改动当作需要删除的代码。 ### 4. RED:运行一个聚焦测试 每次只处理一个行为: 1. 写出最小、名称清楚的测试。 2. 运行该测试或最小的现有测试入口。 3. 确认它因预期行为缺失而失败。 失败原因分类如下: | 结果 | 处理 | | --- | --- | | 断言因目标功能缺失而失败 | 进入 GREEN。 | | 导入、语法、测试数据或断言本身错误 | 修正测试或夹具,再运行同一测试。 | | 外部服务、网络、凭据或环境不可用 | 不把它算作产品行为失败;隔离外部边界或报告阻塞。 | | 与本次改动无关的基线失败 | 记录并保持本次范围;不要借机重构。 | 如果 RED 没有按预期失败,不要开始生产实现。 ### 5. GREEN 和 REFACTOR 只写通过当前测试所需的最小实现,不顺手增加范围外功能。 先运行刚失败的同一测试,确认通过;随后只整理已覆盖的代码,并保持测试通过。对纯转发、常量或无独立行为的代码,不要机械地要求“一函数一测试”;测试要保护可观察行为。 ### 6. 失败后最小范围重试 局部失败不等于重新执行完整工作流。保持已通过且不受影响的结果,只重试失败项及其必要依赖: 1. 找到第一个失败的断言或任务,并读完整错误信息。 2. 修改负责该行为的最小代码范围或测试夹具。 3. 重新运行该失败测试。 4. 只有当接口、共享状态或任务依赖确实变化时,才补跑直接依赖的测试。 5. 不重跑无关的已通过任务,不重新开始需求澄清或规格确认。 若失败说明验收条件不完整、需要改变用户可见行为或需要扩大数据/接口改动,暂停该分支并询问用户;不要自行改规格。 ## Hotline 验证命令 命令和测试布局可能变化。实施前重新检查 `AGENTS.md`、`package.json`、`frontend/package.json` 和实际测试文件;不要照搬其他项目的 `pytest`、`npm test` 或 `cargo test` 命令。 | 改动范围 | 当前可用检查 | 说明 | | --- | --- | --- | | Python 后端 | `python -m compileall python_backend` | 语法与字节码编译检查;不会执行模块导入,也不等于行为测试。 | | 技能中心 | `python skill-center/test_center.py` | 当前标准库 `unittest` 回归测试。根目录 `npm test` 也只调用此测试。 | | Vue 前端 | `npm --prefix frontend run build` | 当前是构建检查;`frontend/package.json` 没有独立测试脚本。构建通过不能代替交互行为测试。 | | 文档 | 按 `AGENTS.md` 核对路径、命令、端口和模块名 | 不为文档文字添加无意义的源码测试。 | 交付代码修改前按根目录 `AGENTS.md` 运行后端编译和技能中心测试;改动前端时再运行前端构建。纯文档修改按 `AGENTS.md` 仅核对文档一致性。若命令不可用,说明实际使用的等价命令和限制,不要声称检查通过。 新增测试时沿用仓库已有测试框架。当前后端依赖中没有声明 `pytest`,不要仅为运行一个测试而静默安装或引入新测试框架;若确实需要新框架,将其列入方案并说明影响。 ## 外部服务与测试数据 - 测试不得依赖真实大模型、Tavily、MinerU、MySQL、Redis、MinIO 或 pgvector 服务。 - 使用临时目录、临时 SQLite 数据库和固定输入;将网络服务替身放在外部 I/O 边界。 - 常规自动化测试使用临时数据,不读取仓库已有运行数据。运行数据默认位于仓库根目录 `data/`;若配置指定了其他数据目录,也按同等敏感信息处理。 - 任务明确要求诊断本地运行数据时,只检查必要内容;不得把敏感值输出到消息、日志、测试夹具或可提交文件,也不得复制原始运行数据。 - 不把 `.env`、真实 API Key、密码、真实服务地址、用户文件或运行数据库复制到测试夹具、日志和报告中。 ## 评审与完成条件 完成前核对: - 每项验收条件都对应测试或明确说明无法自动测试的原因。 - 至少一个新增行为测试按预期经历 RED 和 GREEN;已有行为已满足时如实说明。 - 聚焦测试通过,项目规定的交付检查已运行并报告。 - 局部失败只重跑了失败范围和必要依赖,没有重置用户已有改动。 - 评审确认实现、测试、规格和数据边界相符。 跨模块、重要功能或合并前使用 `requesting-code-review` 请求独立评审;较小改动也要检查差异、错误路径和敏感数据风险。评审发现问题时只修复相关项,再重跑该项测试及必要依赖检查。 最终报告列出:实现内容、RED/GREEN 证据、实际运行的命令及结果、未运行或未通过的检查、评审发现及处理结果。不要把构建检查称作行为测试,也不要隐去基线失败。 ## 常见误区 | 误区 | 正确做法 | | --- | --- | | “把所有检查每次都重跑最保险。” | 局部修复先重跑失败测试和直接依赖;交付前再运行项目规定的完整检查。 | | “根目录有 `npm test`,它就是全项目测试。” | 它当前只运行技能中心测试;按改动范围选择实际检查。 | | “前端 build 通过就证明交互正确。” | build 只证明产物能构建;交互行为需要行为测试或明确的人工验证记录。 | | “要先看到 RED,就得删掉已有实现。” | 保留用户代码;对已有行为先写表征测试,缺陷再由测试驱动修复。 | | “外部模型能连上才算测试。” | 把外部调用隔离在 I/O 边界,用固定替身验证本地逻辑。 | | “测试失败了,整个计划从头再来。” | 保留有效结果,只重跑失败项及被它影响的依赖。 |