coding-conventions
Four rules and one verification pass. They lived in CLAUDE.md, where a long
session stops reading them; now the hook puts them next to the code you just
wrote. The firing is deterministic; following them is still your job.
The rules
- Surgical changes only. Every changed line traces to the request; match
existing style; no drive-by refactors, reformatting, or "improvements".
Remove orphans YOUR change created (imports, helpers, variables); leave
pre-existing dead code and mention it.
- Root cause, not symptom. Before patching the reported call site, grep the
shared function's other callers — the chokepoint fix is usually smaller and
actually closes the bug.
- Simplicity first — stop at the first rung that holds: (1) doesn't need to
exist → skip it, say so; (2) existing helper/pattern; (3) stdlib; (4) native
platform feature; (5) already-installed dependency; (6) one line; (7) minimum
new code. No features beyond the ask, no abstraction for single-use code, no
configurability nobody requested, no handling for impossible cases. 200 lines
that could be 50 get rewritten. Mark deliberate corner-cuts in-code:
# shortcut: <ceiling + upgrade trigger>.
- Verify before claiming done. Run it and paste real output; "should work"
is banned. Non-trivial logic ships with ONE runnable check (assert-based
self-check; no framework unless asked).
The pass (after every code edit)
SKIP WHEN the edit was a comment, a string, a doc, or a one-line constant —
say so in one line and move on. Verification that costs more than the change
it guards is theater.
- Re-read the real diff.
git diff or the file region — the bytes on
disk, not your memory of what you meant to write.
- Make it run. Cheapest thing that proves it executes:
python -c "import mod", node --check file.js, tsc --noEmit, the linter, the existing
test. If a suite covers this path, run it and paste real output. No output
= not verified.
- One runnable check behind non-trivial logic. A branch, loop, parser, or
money/security path leaves behind the smallest thing that fails if the
logic breaks. Trivial one-liners are exempt.
- Scope. Anything that does not trace to the request — a drive-by
reformat, an import you stopped needing, a helper nobody calls — comes
back out now.
Report, one block, honest:
ran: <command> → <real result>
checked: <what step 3 left behind, or "n/a — trivial">
scope: clean | removed <X>
A failure reported with its output beats a pass you didn't run.
Config
- Off for a session:
CODING_CONVENTIONS_OFF=1 (CODE_CHECK_OFF=1 is still
honoured — this skill absorbed code-check on 2026-09-06).
- Debounce and the code-file extension list live at the top of
hooks/postwrite-check.js.
Sources: the engineering-discipline block of a personal CLAUDE.md (moved here
2026-09-06), the code-check skill (merged), and Andrej Karpathy's LLM-coding
observations as packaged in the MIT karpathy-guidelines skill.
1---2name: coding-conventions3description: The coding rules that drift without a trigger: surgical changes, root cause over symptom, simplicity-first rungs with marked shortcuts, verify before claiming done with one runnable check. hooks/postwrite-check.js injects this body after every Edit/Write of a CODE file (docs/config excluded, debounced so a burst nudges once) so the rules land where code is being written. Also "check this", "verify that code", "did that actually run". Not an audit (/audit), not a bug hunt (/code-review).4license: MIT5---67# coding-conventions89Four rules and one verification pass. They lived in CLAUDE.md, where a long10session stops reading them; now the hook puts them next to the code you just11wrote. The firing is deterministic; following them is still your job.1213## The rules14151. **Surgical changes only.** Every changed line traces to the request; match16 existing style; no drive-by refactors, reformatting, or "improvements".17 Remove orphans YOUR change created (imports, helpers, variables); leave18 pre-existing dead code and mention it.192. **Root cause, not symptom.** Before patching the reported call site, grep the20 shared function's other callers — the chokepoint fix is usually smaller and21 actually closes the bug.223. **Simplicity first — stop at the first rung that holds:** (1) doesn't need to23 exist → skip it, say so; (2) existing helper/pattern; (3) stdlib; (4) native24 platform feature; (5) already-installed dependency; (6) one line; (7) minimum25 new code. No features beyond the ask, no abstraction for single-use code, no26 configurability nobody requested, no handling for impossible cases. 200 lines27 that could be 50 get rewritten. Mark deliberate corner-cuts in-code:28 `# shortcut: <ceiling + upgrade trigger>`.294. **Verify before claiming done.** Run it and paste real output; "should work"30 is banned. Non-trivial logic ships with ONE runnable check (assert-based31 self-check; no framework unless asked).3233## The pass (after every code edit)3435**SKIP WHEN** the edit was a comment, a string, a doc, or a one-line constant —36say so in one line and move on. Verification that costs more than the change37it guards is theater.38391. **Re-read the real diff.** `git diff` or the file region — the bytes on40 disk, not your memory of what you meant to write.412. **Make it run.** Cheapest thing that proves it executes: `python -c "import42 mod"`, `node --check file.js`, `tsc --noEmit`, the linter, the existing43 test. If a suite covers this path, run it and paste real output. No output44 = not verified.453. **One runnable check behind non-trivial logic.** A branch, loop, parser, or46 money/security path leaves behind the smallest thing that fails if the47 logic breaks. Trivial one-liners are exempt.484. **Scope.** Anything that does not trace to the request — a drive-by49 reformat, an import you stopped needing, a helper nobody calls — comes50 back out now.5152Report, one block, honest:5354```55ran: <command> → <real result>56checked: <what step 3 left behind, or "n/a — trivial">57scope: clean | removed <X>58```5960A failure reported with its output beats a pass you didn't run.6162## Config6364- Off for a session: `CODING_CONVENTIONS_OFF=1` (`CODE_CHECK_OFF=1` is still65 honoured — this skill absorbed `code-check` on 2026-09-06).66- Debounce and the code-file extension list live at the top of67 `hooks/postwrite-check.js`.6869Sources: the engineering-discipline block of a personal CLAUDE.md (moved here702026-09-06), the `code-check` skill (merged), and Andrej Karpathy's LLM-coding71observations as packaged in the MIT `karpathy-guidelines` skill.
Evan-Daruwalla