diff --git a/CLAUDE.md b/CLAUDE.md
index d2aeb9b6..5eae1367 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -166,7 +166,7 @@ cd frontend && npm run build
 
 # Database migrations
 cd backend && alembic upgrade head
-alembic revision --autogenerate -m "Description"
+alembic revision --autogenerate -m "Description" --rev-id=NNN  # NNN = next sequential number
 
 # Access PostgreSQL
 docker exec -it patherly_postgres psql -U postgres -d patherly
@@ -304,6 +304,8 @@ navigate(`/trees/${newTree.id}/edit`)
 
 **37. First deployed user needs manual admin promotion:** New users default to `engineer` role. Promote via SQL: `UPDATE users SET role = 'admin' WHERE email = '...';` then re-login for new JWT.
 
+**38. Alembic migrations MUST use sequential numbered prefixes:** Check `backend/alembic/versions/` for the highest numbered migration and use the next number. Format: `XXX_descriptive_name.py` (e.g., `040_add_whatever.py`). NEVER use auto-generated revision IDs like `0f1ca2af3647`. Always pass `--rev-id` flag: `alembic revision --autogenerate -m "desc" --rev-id=040`.
+
 ---
 
 ## RBAC & Permissions