mirror of
https://github.com/apache/struts.git
synced 2026-08-05 14:47:09 +00:00
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:
@@ -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
|
||||
Reference in New Issue
Block a user