diff --git a/CLAUDE.md b/CLAUDE.md
index 8aba87af..d52e8b84 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,6 +51,48 @@ go test ./...
 
 **Important:** The `LLGO_ROOT` environment variable must be set to the repository root when running llgo commands during development.
 
+### Update out.ll files after modifying compiler IR generation
+
+**CRITICAL:** When you modify the compiler's IR generation logic (especially in `ssa/` or `cl/` packages), you MUST update all out.ll test files under the `cl/` directory.
+
+#### Understanding out.ll files
+
+The `out.ll` files under the `cl/` directory are comparison IR files that serve as reference outputs for the test suite:
+- They are generated by `llgen` from the corresponding `in.go` files in the same directory
+- They reflect the current compiler's LLVM IR representation of the Go source code
+- They are used by tests to verify that the compiler generates correct and consistent IR output
+
+#### Required steps after modifying IR generation logic
+
+1. **Reinstall llgen** to apply your compiler changes:
+   ```bash
+   go install -v ./chore/llgen
+   ```
+
+2. **Regenerate all out.ll files** under the `cl/` directory:
+   ```bash
+   # llgen automatically finds and updates all test cases
+   llgen
+   ```
+   Or you can regenerate specific test directories:
+   ```bash
+   llgen cl/_testgo/interface
+   llgen cl/_testrt/tpmethod
+   ```
+
+3. **Verify the changes** make sense by reviewing the diff in the out.ll files
+
+4. **Commit the updated out.ll files** along with your compiler changes
+
+#### Why this matters
+
+Failing to update out.ll files after modifying IR generation will cause test failures in `TestFromTestgo` and `TestFromTestrt`. This process ensures that:
+- The test suite reflects the current compiler behavior
+- Changes to IR generation are properly documented and reviewed
+- Future regressions can be detected by comparing against the reference output
+
+**Pro tip:** Always check if your changes affect IR generation. If you're unsure, run the tests first - they will fail if out.ll files need updating.
+
 ## Code Quality
 
 Before submitting any code updates, you must run the following formatting and validation commands: