技能 Reference

V-AC 可行性

在 /dr-do 之前的前置关卡,证明每个运行时命令型 V-AC(docker exec / curl / kubectl / systemctl / 实时数据库查询)都能实际通过。

概述

验证型 AC(V-AC)可以被编写、评审,并引用正确的 AC 编号,但在任何正确的实现下都无法满足——因为它依赖的运行时命令所检验的内容,运行时语义根本不会暴露。当计划的验证清单包含任何验证方式为运行时命令的 V-AC 时,此关卡即启用:docker exec/kubectl exec、针对运行中服务的 curl/wget/Playwright、systemctl/journalctl 状态或日志断言、redis-cli/psql/mongosh 实时查询断言,或任何针对运行中进程的环境/内存/在途状态的断言。静态 V-AC(test -f、针对文件的 grep、lint/单元测试退出码)不需要此关卡——它们对工作树是确定性的。

此关卡防止的失败

触发事件:一个 AC 断言“运行中服务上的环境变量 X 被设置为 Y”,其验证方式为 docker exec <container> printenv X。但 printenv 读取的是 shell 的环境,而不是运行中的 Node 进程在代码中执行 process.env[X] = Y 后所持有的值。无论实现多么正确,该断言都永远无法通过——然而它却通过了计划评审,因为评审者只匹配了 AC 编号和命令形态,而没有针对真实(或骨架)运行时执行它。逐字 AC↔V-AC 镜像和语义匹配评审是必要的,但并不充分:V-AC 还必须可行,而可行性是运行时语义的属性,不是文本的属性。

契约

对于每个运行时命令型 V-AC,计划必须在将其锁定到验证清单之前,证明当实现正确时该命令能够返回 PASS 结果。可接受的证据,按优先级排列:

  1. 针对真实运行时的试运行。 针对运行中的 dev/staging/test 服务(或代表最终服务的桩骨架)执行该命令,并确认在刻意正确的夹具下它产生可观察的正确结果。在计划中内联引用该结果。
  2. 观察路径的语义证明。 当计划时无法访问运行时,指明所断言的值变得可观察的确切机制——例如“该值通过应用日志记录器记录,并用 journalctl -u <unit> | grep 断言”,或“该值在 /healthz JSON 上暴露,并用 curl … | jq 断言”。无法指明观察路径的命令被推定为不可行。
  3. 重新界定为可行的断言。 如果以上两者都不成立,则将 V-AC 替换为可观察的断言——日志行、HTTP 响应字段或持久化副作用,而不是运行时从不暴露的进程内值。

常见的不可行模式

  • 对代码中通过 process.env[X]=Y 设置的值使用 docker exec C printenv X——printenv 读取的是 shell 环境,而不是活动进程被修改后的环境。替代方案:断言回显 X 的应用日志行或 /config 健康字段。
  • 在服务绑定端口/路由存在之前使用 curl <url>——未映射的路由无论正确与否都返回 404。替代方案:先在路由器中 grep 真实路径,然后断言已映射的路由。
  • 对运行时修改的变量使用 kubectl exec … cat /proc/1/environ——/proc/1/environ 是启动环境,在 exec 时已冻结。替代方案:通过应用端点或结构化日志暴露该值。
  • 对应用设置的变量使用 systemctl show -p Environment——显示的是单元声明的环境,而不是进程内部设置的值。替代方案:通过应用自身的可观测性表面进行断言。

输出

在计划中每个运行时命令型 V-AC 旁边内联记录可行性判定,以便评审者无需重新查询即可复现:

  • V-AC-N — 可行(试运行:<command> → <observed PASS result>)
  • V-AC-N — 可行(观察路径:<named mechanism>)
  • V-AC-N — 按原文不可行 → 重新界定为 <new assertion>

没有可行性标注的运行时命令型 V-AC 是计划缺陷:在过渡到 /dr-do 之前修复计划(证明或重新界定)。在计划阶段发现不可行的 V-AC 只需一次试运行或一次 grep;在 /dr-do 或 /dr-verify 阶段发现则需付出完整的流水线周期外加一次 V 关卡重构。