openrewrite · knutwannheden · Mar 6, 2026 · Mar 6, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,12 +2,6 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Important Instructions
-
-When you need to know something about OpenRewrite:
-- Refer to the rewrite-docs folder (if available)
-- Consult Architecture Decision Records in `doc/adr/` for design decisions
-
 ## Project Overview
 
 OpenRewrite is an automated refactoring ecosystem for source code that eliminates technical debt through AST-based transformations. The project uses a visitor pattern architecture where **Recipes** define transformations and **TreeVisitors** traverse and modify Abstract Syntax Trees (ASTs).
@@ -20,47 +14,7 @@ OpenRewrite is an automated refactoring ecosystem for source code that eliminate
 - **SourceFile**: Represents parsed source code as an LST (`org.openrewrite.SourceFile`)
 - **Markers**: Attach metadata to LST nodes without modifying the tree structure
 
-## General Guidelines
-
-### Code Organization
-- Code should be organized into modules based on functionality
-- Each module should have a clear responsibility
-- Follow the package structure conventions established in the project
-- Keep files focused on a single responsibility
-
-### Documentation
-- Public APIs should be documented with a brief summary at the type level and method level documentation for interfaces
-- Include examples in documentation where appropriate
-- Document complex algorithms and non-obvious code
-- Keep documentation up-to-date with code changes
-
-### Testing
-- Write tests for all new features and bug fixes
-- Aim for high test coverage
-- Tests should be comprehensive and cover edge cases
-- Use appropriate testing frameworks (JUnit for Java, Jest for TypeScript)
-
-#### RPC-based Language Tests (Python, JavaScript)
-- **CRITICAL**: Tests for RPC-based languages (like `rewrite-python`) can hang indefinitely when RPC communication fails
-- **ALWAYS** set explicit timeouts when running these tests (e.g., `timeout: 60000` for individual tests, `timeout: 120000` for small test classes)
-- Run individual tests or small test classes rather than entire test suites to avoid long-running hangs
-- If a test hangs, it usually indicates an RPC communication issue (deadlock, malformed response, etc.)
-- Common failure modes: printer bugs causing empty output, bidirectional RPC message interleaving issues
-
-### Error Handling
-- Handle errors appropriately and provide meaningful error messages
-- Use exceptions for exceptional conditions, not for control flow
-- Validate inputs and fail fast
-- Log errors with appropriate context
-
-### Task Management
-- Always check tasks in the task list when they are completed
-- Update task lists in `docs/tasks.md` to reflect current progress
-- Mark tasks as completed by changing `- [ ]` to `- [x]`
-- Keep task lists up-to-date to help track project progress
-- Ensure all subtasks are checked before marking a parent task as complete
-
-## Essential Build Commands
+## Build Commands
 
 ```bash
 # Build everything (compile + test)
@@ -72,16 +26,10 @@ OpenRewrite is an automated refactoring ecosystem for source code that eliminate
 # Run tests only
 ./gradlew test
 
-# Run all quality checks (tests, license, etc.)
-./gradlew check
-
-# Clean and rebuild
-./gradlew clean build
-
 # Install to local Maven repository
 ./gradlew publishToMavenLocal
 
-# Apply license headers to files
+# Apply license headers (run before committing)
 ./gradlew licenseFormat
 
 # Run security vulnerability check
@@ -130,21 +78,14 @@ These modules use their own package managers (`uv`/`pip` for Python, `npm` for N
 - **`rewrite-java-lombok`**: Lombok-specific Java support
 - **`rewrite-benchmarks`**: JMH performance benchmarks
 
-## Architecture Decision Records (ADRs)
-
-Significant architectural decisions are documented in `doc/adr/`. When working on features that involve architectural decisions, consult existing ADRs and create new ones as needed following the standard ADR format (Context, Decision, Consequences).
-
 ## Development Patterns
 
-### Recipe Development
-Recipes extend `org.openrewrite.Recipe` and typically contain one or more `TreeVisitor` implementations. The visitor pattern allows type-safe traversal of language-specific ASTs.
-
 ### AST Traversal
 - Use `TreeVisitor<SourceFile, ExecutionContext>` for cross-cutting concerns
 - Use language-specific visitors (e.g., `JavaIsoVisitor`) for language transformations
 - Always return modified trees; don't mutate in place
 - Return `null` from a visitor method to delete an element
-- **IMPORTANT**: Never typecast LST elements without an `instanceof` check first. The typical pattern when an LST element is not of the expected type is to return early, making no changes. For example:
+- **IMPORTANT**: Never typecast LST elements without an `instanceof` check first. Return early when the type doesn't match:
   ```java
   if (!(arg instanceof J.Lambda) || !(((J.Lambda) arg).getBody() instanceof J.Block)) {
       return m;  // Return unchanged if not the expected type
@@ -163,77 +104,16 @@ void myRecipeTest() {
 }
 ```
 
-When testing OpenRewrite parsers or recipes use `RewriteTest` and its `rewriteRun()` methods with "before" and "after" state to indicate what changes are expected and not expected to be made to source files.
-
 ### Parser Extensions
-New language support for grammars that don't have type attribution require:
+New language support requires:
 1. ANTLR grammar files (`.g4`) in `src/main/antlr/`
 2. AST model classes extending `Tree`
 3. Parser implementation extending `Parser`
 4. Visitor base classes extending `TreeVisitor`
 
-### IDE Configuration
-The project supports selective module loading via `IDE.properties` to improve IDE performance. This allows developers to work on specific modules without loading the entire multi-project build.
-
-### Quality Checks
-The build enforces license headers on all source files and runs OWASP dependency vulnerability scanning. Always run `./gradlew licenseFormat` before committing code changes.
-
-## Java Guidelines
-
-### Code Style
-- Follow standard Java naming conventions
-  - Classes: PascalCase
-  - Methods and variables: camelCase
-  - Constants: UPPER_SNAKE_CASE
-- Use 4 spaces for indentation
-- Keep lines under 120 characters
-- Use meaningful variable and method names
-
-### Java Patterns
-- Use Lombok annotations to reduce boilerplate (@Getter, @RequiredArgsConstructor, etc.)
-- Use interfaces with default methods where appropriate
-- Use @Nullable annotations for null safety
-- Use functional programming style with streams and lambdas where it improves readability
-- Prefer immutable objects where possible
-- Use the Builder pattern for complex object creation
-- Use the Visitor pattern for tree traversal and transformation
+## Conventions
 
-### Java Best Practices
-- Favor composition over inheritance
-- Use dependency injection for better testability
-- Write small, focused methods
-- Avoid mutable state where possible
-- Use appropriate data structures for the task
-- Follow the principle of least surprise
-
-## Language-Specific Guidelines
-
-For detailed guidance on working with specific language implementations, consult the module-specific CLAUDE.md files:
-
-- **Python (`rewrite-python/rewrite/CLAUDE.md`)**: Development setup, testing with RPC, recipe patterns, padding/whitespace conventions specific to the Python module.
-- **TypeScript/JavaScript (`rewrite-javascript/rewrite/CLAUDE.md`)**: Node.js setup, async visitor patterns, test patterns, RPC sender/receiver architecture, module organization.
-
-These files contain implementation-specific patterns, conventions, and debugging tips that supersede general guidance in this document.
-
-## Version Control Guidelines
-
-### Commits
-- Write clear, concise commit messages
-- Each commit should represent a logical change
-- Keep commits focused on a single task
-- Reference issue numbers in commit messages where applicable
-
-### Pull Requests
-- Write a clear description of the changes
-- Include tests for new features and bug fixes
-- Ensure all tests pass before submitting
-- Address review comments promptly
-
-## Important Conventions
-
-### Nullability Annotations
-The project uses JSpecify nullability annotations.
-
-## Conclusion
-
-Following these guidelines will help maintain code quality and consistency across the OpenRewrite project. These guidelines are not exhaustive, and common sense should be applied when making decisions not covered here.
+- The project uses **JSpecify** nullability annotations
+- The build enforces license headers — run `./gradlew licenseFormat` before committing
+- Consult Architecture Decision Records in `doc/adr/` for design decisions
+- The project supports selective module loading via `IDE.properties` to improve IDE performance