docs: streamline CLAUDE.md based on benchmark findings (#1604)

Apply recommendations from CLAUDE.md benchmarking study (1,188 tests
across 3 models): remove redundant generic instructions, reframe
prohibitions as positive directives, trim inferable content, and
keep only project-specific knowledge that Claude cannot derive from
the codebase itself. Reduces file from 142 to 64 lines.

Key changes:
- Remove Common Pitfalls (negative framing, generic, duplicated)
- Remove Available Tools section (redundant with system prompt)
- Trim build commands to project-specific flags only
- Collapse Technology Stack into one-line overview
- Reframe security directives from "never do X" to "do Y instead"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Lukasz Lenart
2026-03-02 12:31:16 +01:00
committed by GitHub
parent 4d2eb93835
commit 4d96950c51
+11 -79
View File
@@ -6,38 +6,19 @@ For detailed procedures, use the specialized agents and commands in `.claude/age
## Project Overview
Apache Struts is a mature MVC web application framework for Java (originally WebWork 2). Current version: *
*7.2.0-SNAPSHOT**.
Apache Struts is a mature MVC web application framework for Java (originally WebWork 2). Current version: **7.2.0-SNAPSHOT**. Uses OGNL for value stack expressions and FreeMarker for UI tag templates.
### Build Commands
```bash
# Full build with tests
mvn clean install
# Run all tests (faster, skips assembly)
# Run tests (skip assembly for speed)
mvn test -DskipAssembly
# Run single test class
mvn test -DskipAssembly -Dtest=MyClassTest
# Single test in specific module
mvn test -DskipAssembly -pl core -Dtest=MyClassTest#testMethodName
# Run single test method
mvn test -DskipAssembly -Dtest=MyClassTest#testMethodName
# Run tests in a specific module
mvn test -DskipAssembly -pl core
# Build without tests
mvn clean install -DskipTests
# Build with code coverage (JaCoCo)
mvn clean install -Pcoverage
# Build with Jakarta EE 11 (Spring 7)
# Jakarta EE 11 / Spring 7 profile
mvn clean install -Pjakartaee11
# Run OWASP dependency vulnerability check
mvn verify -Pdependency-check
```
### Project Structure
@@ -57,13 +38,6 @@ struts/
**Request Lifecycle**: `Dispatcher``ActionProxy``ActionInvocation` → Interceptor stack → `Action` → Result
Key components:
- **ActionSupport**: Base class for actions (validation, i18n, messages)
- **ActionContext**: Thread-local context with request/response/session data
- **Interceptors**: Cross-cutting concerns (validation, file upload, security, params)
- **Results**: Response handlers (dispatcher, redirect, json, stream)
Key packages in `org.apache.struts2`:
- `dispatcher` - Request handling, `Dispatcher`, servlet integration
@@ -72,22 +46,14 @@ Key packages in `org.apache.struts2`:
- `action` - Action interfaces (`UploadedFilesAware`, `SessionAware`, etc.)
- `security` - Security utilities and OGNL member access policies
### Technology Stack
- **Java 17+** with Jakarta EE 10 (Servlet 6.0, JSP 3.1)
- **OGNL** - Expression language for value stack access
- **FreeMarker** - Default template engine for UI tags
- **Commons FileUpload2** - File upload handling
- **Log4j2/SLF4J** - Logging
## Security-Critical Patterns
Apache Struts has a history of security vulnerabilities. Follow these strictly:
Apache Struts has a history of security vulnerabilities (OGNL injection, temp file exploits). Apply these Struts-specific patterns:
1. **Temporary files**: Never use system temp directory; use UUID-based names in controlled locations
2. **OGNL expressions**: Never evaluate user-controlled OGNL; use allowlist member access
1. **Temporary files**: Use UUID-based names in controlled locations (see example below)
2. **OGNL expressions**: Evaluate only framework-generated OGNL; use allowlist member access
3. **File uploads**: Validate content types, sanitize filenames, enforce size limits
4. **Parameter injection**: Use `ParameterNameAware` to filter dangerous parameter names
4. **Parameter filtering**: Use `ParameterNameAware` to restrict accepted parameter names
```java
// Secure temporary file pattern
@@ -97,46 +63,12 @@ protected File createTemporaryFile(String fileName, Path location) {
}
```
Run `/security_scan` for comprehensive security analysis.
## Testing
**Priority order for running tests:**
1. **JetBrains MCP** (in IntelliJ): `mcp__jetbrains__execute_run_configuration`
2. **test-runner agent**: `Task` tool with `subagent_type="test-runner"`
3. **Direct Maven**: `mvn test -DskipAssembly -Dtest=TestClassName`
Tests use JUnit 5 with AssertJ assertions and Mockito for mocking.
## Available Tools
### Commands
- `/security_scan` - OGNL injection, CVE detection, security analysis
- `/quality_check` - JavaDoc compliance, coding standards
- `/config_analyze` - struts.xml validation, interceptor analysis
- `/create_plan` / `/validate_plan` - Implementation planning
- `/research_codebase` - Codebase exploration
### Specialized Agents
- `test-runner` - Maven test execution (use this to RUN tests)
- `security-analyzer` - Security vulnerability scanning
- `codebase-locator` - Find files, classes, implementations
- `codebase-pattern-finder` - Find similar code patterns
- `config-validator` - Validate Struts configuration files
Tests use JUnit 5 with AssertJ assertions and Mockito for mocking. Run with `mvn test -DskipAssembly`.
## Pull Requests
- **Title format**: `WW-XXXX Description` (Jira ticket ID required)
- **Link ticket in description**: `Fixes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`
- **Issue tracker**: https://issues.apache.org/jira/projects/WW
## Common Pitfalls
1. Never use `File.createTempFile()` without controlling the directory
2. Always clean up temporary files (track and delete in finally blocks)
3. Test error paths and cleanup behavior, not just happy paths
4. Don't catch generic `Exception` - catch specific types
5. Use `protected` visibility for methods subclasses may override
- **Issue tracker**: https://issues.apache.org/jira/projects/WW