This is an automated email from the ASF dual-hosted git repository.
zhangliang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 4a532606d9e Update CLAUDE.md (#37067)
4a532606d9e is described below
commit 4a532606d9efa8683ca1e23509c58eb4ee636f16
Author: Liang Zhang <[email protected]>
AuthorDate: Tue Nov 11 02:44:15 2025 +0800
Update CLAUDE.md (#37067)
* Update CLAUDE.md
* Update CLAUDE.md
---
CLAUDE.md | 855 ++++++++++++++++++++++++++------------------------------------
1 file changed, 361 insertions(+), 494 deletions(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index 2f01bc73eec..cf892ca2e3a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,573 +1,440 @@
-# CLAUDE.md - ShardingSphere AI Development Guide
-
-**ShardingSphere**: Distributed SQL engine for data sharding, distributed
transactions, encryption, masking, and more.
-Built on Database Plus concept - unified data access layer over existing
databases.
-
-## Part 1: Core Principles & Quick Reference
-
-### Project Essentials
-- **Core Concepts**: Connect (protocol adaptation), Enhance (feature plugins),
Pluggable (micro-kernel architecture)
-- **Development Philosophy**: High-quality, self-documenting, 100% tested code
-- **Team Culture**: Quality-first, detail-oriented, systematic approach
-
-### The Five Core Principles ๐ฅ
-
-1. **Code Self-Documentation**
- - Zero inline comments - code explains itself through clear naming
- - Extract complex logic to well-named methods (see Self-Documentation
Patterns in Part 2)
- - Use factory methods for object creation
-
-2. **100% Test Coverage**
- - Every line, branch, and method must be tested
- - Coverage-driven development - use JaCoCo reports to guide testing (see
Part 2: Coverage Tools Reference)
- - Focus on branch coverage, eliminate redundant tests
-
-3. **Follow Project Standards**
- - Match existing code patterns and naming conventions
- - Use established architectural patterns (SPI, builder, immutable design)
- - Maintain consistency with similar components
-
-4. **Work Within Scope**
- - Only make changes within explicit task boundaries
- - No "helpful" refactoring or improvements
- - Never create unrelated files
-
-5. **Format Before Completion**
- - Always run `./mvnw spotless:apply -Pcheck` before task completion
- - Ensure all modified code follows project formatting
-
-### Task Classification Standards
-
-#### Task Type Identification
-
-**Source Code Tasks**
-- **File Patterns**: `**/src/main/java/**/*.java`,
`**/src/test/java/**/*.java`, `**/pom.xml`
-- **Impact**: Code compilation, test execution, coverage analysis,
functionality
-- **Examples**: New feature development, bug fixes, test improvements,
configuration changes
-
-**Documentation Tasks**
-- **File Patterns**: `**/*.md`, `docs/**/*`, `**/README*`, `.github/**/*.md`
-- **Impact**: Content accuracy, user experience, knowledge transfer
-- **Examples**: API documentation, user guides, architecture docs, release
notes
-
-**Mixed Tasks**
-- **Characteristics**: Involves both source code and documentation changes
-- **Approach**: Apply combined validation based on changed file types
-- **Examples**: Feature additions with documentation, API changes with examples
-
-#### Differentiated Validation Standards
-
-**Source Code Task Requirements**
-- โ
100% test coverage (JaCoCo validation)
-- โ
Code compilation and build success
-- โ
Code formatting with Spotless
-- โ
All quality checks pass (Checkstyle, etc.)
-- โ
Self-documenting code with zero inline comments
-
-**Documentation Task Requirements**
-- โ
Link validity verification
-- โ
Markdown format consistency
-- โ
Content accuracy review
-- โ
Spelling and grammar check
-- โ No test coverage or compilation required
-
-**Mixed Task Requirements**
-- Apply source code standards to `.java` files
-- Apply documentation standards to `.md` files
-- Ensure consistency between code and documentation changes
-
-### Quick Checklists
-
-#### Before Starting Any Task
-- [ ] Re-read relevant sections of this guide
-- [ ] **Identify task type**: Source code, documentation, or mixed task
-- [ ] Understand the success criteria and validation requirements for your
task type
-- [ ] Review specific standards for your task type
-
-#### Before Task Completion
-
-**For Source Code Tasks:**
-- [ ] All validation requirements from Differentiated Validation Standards
(Lines 60-77)
-- [ ] Additional cleanup: Remove unused mocks, imports, and dead code
-- [ ] Optimize mock configurations and branch coverage
-
-**For Documentation Tasks:**
-- [ ] All validation requirements from Differentiated Validation Standards
(Lines 60-77)
-- [ ] Test code examples and snippets when applicable
-
-**For Mixed Tasks:**
-- [ ] Apply source code standards to `.java` files
-- [ ] Apply documentation standards to `.md` files
-- [ ] Ensure consistency between code and documentation changes
-
-### Common Pitfalls to Avoid
-- **Internal blank lines** in methods - extract private methods instead
-- **Variable naming confusion** - use `actual` in tests, `result` in production
-- **Early test exits** - configure mocks properly to reach target code
-- **Surface-level coverage** - verify actual coverage improvement with JaCoCo
-
-#### Code Cleanup Standards
-- **Dead Mock Objects**: Remove all mock objects never referenced in tests
-- **Unused Imports**: Remove imports that are not used in the file
-- **Redundant Mock Setup**: Extract common mock configurations to private
methods
-- **Unreachable Code**: Remove any code that can never be executed
-- **Duplicate Test Logic**: Eliminate tests that don't improve branch coverage
-
----
-
-## Part 2: Development Process & Quality Standards
-
-### Unified Development Workflow
-
-```mermaid
-graph LR
-A[Analyze Task] --> B[Identify Task Type]
-B --> C[Choose Validation Strategy]
-C --> D[Design & Implement]
-D --> E[Task-Specific Validation]
-E --> F[Format Code]
-F --> G[Complete]
+# CLAUDE.md - ShardingSphere AI Programming Guide
+
+*AI Programming Guide for ShardingSphere Code Development*
+
+## ๐ค AI Usage Guidelines
+
+### Core Principles
+- **AI-First Principle**: All content in this document is oriented towards AI
programming assistants, not human developers
+- **Actionability Priority**: Every instruction must be directly executable by
AI, avoid theoretical descriptions
+- **Unambiguous Expression**: Use clear instructions and parameterized
templates, avoid vague expressions
+- **Search Efficiency Priority**: Information organization facilitates AI
quick positioning, reduces understanding cost
+
+### Content Standards
+- **Accuracy Priority**: All information must be correct and verifiable, no
exaggeration or beautification
+- **Practicality Priority**: Focus on actual effects, avoid exaggerated
expressions
+- **Problem-Oriented**: Directly address problem essence, provide actionable
solutions
+- **Concise and Clear**: Use most direct language to express core information
+
+### Response Style Standards
+- **In-depth Analysis**: Conduct deep analysis based on code logic and project
specifications, avoid surface-level answers
+- **Factual and Realistic**: Present facts and data, do not exaggerate
achievements, do not hide problems
+- **Reasoned Debate**: When facing programmer's misconceptions, engage in
well-reasoned debates based on technical standards and best practices
+- **Timely Correction**: When facing AI inference errors, immediately admit
mistakes and correct them to maintain technical accuracy
+
+### Quick Search Mapping
+- "Create rule change processor" โ Code Templates.Rule Change Processor
Template
+- "Write test methods" โ Code Templates.Test Method Template
+- "Mock external dependencies" โ Code Templates.Mock Configuration Template
+- "Coverage check" โ Quick Commands Reference.Validation Commands
+- "Format code" โ Quick Commands Reference.Validation Commands
+
+### AI Decision Rules
+```yaml
+task_type_detection:
+ if contains(["src/main/java"], ["*.java"]): "source_code_task"
+ if contains(["src/test/java"], ["*Test.java"]): "test_task"
+ if contains(["*.md"], ["docs/"]): "documentation_task"
+
+validation_rules:
+ source_code_task: ["100% test coverage", "code formatting",
"self-documenting"]
+ test_task: ["branch coverage", "mock configuration", "assertion correctness"]
+ doc_task: ["link validity", "format consistency"]
+
+decision_logic:
+ if task_type == "source_code": apply source code task workflow
+ if task_type == "test": apply test task workflow
+ if involves_external_dependencies: use MockedConstruction template
```
-#### Task-Specific Workflows
-
-**Source Code Tasks:**
-1. Analyze Task โ Identify as Source Code โ Coverage Analysis โ Design &
Implement โ Verify Coverage โ Format Code โ Complete
+## โก Quick Commands Reference
-**Documentation Tasks:**
-1. Analyze Task โ Identify as Documentation โ Content Review โ Design &
Implement โ Content Validation โ Format Check โ Complete
-
-**Mixed Tasks:**
-1. Analyze Task โ Identify as Mixed โ Combined Strategy โ Design & Implement โ
Multi-Type Validation โ Format & Complete โ Complete
-
-### Simplified Testing Process
-
-#### Step 1: Analyze & Design
-- **Code Flow Analysis**: Understand complete execution paths
-- **Coverage Gap Identification**: Use JaCoCo to find uncovered branches
-- **Dependency Mapping**: Identify all mocks needed for complete chain
-- **Test Scenarios**: Design realistic business cases for uncovered branches
(see Mock Configuration Standards)
-
-#### Step 2: Implement & Verify
-- **Mock Configuration**: Set up complete dependency chains with
`RETURNS_DEEP_STUBS`
-- **Test Implementation**: Write tests targeting specific uncovered branches
-- **Coverage Validation**: Run tests and verify coverage improvement
-- **Iteration**: Add tests until 100% coverage achieved
+### Build Commands
+```bash
+./mvnw install -T1C # Full build
+./mvnw install -T1C -DskipTests # Build without tests
+```
-#### Step 3: Coverage Confirmation
+### Validation Commands
```bash
-# Verify class coverage
+./mvnw spotless:apply -Pcheck # Format code
./mvnw test jacoco:check@jacoco-check -Pcoverage-check -Djacoco.skip=false \
- -Djacoco.check.class.pattern=your.target.ClassName \
- -pl your-module
+ -Djacoco.check.class.pattern=${ClassName} -pl ${submodule} # Coverage check
-# Verify package coverage
-./mvnw test jacoco:check@jacoco-check -Pcoverage-check -Djacoco.skip=false \
- -Djacoco.check.class.pattern="your.package.**" \
- -Djacoco.minimum.coverage=1.00 \
- -pl your-module
+# Placeholder instructions:
+# ${ClassName} - Specific class name for coverage check (e.g.,
ShardingRuleService)
+# ${submodule} - Specific submodule name (e.g., shardingsphere-jdbc,
shardingsphere-proxy)
```
-- **BUILD SUCCESS**: Coverage meets requirements
-- **BUILD FAILURE**: Review `module/target/site/jacoco/index.html` for
uncovered lines
+### Troubleshooting Commands
+```bash
+./mvnw clean test jacoco:report -Djacoco.skip=false -pl ${submodule} #
Generate coverage report
+open ${submodule}/target/site/jacoco/index.html # View
coverage details
+```
-### Code Quality Standards
+## ๐ Code Templates
-#### Self-Documentation Patterns
+### Rule Change Processor Template
```java
-// โ WRONG - Inline comments
-// Check if user is admin and has permission
-if (user.isAdmin() && user.hasPermission()) {
- // ...
-}
+package org.apache.shardingsphere.${module}.rule.changed;
-// โ
RIGHT - Self-documenting code
-if (userIsAdminWithPermission()) {
- // ...
-}
+import
org.apache.shardingsphere.infra.algorithm.core.processor.AlgorithmChangedProcessor;
+import org.apache.shardingsphere.mode.spi.rule.RuleChangedItemType;
+import
org.apache.shardingsphere.${module}.api.config.${RuleType}RuleConfiguration;
+import org.apache.shardingsphere.${module}.rule.${RuleType}Rule;
-// Extract complex logic to private methods
-private boolean userIsAdminWithPermission() {
- return user.isAdmin() && user.hasPermission();
-}
-```
+import java.util.Map;
-#### Naming Conventions
-- **Test methods**: `assert[MethodName]With[Condition]` pattern
-- **Test variables**: Use `actual` for assertions, `result` for production code
-- **Factory methods**: Describe object creation intent
-- **Private methods**: Explain what logic they encapsulate
+/**
+ * ${AlgorithmType} algorithm changed processor.
+ */
+public final class ${AlgorithmType}AlgorithmChangedProcessor extends
AlgorithmChangedProcessor<${RuleType}RuleConfiguration> {
-#### Comprehensive Test Patterns
-```java
-// Standard test structure (Given-When-Then)
-@Test
-void assertMethodWithCondition() {
- // Given - setup complete mock chain
- mockDependencyChain();
+ public ${AlgorithmType}AlgorithmChangedProcessor() {
+ super(${RuleType}Rule.class);
+ }
- // When - call method directly
- MyResult actual = target.methodUnderTest(input);
+ @Override
+ protected ${RuleType}RuleConfiguration createEmptyRuleConfiguration() {
+ return new ${RuleType}RuleConfiguration();
+ }
- // Then - assert with Hamcrest
- assertThat(actual, is(expectedResult));
+ @Override
+ protected Map<String, AlgorithmConfiguration>
getAlgorithmConfigurations(final ${RuleType}RuleConfiguration
currentRuleConfig) {
+ return currentRuleConfig.get${AlgorithmType}Algorithms();
+ }
+
+ @Override
+ public RuleChangedItemType getType() {
+ return new RuleChangedItemType("${ruleType}",
"${algorithmType}_algorithms");
+ }
}
+```
-// Branch-focused test patterns for utility classes
+### Test Method Template
+```java
@Test
-void assertMethodWithConditionTruePathExpectsResult() {
- // Given - configure mocks for true branch
- mockConditionReturnsTrue();
-
- // When - call method that hits the true branch
- MyResult actual = utilityClass.methodWithCondition(input);
+void assert${MethodName}With${Condition}Expects${Result}() {
+ // Given
+ ${MockSetup}
- // Then - verify true branch result
- assertThat(actual, is(expectedTrueResult));
-}
+ // When
+ ${ActualCall}
-// Advanced branch testing naming
-@Test
-void assert[MethodName]When[BranchCondition]Expects[Result]() {
- // Given - setup for specific branch condition
- // When - execute method
- // Then - verify expected result for this branch
+ // Then
+ assertThat(${actual}, is(${expected}));
}
```
-#### Test Organization Principles
-- **Branch-first naming**:
`assert[MethodName]When[BranchCondition]Expects[Result]`
-- **One test per branch**: Each test should target a specific conditional
branch
-- **Minimal test count**: Avoid redundant tests that don't improve branch
coverage
-- **Test isolation**: Each test controls specific constructor and method
behaviors
-- **Resource management**: Always clean up MockedConstruction with
try-with-resources
-- **Verification focus**: Each test validates one specific branch outcome
+### Mock Configuration Template
-#### Mock Configuration Standards
-```java
-// โ
Complete dependency chain
-when(dependencyA.getDependencyB().process(input)).thenReturn(result);
+**Mock Usage Boundary Principles:**
+- โ
**No Mock Needed**: Simple objects (String, basic types, DTOs, POJOs),
stateless utility classes, configuration objects
+- โ
**Mock Required**: Complex external dependencies (database connections,
network services, file systems), third-party interfaces, SPI services, stateful
objects
+- โ
**Judgment Criteria**: If object construction cost is high or has external
dependencies, Mock is needed
-// โ
Self-documenting mock setup
-private void mockUserPermissionService() {
- when(userPermissionService.hasAdminPermission(any())).thenReturn(true);
-}
+```java
+// Basic Mock configuration - for interface method Mock
+when(dependency.${method}(any())).thenReturn(${result});
-// โ
Constructor mocking for utility classes
-try (MockedConstruction<DatabaseTypeRegistry> mocked =
mockConstruction(DatabaseTypeRegistry.class, (mock, context) -> {
- DialectDatabaseMetaData dialectDatabaseMetaData =
mock(DialectDatabaseMetaData.class, RETURNS_DEEP_STUBS);
-
when(dialectDatabaseMetaData.getConnectionOption().isInstanceConnectionAvailable()).thenReturn(true);
-
when(mock.getDialectDatabaseMetaData()).thenReturn(dialectDatabaseMetaData);
+// Complex dependency Mock - for constructor objects that need Mock
+try (MockedConstruction<${ClassName}> mocked =
mockConstruction(${ClassName}.class, (mock, context) -> {
+ ${DependencyChainSetup}
+ when(mock.${getMethod}()).thenReturn(${mockResult});
})) {
- // Test code that instantiates DatabaseTypeRegistry
+ // Test code - code paths involving new ${ClassName}()
}
-// โ
Complex external dependency mocking
-try (MockedConstruction<ExternalClass> mocked =
mockConstruction(ExternalClass.class, (mock, context) -> {
- when(mock.getExternalCondition()).thenReturn(true);
-
when(mock.getDialectDatabaseMetaData().getConnectionOption().isInstanceConnectionAvailable()).thenReturn(false);
-})) {
- boolean actual = UtilityClass.staticMethodWithExternalDependency();
- assertThat(actual, is(expected));
+// Mock configuration example comparison:
+// โ No Mock needed - simple objects
+String result = "testValue"; // Direct creation
+Map<String, Object> config = new HashMap<>(); // Direct creation
+
+// โ
Mock needed - complex dependencies
+when(dataSource.getConnection()).thenReturn(mockConnection); // External
dependency
+try (MockedConstruction<DatabaseMetaData> mocked =
mockConstruction(DatabaseMetaData.class)) {
+ // Constructor needs Mock case
}
```
-#### Advanced Mock Configuration with MockedConstruction
-Use `MockedConstruction` when testing code that creates objects with `new`:
-- **Constructor interception**: Control how dependency objects are created
-- **Complete call chain**: Configure full dependency paths with
`RETURNS_DEEP_STUBS`
-- **Try-with-resources**: Automatically clean up mock constructions
-- **Utility class testing**: Perfect for static utility methods with external
dependencies
-
-#### Mock Configuration Strategies
-- **Deep stubs**: Use `RETURNS_DEEP_STUBS` for complex nested dependencies
-- **Resource management**: Always use try-with-resources for MockedConstruction
-- **Behavior isolation**: Each test controls specific constructor behaviors
-- **Constructor identification**: Look for `new SomeClass()` in target methods
-
-#### MockedStatic vs MockedConstruction
-- **MockedStatic**: For static method calls (`UtilityClass.staticMethod()`)
-- **MockedConstruction**: For object creation (`new UtilityClass()`)
-- **Placement**: MockedConstruction must wrap the code that creates the objects
-
-#### Assertion Style (Mandatory)
+### SPIๅฎ็ฐๆจกๆฟ
```java
-// โ
Use Hamcrest matchers for readability
-assertThat(actual, is(expected));
-assertThat(actualList, hasSize(expectedSize));
-
-// โ Avoid JUnit assertions (except boolean/null)
-// assertEquals(actual, expected); // Not preferred
-```
-
-### Coverage Tools Reference
-
-#### Essential Commands
-```bash
-# Generate coverage report
-./mvnw clean test jacoco:report -Djacoco.skip=false -pl module-path
-
-# Check specific class coverage
-./mvnw test jacoco:check@jacoco-check -Pcoverage-check -Djacoco.skip=false \
- -Djacoco.check.class.pattern=com.example.ClassName
-
-# Verify package coverage with 100% requirement
-./mvnw test jacoco:check@jacoco-check -Pcoverage-check -Djacoco.skip=false \
- -Djacoco.check.class.pattern="com.example.**" \
- -Djacoco.minimum.coverage=1.00
-
-# Format code
-./mvnw spotless:apply -Pcheck
-
-# Full build with tests
-./mvnw install -T1C
-```
-
-#### Coverage Patterns
-```bash
-# Package level coverage
--Djacoco.check.class.pattern="com.example.**"
-
-# By type coverage
--Djacoco.check.class.pattern="**/*Service"
-
-# Multiple patterns
--Djacoco.check.class.pattern="**/*Service,**/*Manager"
-```
-
-#### Coverage Interpretation
-- **Target**: 100% instruction, line, branch, and method coverage
-- **Validation**: Must verify improvement with JaCoCo HTML reports
-- **Focus**: Branch coverage over redundant line coverage
-- **Strategy**: Minimal tests targeting specific uncovered branches
-- **BUILD SUCCESS**: Coverage meets requirements
-- **BUILD FAILURE**: Review `module/target/site/jacoco/index.html` for
uncovered lines
+package org.apache.shardingsphere.${module}.spi;
+
+@TypedSPI
+public final class ${SPIName}Impl implements ${SPIName}SPI {
+ @Override
+ public ${ResultType} execute(${ContextType} context) {
+ // ๅฎ็ฐ้ป่พ
+ return ${result};
+ }
-#### Advanced Coverage Strategies
-```bash
-# Branch gap analysis - identify uncovered branches
-./mvnw clean test jacoco:report -Djacoco.skip=false
-open target/site/jacoco/index.html # Check red diamonds for missing branches
+ @Override
+ public String getType() {
+ return "${type}";
+ }
+}
```
-#### Constructor Path Testing
-- **Identify `new` operators**: Look for `new SomeClass()` in target code
-- **Use MockedConstruction**: Intercept constructor calls to control behavior
(see Mock Configuration Standards)
-- **Configure complete mock chains**: Ensure all dependency paths are properly
mocked
-- **Test each branch**: Create focused tests for each conditional branch
-
-#### Utility Class Coverage Optimization
-- **Static method analysis**: Map each conditional branch to specific test
scenarios
-- **Dependency isolation**: Use MockedConstruction to control external
dependencies
-- **Complete path coverage**: Ensure both true and false paths are tested
-- **Verification strategy**: Use JaCoCo HTML reports to confirm 100% branch
coverage
-
----
-
-## Part 3: Project Context & Patterns
-
-### ShardingSphere Architecture
-
-#### Module Structure
-```
-infra/ - SPI implementations and basic components
-parser/ - SQL parsers for dialects and DistSQL
-kernel/ - Core functionality (metadata, transaction, authority)
-feature/ - Pluggable features (sharding, encryption, shadow)
-mode/ - Configuration persistence and coordination
-proxy/ - Proxy implementation (MySQL/PostgreSQL/Firebird)
-jdbc/ - JDBC driver implementation
-test/ - E2E/IT test engine and cases
+## ๐ฏ Task Execution Workflow
+
+### Source Code Task Steps
+1. **Analyze Task** โ Identify as source code task
+2. **Coverage Analysis** โ Use JaCoCo to find uncovered branches
+3. **Design Implementation** โ Apply templates from Code Templates
+4. **Verify Coverage** โ Run tests to ensure 100% coverage
+5. **Format Code** โ Apply spotless formatting
+6. **Complete Validation** โ Ensure all quality checks pass
+
+### Test Task Steps
+1. **Analyze Test Scenarios** โ Identify branches that need testing
+2. **Mock Configuration** โ Use Mock Configuration Template
+3. **Write Tests** โ Apply Test Method Template
+4. **Verify Coverage** โ Ensure complete branch coverage
+5. **Assertion Validation** โ Use correct assertion patterns
+
+### Documentation Task Steps
+1. **Content Review** โ Check accuracy and formatting
+2. **Link Validation** โ Ensure all links are valid
+3. **Format Check** โ Unify markdown format
+4. **Complete Validation** โ Ensure documentation quality standards
+
+## ๐ Project Constraint Rules
+
+### YAML Format Constraint Configuration
+```yaml
+# Package naming conventions
+package_naming:
+ service: "org.apache.shardingsphere.{module}.service"
+ spi: "org.apache.shardingsphere.{module}.spi"
+ config: "org.apache.shardingsphere.{module}.config"
+ util: "org.apache.shardingsphere.{module}.util"
+
+# Class design rules
+class_design:
+ services:
+ - final_class_with_final_fields
+ - constructor_injection_only
+ - use_requiredArgsConstructor
+ - self_documenting_code_only
+
+ naming_conventions:
+ test_methods: "assert{MethodName}With{Condition}Expects{Result}"
+ production_variables: "result"
+ test_variables: "actual"
+ private_methods: "descriptive_verb_noun"
+
+ test_organization:
+ - one_test_per_branch
+ - branch_first_naming
+ - minimal_test_count
+ - test_isolation
+ - try_with_resources_for_mocks
+
+# Quality requirements
+quality_requirements:
+ test_coverage: "100%"
+ code_formatting: "spotless_applied"
+ documentation: "self_documenting_only"
+ mock_strategy: "use_mockedconstruction_for_external_deps"
+
+# Assertion standards
+assertion_standards:
+ preferred_style: "hamcrest_matchers"
+ usage_pattern: "assertThat(actual, is(expected))"
+ variable_naming: "use_actual_for_assertions"
```
-#### Core Design Patterns
-
-**Database Abstraction**
-- Database-specific dialect implementations
-- SPI for extensible components
-- Database-agnostic core logic
-
-**Metadata Design**
-- Immutable objects (final classes + final fields)
-- Builder patterns for complex construction
-- Consistent database concept naming
+### Code Pattern Examples
+```java
+// Self-documenting code pattern (must follow)
+if (userIsAdminWithPermission()) {
+ // Complex logic extracted to private method
+}
-**SPI Implementation**
-- Service discovery mechanism for registration
-- Appropriate default implementations
-- Use `TypedSPILoader.getService()` in tests when mocking is complex (see
Appendix: Common Issues & Solutions)
+private boolean userIsAdminWithPermission() {
+ return user.isAdmin() && user.hasPermission();
+}
-### Development Patterns
+// Standard test structure (must follow)
+@Test
+void assertMethodNameWithConditionExpectsResult() {
+ // Given
+ mockDependencyChain();
-#### Dependency Injection
-```java
-// Constructor-only injection with final fields
-public final class ExampleService {
- private final DependencyService dependencyService;
+ // When
+ MyResult actual = target.methodUnderTest(input);
- public ExampleService(DependencyService dependencyService) {
- this.dependencyService = dependencyService;
- }
+ // Then
+ assertThat(actual, is(expectedResult));
}
```
-#### Configuration Patterns
-```java
-// YAML-based configuration
-Properties props = PropertiesBuilder.build(new Property("key", "value"));
+## ๐ Quick Search Index
-// Repository abstraction for data access
-Repository repository = new YamlRepository(path);
-```
+### AI Search Mapping Table
+```yaml
+quick_search_index:
+ "Create rule change processor":
+ target: "Code Templates.Rule Change Processor Template"
+ description: "Create rule change processor class"
-// Test patterns and organization covered in Comprehensive Test Patterns (Part
2)
+ "Write test methods":
+ target: "Code Templates.Test Method Template"
+ description: "Write unit test methods"
-### Utility Class Testing Best Practices
+ "Mock external dependencies":
+ target: "Code Templates.Mock Configuration Template"
+ description: "Configure external dependency Mock"
-#### Static Method Testing Strategy
-- **Branch mapping**: Map each conditional statement to specific test scenarios
-- **Constructor control**: Use MockedConstruction to control external
dependencies
-- **Complete path coverage**: Ensure both true and false branches are tested
-- **Minimal test set**: One test per branch, no redundant coverage
+ "Coverage check":
+ target: "Quick Commands Reference.Validation Commands"
+ description: "Run test coverage check"
-// Constructor behavior validation examples covered in Mock Configuration
Standards (Part 2)
+ "Format code":
+ target: "Quick Commands Reference.Validation Commands"
+ description: "Apply code formatting"
-#### Complete Branch Coverage Implementation
-- **Identify all branches**: Use JaCoCo HTML reports to find uncovered
conditional branches
-- **Create targeted tests**: One test method per missing branch
-- **Mock external dependencies**: Control all external object creation paths
-- **Verify 100% coverage**: Confirm all branch diamonds are green in JaCoCo
reports
+ "Naming rules":
+ target: "Project Constraint Rules.class_design.naming_conventions"
+ description: "View naming conventions"
-// Test method organization principles covered in Comprehensive Test Patterns
(Part 2)
+ "Package structure":
+ target: "Project Constraint Rules.package_naming"
+ description: "View package naming rules"
-#### Priority Guidelines
-1. **Quality > Speed**: Never compromise on 100% coverage or code standards
-2. **Consistency > Preference**: Match existing patterns over personal
preferences
-3. **Safety > Features**: Preserve existing functionality over adding new
features
-4. **Clarity > Brevity**: Self-documenting code over clever but unclear code
+ "Quality issues":
+ target: "Troubleshooting Guide"
+ description: "Solve common quality issues"
-#### Handling Ambiguity
-- **Scope unclear** โ Request clarification before proceeding
-- **Impact uncertain** โ Propose minimal safe experiment
-- **Rules conflict** โ Follow most restrictive interpretation
-- **Emergency needed** โ Stop and report constraints immediately
+error_recovery_index:
+ "Coverage not met":
+ solution: "Check Mock configuration, add branch tests"
+ reference: "Code Templates.Mock Configuration Template"
-#### Performance Considerations
-- Identify performance-sensitive code paths
-- Use appropriate data structures (LinkedHashMap for thread-safe iteration)
-- Consider concurrency implications in multi-threaded contexts
-- Avoid shared mutable state in service classes
+ "Compilation errors":
+ solution: "Check dependencies and syntax"
+ reference: "Quick Commands Reference.Build Commands"
-#### Security Practices
-- Validate input parameters at API boundaries
-- Use immutable collections for test data
-- Apply appropriate synchronization for shared resources
-- Follow secure coding patterns for database operations
+ "Format errors":
+ solution: "Run spotless formatting"
+ reference: "Quick Commands Reference.Validation Commands"
----
+ "Test failures":
+ solution: "Check Mock configuration and assertion logic"
+ reference: "Code Templates.Test Method Template"
+```
-## Appendix: Tools & Troubleshooting
+## ๐ ๏ธ Troubleshooting Guide
-### Quick Reference Commands
+### Common Problem Diagnosis
-**Source Code Tasks**
-```bash
-# === Development ===
-./mvnw install -T1C # Full build
-./mvnw install -T1C -DskipTests # Build without tests
-./mvnw spotless:apply -Pcheck # Format code
+#### Coverage Issues
+```yaml
+problem: "Coverage not met"
+cause_check:
+ - Mock configuration incomplete, some branches not executed
+ - Tests exit early, not covering target code
+ - Complex conditional statement branch testing missing
-# === Coverage ===
-./mvnw clean test jacoco:report -Djacoco.skip=false -pl module/path
-./mvnw test jacoco:check@jacoco-check -Pcoverage-check -Djacoco.skip=false \
- -Djacoco.check.class.pattern=ClassName
+solution:
+ 1. Check Mock configuration, use MockedConstruction to control external
dependencies
+ 2. View JaCoCo HTML report, locate red diamond marked uncovered branches
+ 3. Create dedicated test methods for each conditional branch
-# See Part 2: Coverage Tools Reference for complete command patterns and
advanced strategies
+reference_commands:
+ ./mvnw clean test jacoco:report -Djacoco.skip=false -pl ${submodule}
+ open ${submodule}/target/site/jacoco/index.html
```
-**Documentation Tasks**
-```bash
-# === Documentation Validation ===
-# Quick link check (if available)
-find . -name "*.md" -exec grep -l "http" {} \; # Find docs with links
+#### Compilation Errors
+```yaml
+problem: "Compilation failure"
+cause_check:
+ - Dependency version conflicts
+ - Syntax errors
+ - Package import errors
+
+solution:
+ 1. Check dependency versions and compatibility
+ 2. Verify syntax correctness
+ 3. Confirm package paths and import statements
+
+reference_commands:
+ ./mvnw clean compile
+ ./mvnw dependency:tree
+```
-# Markdown format check
-markdownlint docs/**/*.md # If markdownlint is available
+#### Test Failures
+```yaml
+problem: "Test execution failure"
+cause_check:
+ - Mock configuration incorrect
+ - Assertion logic errors
+ - Test data construction problems
-# Spell check (if available)
-cspell docs/**/*.md # If cspell is configured
+solution:
+ 1. Check Mock configuration, ensure complete dependency chain
+ 2. Verify assertion logic, use Hamcrest matchers
+ 3. Confirm test data validity
-# === Documentation Quick Fix ===
-./mvnw spotless:apply -Pcheck # Format any code examples
+reference_template: "Code Templates.Test Method Template"
```
-**Mixed Tasks**
-```bash
-# === Combined Validation ===
-# Apply source code commands to .java files only
-# Apply documentation commands to .md files only
-# Use file-specific validation based on changed file patterns
-
-# Example: Check changed files
-git diff --name-only HEAD~1 | grep "\.java$" # Changed Java files
-git diff --name-only HEAD~1 | grep "\.md$" # Changed Markdown files
+#### Mock Configuration Issues
+```yaml
+problem: "Mock configuration complex and difficult to manage"
+cause_check:
+ - Nested dependencies too deep
+ - Constructor Mock missing
+ - Static method call Mock inappropriate
+ - Mock object selection inappropriate (over-Mocking simple objects)
+
+solution:
+ 1. Identify Mock boundaries: direct creation for simple objects, Mock only
for complex objects
+ 2. Use RETURNS_DEEP_STUBS to handle complex dependencies
+ 3. Use MockedConstruction for constructor calls
+ 4. Use MockedStatic for static method calls
+ 5. Reduce unnecessary Mock, improve test readability
+
+mock_boundary_judgment:
+ - No Mock needed: String, basic types, DTOs, POJOs, stateless utility classes
+ - Must Mock: database connections, network services, file systems,
third-party interfaces
+
+reference_template: "Code Templates.Mock Configuration Template"
```
-### Common Issues & Solutions
+### Debugging Techniques
-#### Coverage Problems
-- **Issue**: Tests pass but coverage doesn't improve
-- **Cause**: Tests exit early before reaching target code
-- **Solution**: Check mock configuration, use coverage reports to verify
execution paths
+#### Coverage Debugging
+1. **Generate detailed report**: `./mvnw clean test jacoco:report
-Djacoco.skip=false -pl ${submodule}`
+2. **View HTML report**: `open ${submodule}/target/site/jacoco/index.html`
+3. **Locate uncovered lines**: Look for red-marked code lines
+4. **Analyze branch conditions**: Identify unexecuted conditional statement
branches
-#### Mock Configuration Issues
-- **Issue**: Complex nested mocks become unmanageable
-- **Solution**: Use `RETURNS_DEEP_STUBS`, extract mock setup to private methods
-
-// Constructor mocking problems and solutions covered in Mock Configuration
Standards (Part 2)
-
-#### Branch Coverage Challenges
-- **Issue**: Tests pass but coverage doesn't reach 100%
-- **Solution**: Use MockedConstruction to control all external dependencies in
conditional branches
-- **Issue**: Complex conditional logic with multiple nested dependencies
-- **Solution**: Break down complex conditions into individual branch tests
-- **Issue**: Cannot determine which branch is being executed
- - **Solution**: Use JaCoCo HTML reports to identify red diamond (uncovered
branches)
-
-#### SPI Testing Complexity
-- **Issue**: SPI services are difficult to mock
-- **Solution**: Use real services via `TypedSPILoader.getService()` when
appropriate
-
-#### Code Formatting Issues
-- **Issue**: Spotless formatting fails
-- **Solution**: Check for syntax errors, run `./mvnw validate` first
-
-### Extended Resources
-
-#### Documentation Links
-- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) - Detailed coding standards
-- Project Wiki - Architecture and design decisions
-- JavaDocs - API documentation and examples
-
-#### Best Practice Examples
-- Test case patterns in existing test files
-- Implementation patterns in similar classes
-- SPI implementation examples in infra modules
-
-#### Troubleshooting Checklist
-- [ ] Check test dependencies and mock configuration
-- [ ] Verify JaCoCo report for actual coverage gaps
-- [ ] Ensure code follows existing patterns
-- [ ] Confirm all changes are within task scope
-- [ ] Run final formatting and validation
+#### Mock Debugging
+1. **Verify Mock calls**: `verify(mock).method(params)`
+2. **Check Mock state**: Confirm Mock configuration is correct
+3. **Debug dependency chain**: Verify Mock configuration layer by layer
---
-**Key Success Factors:**
-1. **Analyze before coding** - Understand requirements and existing patterns
-2. **Test with purpose** - Each test should improve coverage
-3. **Code self-documentation** - Zero comments through clear naming
-4. **Iterate systematically** - Use coverage reports to guide development
-5. **Finish completely** - Format, validate, and verify 100% coverage
-
-*This guide emphasizes practical implementation over theoretical concepts.
Focus on writing clean, tested code that follows established patterns.*
\ No newline at end of file
+## ๐ Quick Checklist
+
+### Pre-Task Check
+- [ ] Clarify task type (source code/test/documentation)
+- [ ] Understand quality requirements (100%
coverage/formatting/self-documenting)
+- [ ] Find relevant templates and constraint rules
+
+### Pre-Completion Check
+- [ ] Source code task: 100% test coverage
+- [ ] Source code task: Code formatting
+- [ ] Source code task: Self-documenting code
+- [ ] Test task: Complete branch coverage
+- [ ] Documentation task: Link validity
+- [ ] All tasks: Conform to project constraint rules
+
+### Final Verification
+- [ ] Run full build: `./mvnw install -T1C`
+- [ ] Verify coverage: `./mvnw test jacoco:check@jacoco-check -Pcoverage-check`
+- [ ] Check formatting: `./mvnw spotless:apply -Pcheck`
\ No newline at end of file
