reframe quality standards as benefiting everyone, not just agents
All checks were successful
check / check (push) Successful in 11s

Humans also have limited state and drop things under cognitive load.
Universal make targets reduce context-switching cost across repos.
Agents can implement/enforce, but everyone benefits.
This commit is contained in:
clawbot 2026-02-28 02:28:34 -08:00
parent f5e2d22398
commit 0db057ff4a

View File

@ -550,7 +550,26 @@ the tools_ — it's not documentation that can drift from reality, it IS the
reality. `make<tab>` shows you everything you can do. No wikis to read, no
READMEs to hope are up-to-date.
For AI agents specifically, this is even more valuable:
The deeper insight: **humans also have limited state, limited memory, and start
dropping things when context gets too big.** A developer switching between a Go
service, a Python scraper, and a JS frontend in the same afternoon doesn't want
to remember three different ways to run tests, three different linter
invocations, three different formatting commands. `make test` is `make test`
everywhere. `make check` is `make check` everywhere. `make fmt` is `make fmt`
everywhere. The language, the framework, the toolchain — all abstracted behind a
universal interface.
This reduces cognitive load and allows better flow and focus. You don't have to
re-orient when switching repos. You don't have to look up "was it `pytest` or
`python -m pytest` or `make test-unit`?" The Makefile answers all of that with
one consistent vocabulary across every project.
The agent can implement and enforce these policies — auto-generating Makefiles,
running the checklists, catching drift — but everyone benefits. Humans get
consistency. Agents get predictability. New team members (human or AI) get
instant orientation. The policies serve all three audiences simultaneously.
For AI agents, there's an additional benefit:
- The agent always uses `make test`, never `go test ./...` directly — the
Makefile encapsulates flags, timeouts, environment setup
@ -676,21 +695,27 @@ The full standardized configs are available at
`https://git.eeqj.de/sneak/prompts/raw/branch/main/<filename>` — agents fetch
them when bootstrapping a new repo, ensuring consistency across all projects.
#### Why This Matters for AI Agents Specifically
#### Why This Matters — For Everyone
AI agents have a unique failure mode: they're confidently wrong. An agent will
push code that "should work," assert that checks pass without running them, or
silently weaken a gate to make the build green. Automated interlocking checks
turn these soft failures into hard failures:
These interlocking checks aren't just agent-proofing — they're human-proofing
too. Humans also cut corners under deadline pressure, forget to run the
formatter, skip tests "just this once," or push a quick fix without checking CI.
The automated gates don't care who's committing:
- Can't push unformatted code → `make fmt-check` in pre-commit hook
- Can't skip tests → `make check` depends on `make test`
- Can't weaken linters → config file changes flagged in PR review
- Can't claim "CI passes" without proof → Docker build is pass/fail
- Can't ship without the human seeing it → PR assignment rules
- Can't ship without review → PR assignment rules
The agent doesn't need willpower or attention to detail. It needs a system where
doing the wrong thing fails loudly.
AI agents do have a unique failure mode on top of this: they're confidently
wrong. An agent will assert that checks pass without having run them, or
silently weaken a gate to make the build green. The interlocking system catches
this too — confidence doesn't override a failing build.
Nobody needs willpower or attention to detail when the system makes doing the
wrong thing fail loudly. That's the point: good engineering infrastructure
benefits every contributor, regardless of whether they're carbon or silicon.
#### Checklists Over Prose — Why Redundancy Is the Point