Skip to content

xinetzone/SpecWeave / .trae/skills/spec-task-ifavc-delivery

spec-task-ifavc-delivery

Verified

按 I→F→A→V→C 闭环推进 .trae/specs 编号 Task——事实采集、作用域设计、代码与剧本测试同批落地、fresh-context 对抗评审(P0/P1 必修并回归)、证据回填与显式文件隔离的中文原子提交(默认不推送)。当用户说“继续推进/完成 Task N”或承接故障注入、韧性验收类规格任务时使用;无 spec 任务单的日常编码不要使用。

spec-task-ifavc-delivery

把 .trae/specs/<theme>/tasks.md 中的一个编号 Task 从 pending 推进到 completed 的标准闭环。链路固定为 I(事实)→ F(方案)→ A(实施)→ V(对抗验证)→ C(收尾),五阶段顺序不可颠倒;每阶段产出可审计证据,最终一次原子提交,未经用户明确要求绝不 push。

本技能沉淀自 wechat-mp-content-archiver Task 9/10/11/12 四次同构交付,适用于任何有 spec.md + tasks.md 的规格任务。

阶段 0:冻结目标(动手前必做)

  1. 读磁盘原文,不凭记忆/摘要:用 Read 打开目标 tasks.md 的 Task N 段落(Status、Priority、Depends On、Description、AC Addressed、TR 验收项)与 spec.md 中对应 AC 条款全文。会话延续(有 summary)时同样重读,摘要只作线索不作事实。
  2. 冻结三件事并在 TodoWrite 建 5 项清单(I/F/A/V/C):
    • 交付边界:软件侧可闭环的部分 vs 必须真实环境(真机/Docker/扫码/实网)的部分;后者做不到就显式挂起并写入证据,不假装完成。
    • 测试基线:找到应用目录与测试命令,先跑一次记录基线通过数(如 205/205)。
    • 提交纪律:默认最后一次原子提交、不推送;确认提交工具与工作区是否已有无关的已暂存/未暂存变更。
  3. 遵守仓库 AGENTS.md 启动协议与文档边界:公开产出入根 docs/,规格产物留在 .trae/specs/;Markdown 交叉引用一律相对路径,禁止 file:/// 与 .temp/ 引用。

I:事实采集(Investigate)

  • 读现有机制而非想象:相关源文件的现状行为(重试/状态机/错误分类/退出码/幂等等)、已有测试覆盖了什么、夹具与 helper 长什么样。
  • 每条事实标注文件与行号;区分「已有机制可复用」与「真实缺口」。故障/韧性类任务还要画出故障信号在各层(client → core → adapter → CLI)的现有传播路径。
  • 记录环境事实:Python 版本、venv 位置、测试命令、外部依赖的 mock 方式(如 httpx MockTransport)、时钟/睡眠/随机源可否注入。

F:方案成形(Form)

  • 先做作用域分流表再写代码:每类输入信号 → 作用域(账号/环境级、连续服务级、单篇/单资源级)→ 行为(立即熔断 / 连续阈值熔断 / 隔离继续)→ 可观测信号(日志/退出码/报告字段)→ 恢复方式。
  • 明确「不改变什么」:刻意保留的边界(如媒体单资源失败不阻断主产物)要写明,防止 V 阶段被当缺陷或在 C 阶段误改。
  • 设计可观测性时同步定日志脱敏规则(只记 host 不记 query/凭证/标识参数)。
  • 列出剧本→测试用例的一一对应清单,AC 每条至少一个可执行用例。

A:实施(Act)

  1. 源文件改动与测试在同一阶段完成,不许只改源码留测试到后面。
  2. 新测试优先独立成文件(如 tests/test_fault_injection.py),模块 docstring 写清剧本清单与可复现命令(含能实时打印行为日志的命令行,作为 TR 要求的「演练日志」证据)。
  3. 确定性优先:注入 sleeper/clock/rng,断言精确数值(退避秒数序列、请求次数、状态计数),不断言弱布尔;覆盖「不触发」的反例(如失败被成功篇隔开时不熔断)。
  4. 预判旧测试断言漂移:行为语义改变后,主动 grep 旧断言(字符串、状态、异常类型),逐条核对后显式更新,并在提交说明中交代。
  5. 先单跑新测试文件,再跑全量;全量通过数 = 基线 + 新增(记录两个数字)。注意全局日志配置(如 configure_logging)可能在全量套件中抬高/压低 logger 级别导致 caplog 断言失效,断言时用 caplog.set_level(level, logger="<具体logger名>")。

