tmu
8940537fc0
The agent must not use `git commit --no-verify` (or skip any hook) to get a green run — bypassing a check to silence it is the same anti-pattern as @ts-nocheck or an oxlint-disable. The pre-commit checks are fast and offline, so a redundant run costs nothing. Records the "redo through the hook" recovery command.
3.4 KiB
AGENTS.md
Machine entry point for AI coding agents working in this repo. The authoritative guidance for humans lives in CONTRIBUTING.md and README.md; this file only points at it and states the stable first-action facts. Do not restate evolving prose here — it will drift.
First action
-
Project: F#-style pattern matching for TypeScript/ESM. Node
>=26(pinned via.node-version), ESM-only (no CommonJS shim). -
Mandatory while iterating:
npm run test(runscheck:tsc, then the unit suite). This is the gate you are responsible for. -
On commit: write a good message (see CONTRIBUTING.md § Commit messages). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks (
tsc+oxlint+oxfmt+cspell) — don't run them by hand. If the hook fails on style,npm run fix, restage, recommit. -
npm run checkis NOT part of the feature loop. It addsknip(dead-code/deps) andcheck:outdated(registry) — repo-maintenance scans. Run it only on an explicit maintenance / update-deps branch; CI runs it on the PR regardless.npm run test # the bot's definition of done; commit normally after
Never do
Don't silence the type system to force a green run. As an agent these are forbidden:
// @ts-nocheck,// @ts-ignore,// @ts-expect-error// oxlint-disable/// oxlint-disable-next-lineascasts used to push an expression through (type-aware oxlint already flags unsafe assertions)
Fix the root cause with the type system instead — narrowing, generics, satisfies, conditional / mapped types, utility types (NonNullable, Exclude, …). TypeScript can express it; that's the intended tool. The oxlint-disable-location rule in CONTRIBUTING.md § Rules the tools don't enforce is a human last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / MR) rather than suppress it.
The same applies to the checks themselves: never git commit --no-verify (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: git reset --soft HEAD~1 && git commit -C <skipped-sha>.
Read these
- CONTRIBUTING.md § Rules the tools don't enforce — the constraints the linters don't catch; CI/review bounce these. The most important section.
- CONTRIBUTING.md § Script prefix convention — adding an
npm runscript? reuse an existing prefix or it doesn't belong. - CONTRIBUTING.md § Commit messages — gitmoji + imperative + 50/72.
- CONTRIBUTING.md § Feedback tiers — what runs when (
watch/ pre-commit / pre-push /check/fix/ CI). - README.md § Tooling decisions — the rationale behind each tool choice; read before changing tooling.
- package.json
#scripts— the source of truth for every command (theLEFTHOOK_FILESconvention scopes them to staged files vs. the whole project).