Bun Agent Rules

A JavaScript runtime, bundler, test runner, and package manager.

Overview

Bun sends most development and testing through its build wrapper, with an exception for declaration-only edits. The guide separates regressions from behavior that never worked, explains the cost of debug and sanitizer builds, and points specialized reviews to separate guides. AGENTS.md links to this CLAUDE.md file.

Verification by change type Scope layering House vocabulary Architecture as narrative Router files

Documents

├── 
├──  · 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
│   └── 
└──

Techniques in this file

01 / Verification by change type

Prove that the test detects the change

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.

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

Explain the exception to the build rule

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.

31Edits 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

Define what counts as a regression

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.

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

Budget for debug and sanitizer overhead

The test guidance gives approximate time budgets and explains why release-speed assumptions become expensive in CI. It also distinguishes timeout ceilings from targets.

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

Account for arena cleanup semantics

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.

2008. **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

Route review decisions by task

The root links the shared review rules and a situational guide covering compatibility, API design, performance, platforms, dependencies, documentation, and PR work.

189Several 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).

Ideas for your repo

Require a regression test to distinguish the installed build from the changed build.
Document precise exceptions next to broad command prohibitions.
Define terms such as regression before using them to organize tests.
Set test budgets with CI instrumentation overhead in mind.
Call out lifetime-management exceptions that ordinary language idioms hide.