diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7a50aa7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,19 @@
+# Agent guidelines for agent-sandbox
+
+## Build and test
+
+- `cargo fmt` and `cargo clippy` must pass before every commit.
+- `cargo test` runs all integration tests. Tests run serially (configured in `.cargo/config.toml`) because they spawn real bwrap sandboxes that share host paths like `/tmp`.
+- Never add Co-Authored-By lines to commits.
+
+## Things that will bite you
+
+### bwrap argument ordering matters
+
+Later bwrap arguments override earlier ones for the same path. This has caused multiple bugs:
+
+- Blacklist overlays (tmpfs, ro-bind /dev/null) must come **after** the base `--ro-bind / /` and `--bind /tmp /tmp`.
+- The `/run` tmpfs and its selective whitelisted binds must come **after** the overlay section, or the overlays clobber the whitelisted paths.
+- User `--rw`/`--ro` escape hatches must come **after** mode setup so they can override sandbox restrictions.
+
+Take extreme care when reordering any arguments in `sandbox.rs` or refactor things and test thoroughly.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md