diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..be4479f37c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,36 @@
+## bun tests
+
+**IMPORTANT**: use the `bun agent` command instead of the `bun` command. For example:
+
+✅ Good
+
+```sh
+bun agent test internal/ban-words.test.ts
+bun agent ./foo.ts
+```
+
+The `bun agent` command runs the DEBUG build. If you forget to run the debug build, your changes will not be reflected..
+
+### Run a file
+
+To run a file, you can use the `bun agent <file-path>` command.
+
+```sh
+bun agent ./foo.ts
+```
+
+### Run tests
+
+To run a single test, you need to use the `bun agent test <test-name>` command.
+
+```sh
+bun agent test internal/ban-words.test.ts
+```
+
+You must ALWAYS make sure to pass a file path to the `bun agent test <file-path>` command. DO NOT try to run ALL the tests at once unless you're in a specific subdirectory.
+
+### Run a Node.js test
+
+```sh
+bun agent --silent node:test test-fs-link
+```
diff --git a/package.json b/package.json
index 0881238bd7..69f87e78be 100644
--- a/package.json
+++ b/package.json
@@ -33,7 +33,7 @@
     "build": "bun run build:debug",
     "watch": "zig build check --watch -fincremental --prominent-compile-errors --global-cache-dir build/debug/zig-check-cache --zig-lib-dir vendor/zig/lib",
     "watch-windows": "zig build check-windows --watch -fincremental --prominent-compile-errors --global-cache-dir build/debug/zig-check-cache --zig-lib-dir vendor/zig/lib",
-    "bd": "(bun run --silent build:debug &> /tmp/bun.debug.build.log || (cat /tmp/bun.debug.build.log && rm -rf /tmp/bun.debug.build.log && exit 1)) && rm -f /tmp/bun.debug.build.log && ./build/debug/bun-debug",
+    "agent": "(bun run --silent build:debug &> /tmp/bun.debug.build.log || (cat /tmp/bun.debug.build.log && rm -rf /tmp/bun.debug.build.log && exit 1)) && rm -f /tmp/bun.debug.build.log && ./build/debug/bun-debug",
     "build:debug": "bun ./scripts/build.mjs -GNinja -DCMAKE_BUILD_TYPE=Debug -B build/debug",
     "build:debug:asan": "bun ./scripts/build.mjs -GNinja -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON -B build/debug-asan",
     "build:valgrind": "bun ./scripts/build.mjs -GNinja -DCMAKE_BUILD_TYPE=Debug -DENABLE_BASELINE=ON -ENABLE_VALGRIND=ON -B build/debug-valgrind",