diff --git a/OPENCLAW_TRICKS.md b/OPENCLAW_TRICKS.md index 2e5eb1e..5e80c07 100644 --- a/OPENCLAW_TRICKS.md +++ b/OPENCLAW_TRICKS.md @@ -550,7 +550,26 @@ the tools_ — it's not documentation that can drift from reality, it IS the reality. `make` 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/` — 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