V:对抗验证(Verify)——强制 fresh-context 独立评审

自审通过后,必须用 Task 工具派一个 general_purpose_task 子智能体做只读对抗评审(子代理无本会话上下文,模拟独立 reviewer):

  • 简报必须包含:改动文件清单与每个文件的职责、相关 AC 原文、要求它尝试找反例的具体假设(至少覆盖:数值/边界 off-by-one、误杀正常输入的场景、状态机污染与半成品落盘、幂等/重复、错误分类计数时机、日志泄密、CLI 多路径接线、测试断言是否过弱/依赖执行顺序)。
  • 要求输出 P0/P1/P2 分级(每条给文件:行号、证据、后果、修复建议)+ 已核查无问题清单;允许它运行测试与写临时探针,但禁止改项目文件。
  • 处置规则:P0/P1 必须修复;P2 逐项给出「修复」或「刻意保留 + 理由」的结论,不得沉默忽略。
  • 每个被证实的问题修复后必须补一条回归测试(复现评审反例),再跑全量。把评审发现与处置摘要写入最终 tasks.md 证据。

C:收尾闭环(Close)

  1. 用户可见行为变化时更新应用 README 的对应小节(表格化行为/处置/退出码),不新建多余 md。
  2. 回填 tasks.md 的 Task N:
    • Status 改为 completed,括号注明完成日期与挂起项(软件完成 vs 真机/实网挂起的边界);
    • Completion Evidence 用相对路径链接(spec 到 apps 通常是 ../../../apps/...),写清机制、测试文件与用例数、基线→新总数、每条 TR-x.y 如何闭环(证据形态)、独立评审发现与处置、真实环境挂起说明。
  3. 原子提交(见下方固定工具):
    • 先 git status --short 与 git diff --cached --name-only;工作区中先于本任务存在的无关变更一律不纳入;
    • 用显式文件路径提交;若暂存区混入无关文件,先 git reset HEAD -- <file> 撤出;
    • 中文 Conventional Commit(type(scope): 主题(Task N)),正文交代 AC 映射、测试数、评审闭环、挂起项;
    • 提交后验证:git cat-file commit HEAD 中文无乱码、git log --oneline -1、git status -sb 确认 ahead 且未推送。
  4. 最终汇报固定六项:commit hash、文件清单、测试通过数(基线+新增)、V 阶段发现与处置、挂起项、未推送声明。

本工作区固定事实

  • 应用多为自带 venv 的独立子项目:在应用目录下执行 .venv\Scripts\python.exe -m pytest -q;需要总数汇总行时去掉 -q。
  • UTF-8 提交工具(支持显式文件隔离,多个 -m 为主题/正文): python .agents\scripts\git-commit-utf8.py -m "主题" -m "正文" <显式文件路径...> 暂存区存在无关已暂存文件时该工具会 FAIL。
  • Windows PowerShell 7 写复杂临时代码用 here-string:@'...'@ | Out-File "$env:TEMP\x.py" -Encoding utf8,跑完删除;不要在命令行里硬拼多层中文引号。
  • apps/ 可直接改;projects/、vendor/ 是 submodule,禁止本地修改。
  • 断点续跑/故障类任务的恢复语义默认:普通重跑只处理 pending,显式开关(如 --include-failed)才重试 failed——实现与文案都要与此一致。

反模式

  • 跳过 V 的独立评审,只用自审代替(本流程核心价值在 fresh-context 反例)。
  • P1 问题「记下以后再修」却把 Task 标 completed。
  • 评审意见只改代码不补回归测试。
  • git add -A / git add . 把工作区既有无关变更一并提交。
  • 未被要求自行 push;用「零风险」类绝对化表述;真机验收做不到却写成已完成。
  • 证据写成散文口号而无文件链接、用例数、TR 编号映射。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall