diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..3d8feb34
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,31 @@
+# Agent Instructions
+
+Read `CONTEXT.md` before making code changes.
+
+Follow existing project patterns. Prefer small, focused changes. Do not duplicate architecture or domain context here; keep `CONTEXT.md` as the source of truth.
+
+Before changing public APIs, build/runtime contracts, supported platforms, or architecture, update `CONTEXT.md`.
+
+## Checks
+
+Use `bun` for repo commands.
+
+Common checks:
+
+- `bun run lint`
+- `bun run check:typescript`
+- `bun run test`
+- `bun run format`
+
+For package-specific work under `packages/uniwind`, prefer targeted package scripts when available:
+
+- `bun run build`
+- `bun run check:typescript`
+- `bun run lint`
+- `bun run circular:check`
+- `bun run test:native`
+- `bun run test:web`
+- `bun run test:types`
+- `bun run test:e2e`
+
+Run relevant checks after changes when practical. Mention skipped checks in final response.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/context.md b/CONTEXT.md
similarity index 100%
rename from context.md
rename to CONTEXT.md