code-quality
Generic code-authoring standards for dev agents: correctness over convenience, no fail-open branches, comment rules, over-engineering limits, prove-your-guards. Load before writing or modifying code.
vanillagreencom · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add vanillagreencom/kendex --skill code-quality技能说明
name: code-quality description: "Load for any coding or development task in any repository: writing, changing, fixing, refactoring, or testing code or scripts in any language." summary: "Code-authoring standards for dev agents: correctness over convenience, no fail-open branches, comment rules, over-engineering limits, prove-your-guards, test shape." license: MIT user-invocable: true dependencies: required: [docs-writing] metadata: author: vanillagreen source: kendex repository: "https://github.com/vanillagreencom/kendex" bugs: "https://github.com/vanillagreencom/kendex/issues" version: "1.0.0" tags: [review]
Project Instructions
Problems with a kendex-owned skill go through kendex report; check ownership in the file first.
Code Quality
Repo-specific standards live in each repo's ## Project Instructions section and add to these rules.
Core Principle
A loud failure beats a silent wrong answer. Handle every error, check invariants, and never continue in a state the code does not understand.
Correctness
- No workarounds or quick hacks. If the correct fix is larger than expected, say so.
- Never fail open. A dependency failure (command, file, network, parse) must not leave the caller in a passing or default state: no validator degrading to "no findings", no probe failure read as "not applicable".
- A gate, guard or scanner change adds no enumerated exemption list; a refusal is one rule at the point the code cannot judge.
- A branch that "shouldn't happen" is never an empty or silently-ignored
else: assert it, return an explicit internal error, or mark it unreachable, with a message naming the violated invariant. Use plain conditionals only when both branches are expected paths. - An error path must name the actual cause, not a neighbouring dependency.
- Handle edge cases: empty input, boundary values, junk prefixes/suffixes, interrupted-then-retried flows.
Prove Your Guards
A new or modified check, guard, assertion, or test ships with a must-fail control: plant the defect it catches (a red-first run or a temporary mutation) and see it go red before its green counts. A guard that pattern-matches source text also gets controls for shapes that satisfy the match without the property: comments, string and template-literal interiors, nested occurrences, alternate quoting, a braceless statement, a dead branch, a discarded result, and a textually earlier but unrelated conditional. The control that counts keeps the matched text and removes the behavior; one that deletes the code under test only proves the assertion runs. Reject assertions loose enough to match a skip note, fixtures that never reach the guarded bound, and harness code that keeps alive what the implementation should.
- A scripted text substitution asserts its match, or it is not an edit. Assert the pattern's occurrence count and that the file changed, or use an edit tool that errors on no match. Neither assertion holds on a symlink, which
sed -ireplaces with a new file while its target stands: resolve the path first, or refuse a symlink. - A floor alone is not a control. Derive the expected set from the artifact under test (the flag's own regex, the function's own body), never from a second list in a test file. Floor it, with a message naming the extractor as broken rather than the subject as sparse. Under-inclusion needs the floor plus a required member; over-inclusion needs a forbidden member. State which direction stays open.
Instruments you did not write
- A check narrower than the claim can only confirm it, never establish it. Match the instrument's reach to the assertion's reach before running it, and prefer one that fails visibly on a planted counterexample. A grep over one directory supports no claim about the tree.
- Behaviour measured at an interactive prompt is not what scripts get.
type <cmd>names the shadow, which differs per shell. Resolve the command in the script's own shell and PATH, and name the shell and implementation it resolves to. - A guard's failure message is an instrument. It is what an author acts on. Unescaped backticks inside a double-quoted diagnostic execute their contents, so the intended text is altered or gone while the surrounding command still succeeds.
Tests
- One control per behaviour surface, a public function, command, rule or contract, plus its inverse: the must-fail control § Prove Your Guards demands.
- N planted defects means N asserted rows. A fixture that plants several defects under one verdict passes while any one of them is caught, and is never allowed.
- Shaped input (positions, settings keys, tamper classes) is one table-driven case: one loop, one assertion per row, the row list visible in the file.
- Assert the code, the enum or the exit status. Pin a human-readable message only inside a contract a consumer parses.
- A row pins the clause only its own guard emits: an expectation a neighbouring gate or the production helper on both sides can also produce is not a pin, a value read as a truthiness bit is not a pin, and a fold keeps every assertion of its former cases.
- No test of the test harness: a pin on a manifest script string or a runner configuration proves nothing about behaviour.
- A shared fixture is a neutral world (a seeded repository, a fake SDK). A fixture that carries a planted defect is private to its case.
- One file per surface, beside the code, named for the surface.
- A file past about 64 KB or about 60 cases holds more than one surface. Split it at a surface seam and move cases whole. The seam is the author's judgement; no check measures it.
Language Discipline
- Rust: make illegal states unrepresentable; exhaustive matches (no
_ =>over enums you own); enums over strings/sentinels/booleans-with-meanin