AGENTS.md: agent context + testing framed as additive coverage#332
Conversation
Two changes:
1. New "Context for every agent" section near the top of AGENTS.md.
Role (low-level framework), audience (unknown broad, high-stakes
included), and the dark-factory thesis (tests carry the load human
review used to) shape every decision more than any specific rule.
Implications: coverage bar higher than typical, new environments
are additive not replacements, avoid rules that foreclose future
goals, more signal not less.
2. Reframe the Testing section. The previous language pinned TKO to a
single environment ("real browsers only") which is presumptive and
forecloses reasonable future targets like SSR / TUI / node reactive
code. New framing: the browser matrix is authoritative today;
additional environments (happy-dom, node, TUI shims) are welcome
when they add coverage for runtimes TKO should work in. A failing
test in a new environment is signal — fix the signal, don't prune
the test.
Framing beats prescription for a framework at TKO's level.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 0 minutes and 4 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Updates contributor/agent guidance in AGENTS.md to set higher-level decision framing for TKO work, and to adjust the testing guidance to emphasize additive coverage across environments without locking out future targets.
Changes:
- Adds a new “Context for every agent” section describing overarching constraints (framework nature, broad downstream audience, test-driven safety).
- Reframes the Testing section to treat the real-browser matrix as authoritative today while encouraging additional environments when they add coverage.
| Today the suite runs in a real-browser matrix (chromium, firefox, webkit) — authoritative because the binding layer is exercised against real DOM behavior. Additional environments (happy-dom, node, bun, TUI shims, …) are welcome when they **add** coverage for runtimes TKO should work in. Additive, never replacement; a test failing in a new environment is signal (missing polyfill, real env-scoped behavior, or a test that assumed too much) — fix the signal, don't prune the test. | ||
|
|
||
| Fast local iteration: scope the run (`bunx vitest run packages/observable`, ~1s warm). |
There was a problem hiding this comment.
The doc here implies bunx vitest run runs a chromium/firefox/webkit matrix by default, but locally the default is just chromium unless VITEST_BROWSERS is set (see vitest.config.ts and .github/workflows/test-headless.yml). Consider clarifying that the matrix is authoritative in CI (and how to opt into it locally), and aligning the earlier “Runner … headless Chromium” bullet/bun run test description with this wording to avoid confusing contributors.
|
|
||
| Tests run in a real browser via Playwright — not jsdom. This is required | ||
| because TKO does low-level DOM manipulation, MutationObserver, and event handling. | ||
| Today the suite runs in a real-browser matrix (chromium, firefox, webkit) — authoritative because the binding layer is exercised against real DOM behavior. Additional environments (happy-dom, node, bun, TUI shims, …) are welcome when they **add** coverage for runtimes TKO should work in. Additive, never replacement; a test failing in a new environment is signal (missing polyfill, real env-scoped behavior, or a test that assumed too much) — fix the signal, don't prune the test. |
There was a problem hiding this comment.
Minor grammar: “Additive, never replacement” is missing an article; consider “Additive, never a replacement” for readability.
| Today the suite runs in a real-browser matrix (chromium, firefox, webkit) — authoritative because the binding layer is exercised against real DOM behavior. Additional environments (happy-dom, node, bun, TUI shims, …) are welcome when they **add** coverage for runtimes TKO should work in. Additive, never replacement; a test failing in a new environment is signal (missing polyfill, real env-scoped behavior, or a test that assumed too much) — fix the signal, don't prune the test. | |
| Today the suite runs in a real-browser matrix (chromium, firefox, webkit) — authoritative because the binding layer is exercised against real DOM behavior. Additional environments (happy-dom, node, bun, TUI shims, …) are welcome when they **add** coverage for runtimes TKO should work in. Additive, never a replacement; a test failing in a new environment is signal (missing polyfill, real env-scoped behavior, or a test that assumed too much) — fix the signal, don't prune the test. |
Agents ship fast; humans review less. The safety net has to move earlier in the loop. Before declaring done, steelman the case against the change — what could go wrong, what future goal it forecloses, what coverage or signal it weakens, who it surprises. Spawn a subagent for an independent adversarial pass on high-leverage changes (framework internals, test coverage, public APIs, shared docs). Lists the common failure modes worth probing every time: speed/coverage trades, happy-path optimization, presumptive rules, symptom vs root cause, scope creep, silent environmental assumptions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Subagent review flagged three real issues; fixing all three: 1. Context section was too long and restated rules below it. Compressed to two bullets + one-sentence implication, focused on the coverage/ safety bar rather than philosophy. 2. "Additive, never replacement" was absolute, contradicting the PR's own "don't foreclose future goals" warning (Playwright once replaced karma, webkit may need dropping someday, etc.). Softened to: new environments should add coverage, not substitute for the authoritative matrix; if a PR replaces a runner/environment/matrix target, say so explicitly and justify the coverage delta. "A failing test is usually signal — investigate before excluding" replaces the absolutist "fix the signal, don't prune the test." 3. Generic failure-modes list missed the ones that actually bite a published low-level framework. Replaced filler bullets with: backwards-compat in @tko/build.knockout, disposal leaks, hot-path perf regressions, public @tko/* API changes without a changeset, import-time side effects. Kept the generic bullets that still apply. Also: cross-linked "Always Improve" and "Review Adversarially" so the tension is explicit (improve in scope, audit the scope itself here). Dropped the "spawn a subagent" prescription in favor of "get an independent second pass" — portable to contributors whose harness doesn't expose agent-spawning. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
"Scope creep disguised as while I'm here" collided directly with the "Always Improve" section which encourages exactly that shape of cleanup. Replaced with explicit wording that points back at Always Improve's bar (small, low-risk, in-scope) so the two rules reinforce instead of contradicting. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Summary
Two changes to
AGENTS.md:1. New "Context for every agent" section
Up near the top, before the project structure. Establishes the three framings that shape every decision:
With implications: coverage bar higher than typical, new environments are additive not replacements, avoid rules that foreclose future goals.
2. Reframe the Testing section
The previous line ("real browsers only") was presumptive and forecloses reasonable future targets like SSR / TUI / node reactive code. New framing: the browser matrix is authoritative today; additional environments are welcome when they add coverage for runtimes TKO should work in. A failing test in a new environment is signal — fix the signal, don't prune the test.
Why
Framing beats prescription at TKO's level. A rule saying "no happy-dom" rules out adding TUI runtime validation later; a framing saying "additive, never replacement" gets the same safety in the present without locking the door on the future. Worked through in closed #330 (failed speed-for-coverage trade) and #331 (too prescriptive, closed in favor of this).
Test plan
Docs-only.
🤖 Generated with Claude Code