A JavaScript runtime, bundler, test runner, and package manager.
Tests must fail against the installed runtime and pass against the local build.
├── ├── · symlink → CLAUDE.md ├── .claude │ └── docs │ └── ├── .github │ └── workflows │ └── ├── scripts │ ├── build │ │ └── │ └── verify-baseline-static │ └── ├── src │ ├── js │ │ ├── · symlink → CLAUDE.md │ │ └── │ ├── jsc │ │ └── bindings │ │ └── v8 │ │ ├── │ │ └── · same content as src/jsc/bindings/v8/AGENTS.md │ ├── · symlink → CLAUDE.md │ └── └──
The file, explained
Bun makes its build wrapper the default route into development and testing, with an explicit exception for declaration-only edits. Its instructions distinguish real regressions from behavior that never worked, explain how debug and sanitizer builds change test costs, and route specialized review decisions to separate guides. AGENTS.md is a symlink to this CLAUDE.md source.
Quoted passages are verbatim. Open one to see it in the source.
01 / Verification by change type
The guide requires a failing run against the installed Bun and a passing run against the debug build. A green test against both is not accepted as evidence for the fix.
Source excerpt starting at line 108.- **CRITICAL**: Verify your test fails with `USE_SYSTEM_BUN=1 bun test <file>` and passes with `bun bd test <file>`. Your test is NOT VALID if it passes with `USE_SYSTEM_BUN=1`.
02 / Scope layering
Type declaration tests package declaration files and invoke TypeScript without running the native binary. The guide therefore allows the installed test runner for this specific case.
Source excerpt starting at line 31.Edits to **TypeScript type declarations** (`packages/bun-types/**/*.d.ts`) do not touch any compiled code, so `bun bd` is unnecessary. The types test just packs the `.d.ts` files and runs `tsc` against fixtures — it never executes your build. Run it directly with the system Bun (an explicit exception to the "never use `bun test` directly" rule):
03 / House vocabulary
An issue-numbered regression file requires both a real issue and previously working behavior. Other bug coverage belongs beside the existing tests for the module.
Source excerpt starting at line 60.**Exception:** `test/regression/issue/${issueNumber}.test.ts` is reserved for bugs with a GitHub issue number **and** that are true regressions (worked in a previous release, then broke). If the behavior was never correct, it's not a regression — the test belongs in the existing file for that module. The issue number must be **REAL**, not a placeholder.
04 / Verification by change type
The test guidance gives approximate time budgets and explains why release-speed assumptions become expensive in CI. It also distinguishes timeout ceilings from targets.
Source excerpt starting at line 103.- Keep tests fast: budget roughly 1s per test and 10s per file. Debug+ASAN builds run 10-100x slower than release, so a 1s local test can take a minute in CI. Use `test.concurrent` for independent subprocess-spawning tests.
05 / Architecture as narrative
The memory-management note names the exception to normal RAII cleanup: arena reset does not run destructors. Heap allocations and references owned by those values need explicit release first.
Source excerpt starting at line 200.8. **Memory management** - Prefer RAII (`Drop`) over manual cleanup. Arena edge case: values allocated in an arena (`Arena<T>`/`bumpalo`) do **not** run `Drop` on arena reset — types owning a heap allocation or refcount must be freed/deref'd explicitly first, mirroring the original Zig `deinit()` order.
06 / Router files
The root links the shared review rules and a situational guide covering compatibility, API design, performance, platforms, dependencies, documentation, and PR work.
Source excerpt starting at line 189.Several situational sections live in `.claude/docs/landing-prs.md` — read the relevant one before the work it covers: **Node/Web compat** (touching `node:*` modules, Web APIs, or `src/runtime/node/`), **API design** (adding or changing user-facing API surface), **Performance** (optimizing, touching hot paths, or making perf claims), **Cross-platform** (platform-gated code, FFI/ABI, or platform-sensitive tests), **Dependencies & vendoring** (bumping deps or touching `vendor/`), **Docs, types, and comments** (docs, `.d.ts`, JSDoc), and **PR process** (opening or responding to a PR).
Put it to work
Bun's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
Try Modem