diff --git a/CLAUDE.md b/CLAUDE.md
index 70fb63316..c91c27a7b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -296,6 +296,16 @@ Socket CLI has different update mechanisms depending on installation method:
 - Fixtures in `test/fixtures/`
 - Coverage reporting available
 
+### 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
+
 ### External Dependencies
 
 - Vendored modules in `src/external/` (e.g., ink-table)