diff --git a/CLAUDE.md b/CLAUDE.md
index 41be5d3..3807399 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -378,6 +378,16 @@ Or use `scripts/generate-package-exports.mjs` to auto-generate exports.
 - Mock external dependencies appropriately
 - Use path helpers for cross-platform tests
 
+### Test Style — Functional Over Source Scanning
+
+**NEVER write source-code-scanning tests**
+
+Do not read source files and assert on their contents (`.toContain('pattern')`). These tests are brittle and break on any refactor.
+
+- Write functional tests that verify **behavior**, not string patterns
+- For modules requiring a built binary: use integration tests
+- For pure logic: use unit tests with real function calls
+
 #### Running Tests
 
 - **All tests**: `pnpm test`