diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..732881e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,26 @@
+# AGENTS.md
+
+## Project
+
+A sidecar for Home Assistant that runs automations using arrowized functional
+reactive programming (AFRP). Haskell, built with cabal.
+
+## Code style
+
+- Vertical modules: split by feature/concept, not by layer.
+- Comments are minimal. They describe the contract, not the implementation,
+  and should stay stable as the implementation changes.
+
+## Build
+
+- Nix-backed project: `flake.nix` provides the devShell, `default.nix` is the
+  generated cabal derivation.
+- Always run cabal through the devShell: `nix develop -c cabal build`.
+- After adding dependencies to the .cabal file, regenerate the derivation:
+  `nix run nixpkgs#cabal2nix -- ./. > default.nix`. Do not edit it by hand.
+- `secrets.yaml` is sops-encrypted. Never read, print, or commit its contents.
+
+## Tests
+
+- hspec for unit tests, hedgehog for property tests.
+- Run with `nix develop -c cabal test`.