1 files changed, 22 insertions, 1 deletions
diff --git a/AGENTS.md b/AGENTS.md
index 653e8f3..3cd9aa7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -255,11 +255,32 @@ States:
 
 ```
 .tasks/
-├── tasks.jsonl    # Git-tracked, source of truth
+├── tasks.jsonl       # Git-tracked, production database
+├── tasks-test.jsonl  # Test database (not tracked, auto-created)
 ```
 
 Each line in `tasks.jsonl` is a JSON object representing a task.
 
+## Testing and Development
+
+**IMPORTANT**: When writing or testing code that modifies tasks, use the test database:
+
+```bash
+# Set test mode to protect production database
+export TASK_TEST_MODE=1
+
+# Now all task operations use .tasks/tasks-test.jsonl
+task create "Test task" --type=task
+task list
+
+# Unset when done
+unset TASK_TEST_MODE
+```
+
+**The test suite automatically uses test mode** - you don't need to set it manually when running `task test` or `bild --test Omni/Task.hs`.
+
+**Never run destructive tests against the production database** (`.tasks/tasks.jsonl`) as this will delete real task data.
+
 ## Example Session
 
 ```bash