Back to Details

verify-commands

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Verify commands

验证命令

A verify command is an acceptance test. Before shipping one, answer: if this command were silently doing nothing, what in its output would tell me? If you cannot answer, you have a command, not a check. Fix the command; do not invent a statement for it.
验证命令属于验收测试范畴。在交付前，请先回答：如果该命令静默执行无任何操作，从其输出中能看出什么？ 如果无法回答，那你拥有的只是一个命令，而非检查项。请修复该命令，不要为它编造理由。

Name the failing direction

明确失败方向

Next to every runnable check, write one line naming the observable signal that means failure: 
non-zero exit
, 
"0 passed" in the summary line
, 
the coverage line is absent
, 
stderr contains "ECONNREFUSED"
. "The command fails" and "an error occurs" are restatements, not signals. 
TBD
, 
N/A
, and 
none
are refusals. Short is fine; 
non-zero exit
is complete. Prefer the signal the tool actually emits over one you imagine: for a command that already ran, state what you saw; for a new one, take the signal from the tool's documented output. N commands need N statements.
在每个可运行的检查旁，添加一行文字说明代表失败的可观测信号：
non-zero exit
（非零退出码）、
摘要行中包含"0 passed"
、
覆盖率行缺失
、
stderr包含"ECONNREFUSED"
。“命令失败”和“发生错误”只是重述，并非信号。
TBD
、
N/A
和
none
属于回避问题。简短即可；
non-zero exit
就足够完整。优先使用工具实际输出的信号，而非你想象的信号：对于已运行的命令，说明你实际看到的信号；对于新命令，则参考工具文档中记录的输出信号。N个命令需要N条说明。

Ground every path

锚定所有路径

Inherit the command that already worked in this repo, verbatim, before deriving a new one. A 
cd
target or 
--prefix
target must exist, or be created by an earlier step, and must hold the matching manifest (
package.json
, 
Makefile
, 
pyproject.toml
). Prefer 
npm --prefix <dir> run <script>
over 
cd <dir> && npm run <script>
; it does not depend on the caller's working directory. Do not hand-reason the filesystem: list it. If you cannot ground a path, say so instead of guessing.
在衍生新命令前，先完全继承仓库中已验证可行的命令。
cd
目标或
--prefix
目标必须存在，或由之前的步骤创建，且必须包含匹配的清单文件（
package.json
、
Makefile
、
pyproject.toml
）。优先使用
npm --prefix <dir> run <script>
而非
cd <dir> && npm run <script>
；前者不依赖调用者的工作目录。不要主观推断文件系统结构：列出实际路径。如果无法锚定路径，请如实说明，不要猜测。

Shapes that pass while measuring nothing

看似通过但未有效检测的情况

TrapWhy it passesInstead
pnpm ls vite | grep -E '^vite@7'
tree output starts each line with 
└──
, so 
^
never matches		drop the anchor, or match 
(└|├)── vite@7
npm test | grep '714 passed'
a count recalled from memory, stale from training
grep -E '[0-9]+ passed'
, or run the count first
X=$(cmd 2>/dev/null || echo 0)
feeding 
[ "$X" = "$Y" ]
both sides default to 
0
when inputs are missing, so parity passes on nothing		let the failure propagate, or guard with 
test -f
and exit
grep -c 'LITERAL' file == 0
while an instruction or comment quotes 
LITERAL
the gate trips on comment text, not on codedescribe the forbidden thing by concept, not by literal
! grep -q PATTERN file
when a sibling change legitimately adds 
PATTERN
elsewhere in the file		a file-wide negative is unsatisfiable across regionsscope it: 
awk '/^def f/,/^def /' file | grep
, or an AST check, or a unit test
a test-name filter that matches zero testsexit 0 with nothing assertedlist tests first (
--collect-only
, 
--list
), then run the one named test
The anchor trap has a family: 
npm ls
, 
yarn list
, 
docker ps
, and 
kubectl get
all print column or tree prefixes. 
|| echo default
is acceptable only when absence is the default and the value is not used in a comparison meant to detect absence.
陷阱为何会通过替代方案
pnpm ls vite | grep -E '^vite@7'
树形输出每行以
└──
开头，因此
^
永远无法匹配		移除锚点，或匹配
(└|├)── vite@7
npm test | grep '714 passed'
数字是凭记忆回忆的，与当前实际情况不符使用
grep -E '[0-9]+ passed'
，或先获取实际数量
X=$(cmd 2>/dev/null || echo 0)
用于
[ "$X" = "$Y" ]
当输入缺失时，两边默认值均为
0
，因此即使无有效输入也会判定相等		让失败直接传播，或用
test -f
检查并退出
grep -c 'LITERAL' file == 0
但说明或注释中引用了
LITERAL
检查会触发注释文本，而非代码中的内容从概念层面描述禁止的内容，而非字面文本
! grep -q PATTERN file
但其他合法修改在文件其他位置添加了
PATTERN
针对整个文件的否定检查在不同区域无法满足限定范围：使用
awk '/^def f/,/^def /' file | grep
，或进行AST检查，或编写单元测试
匹配零个测试的测试名称过滤器无任何断言就返回退出码0先列出测试（使用
--collect-only
、
--list
），再运行指定的测试
锚点陷阱有一系列类似情况：
npm ls
、
yarn list
、
docker ps
和
kubectl get
都会输出列或树形前缀。只有当缺失是默认情况且该值不用于检测缺失的比较时，
|| echo default
才是可接受的。

Reviewing someone else's command

审查他人的命令

Report; never prescribe a replacement path you did not verify. A prescribed path is copied verbatim and carries zero information. A missing directory or manifest is a blocker: quote the raw target. A dynamic path, glob, 
~
, or variable is a warning, not a licence to guess the literal.
仅报告问题；切勿给出未经验证的替代方案。指定的替代方案会被直接复制，但不包含任何有效信息。缺失的目录或清单文件是阻塞问题：直接引用原始目标。动态路径、通配符、
~
或变量是警告，而非猜测字面内容的许可。