diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..e0dd4bba1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,10 @@
+* Brevity is good.
+* Assume that the maintainers and readers of the code you write are Go experts:
+   * Don't use comments to explain the obvious.
+   * Use self-explanatory variable and function names.
+   * Use short variable names when the context is clear.
+* Never export symbols that's not needed outside of the package.
+* Avoid global state at (almost) all cost.
+* This is a project with a long history; assume that a similiar problem has been solved before, look hard for helper functions before creating new ones.
+* Use `go test ./somepackage/...` when iterating.
+* Use `mage check` when you're done.
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..43c994c2d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md