diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index cab440b5ef..0000000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,2 +0,0 @@
-1. See README.md for useful information about working on this.
-2. **Never ever** remove zig-cache, nether local nor global.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..64aa77a9fe
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,11 @@
+- when porting features from upstream Zig, it should be a mechanical copy.
+  Don't invent. Most of what you are doing is invented, but needs to be re-done
+  in C. Keep the structure in place, name functions and types the same way (or
+  within reason equivalently if there are namespacing constraints). It should
+  be easy to reference one from the other; and, if there are semantic
+  differences, they *must* be because Zig or C does not support certain
+  features (like errdefer).
+- See README.md for useful information about working on this.
+- **Never ever** remove zig-cache, nether local nor global.
+- Zig code is in ~/code/zig, don't look at /nix/...
+- remember: **mechanical copy** when porting existing stuff, no new creativity.