diff --git a/CLAUDE.md b/CLAUDE.md
index fe9dfb1..4f92752 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,3 +14,25 @@
   output by the linter is something that legitimately needs fixing in the
   code.
 
+* when running tests, use `make test`.
+
+* before commits, run `make check`.  this runs `make lint` and `make test`
+  and `make check-fmt`.  any issues discovered must be resolved before
+  committing unless explicitly told otherwise.
+
+* when fixing a bug, write a failing test for the bug FIRST.  add
+  appropriate logging to the test to ensure it is written correctly.  commit
+  that.  then go about fixing the bug until the test passes (without
+  modifying the test further).  then commit that.
+
+* when adding a new feature, do the same - implement a test first (TDD).  it
+  doesn't have to be super complex.  commit the test, then commit the
+  feature.
+
+* when adding a new feature, use a feature branch.  when the feature is
+  completely finished and the code is up to standards (passes `make check`)
+  then and only then can the feature branch be merged in to `main` and the
+  branch deleted.
+
+* write godoc documentation comments for all exported types and functions as
+  you go along.