diff --git a/.claude/rules/linting.md b/.claude/rules/linting.md
new file mode 100644
index 000000000..dcc4adb01
--- /dev/null
+++ b/.claude/rules/linting.md
@@ -0,0 +1,10 @@
+# Linting Rules
+
+Before committing Go code changes:
+
+1. Run `cd src && make lint` to check for lint errors
+2. Run `cd src && make lint-fix` to auto-fix issues
+3. Do NOT use `--no-verify` to skip pre-commit hooks
+4. Do NOT commit code that fails `golangci-lint`
+
+The PostToolUse hook auto-runs golangci-lint on edited Go files, but always verify with a full lint pass before committing.
diff --git a/.claude/settings.json b/.claude/settings.json
index d1f74d0bf..14ec32ad2 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -19,5 +19,19 @@
       "Bash(tail:*)",
       "Bash(xxd:*)"
     ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE=$(jq -r '.tool_input.file_path // empty' 2>/dev/null); if [ -n \"$FILE\" ] && echo \"$FILE\" | grep -qE '/src/.*\\.go$'; then PKG=$(dirname \"$FILE\" | sed 's|.*/src/||'); cd src && golangci-lint run --fix \"./$PKG/...\" 2>/dev/null || true; fi",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
   }
 }
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..fddd5016d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,16 @@
+# Agents (Codex)
+
+## Linting
+
+- MUST run `cd src && make lint` before committing any Go changes
+- MUST run `cd src && make lint-fix` to auto-fix lint issues when lint fails
+- MUST NOT use `--no-verify` on git commits
+
+## Testing
+
+- MUST run `cd src && make test` before pushing
+- Use `-short` flag for unit tests: `cd src && go test -short ./...`
+
+## Git Hooks
+
+Git hooks are configured via `core.hooksPath`. Run `make install-git-hooks` if hooks are not active.
diff --git a/Makefile b/Makefile
index ad8a040b2..9cbf250d8 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,6 @@
 .PHONY: install-git-hooks
 install-git-hooks:
-	printf "#!/bin/sh\nmake pre-commit" > .git/hooks/pre-commit
-	chmod +x .git/hooks/pre-commit
-	printf "#!/bin/sh\nmake pre-push" > .git/hooks/pre-push
-	chmod +x .git/hooks/pre-push
+	git config core.hooksPath scripts
 
 .PHONY: pre-commit
 pre-commit:
diff --git a/scripts/pre-commit b/scripts/pre-commit
new file mode 100755
index 000000000..33e97a95d
--- /dev/null
+++ b/scripts/pre-commit
@@ -0,0 +1,5 @@
+#!/bin/sh
+# Pre-commit hook: lint changed Go files in src/
+if git diff --cached --name-only | grep -q '^src/'; then
+    make -C src lint
+fi
diff --git a/scripts/pre-push b/scripts/pre-push
new file mode 100755
index 000000000..863c4dc39
--- /dev/null
+++ b/scripts/pre-push
@@ -0,0 +1,3 @@
+#!/bin/sh
+# Pre-push hook: run tests before pushing
+make pre-push