diff --git a/CLAUDE.md b/CLAUDE.md
index 88a523d7..bc937fbe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -245,6 +245,16 @@ if (isCoverageMode) {
 - **Cross-platform**: Test path handling on Windows and Unix
 - **Follow patterns**: See `test/unit/getapi-sendapi-methods.test.mts` for examples
 
+### 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
+
 ### CI Testing
 
 - **🚨 MANDATORY**: `SocketDev/socket-registry/.github/workflows/ci.yml@<SHA>` with full SHA