refactor: simplify module documentation with unified template

- Replace 4-layer hierarchy (Layer 1-4) with single unified template
- New template: claude-module-unified.txt works for all modules and files
- Update update_module_claude.sh to remove layer detection logic
- Archive old layer-based templates to memory/archive/
- Update intelligent-tools-strategy.md to reference unified template

Benefits:
 Single template to maintain
 Simpler script logic
 Universal application for folders and code files
 Clearer documentation structure

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-12 21:50:01 +08:00
parent 0fd390f5d8
commit 8a849d651f
7 changed files with 161 additions and 74 deletions

View File

@@ -0,0 +1,138 @@
Create or update CLAUDE.md documentation with unified module/file template:
## Unified Module Documentation Requirements
### Analysis Strategy
- **For Folders/Modules**: Analyze directory structure, sub-modules, and architectural patterns
- **For Code Files**: Analyze classes, functions, interfaces, and implementation details
### Content Focus (MUST INCLUDE):
#### 1. Purpose and Scope
- Clear description of what this module/file does
- Main responsibilities and boundaries
- Role within the larger system
#### 2. Structure Overview
**For Folders/Modules**:
- Directory organization and file structure
- Sub-module categorization
- Architectural layout
**For Code Files**:
- File organization (imports, exports, structure)
- Core classes and their hierarchy
- Main functions and their grouping
#### 3. Key Components
**For Folders/Modules**:
- Sub-modules and their responsibilities
- Major components and their interactions
- Entry points and public interfaces
**For Code Files**:
- Core classes with brief descriptions
- Key methods/functions with signatures
- Important interfaces/types
- Exported APIs
#### 4. Dependencies
- **Internal Dependencies**: Other modules/files within the project
- What it imports/requires
- Dependency relationships and flow
- **External Dependencies**: Third-party libraries and frameworks
- Critical dependencies and their purposes
- Version constraints if important
#### 5. Integration Points
- How this module/file connects to other parts
- Public APIs or interfaces exposed
- Data flow patterns (input → processing → output)
- Event handling or callbacks
- Extension points for customization
#### 6. Implementation Notes
- Key design patterns used (e.g., Singleton, Factory, Observer)
- Important technical decisions and rationale
- Configuration requirements or environment variables
- Performance considerations
- Security considerations if applicable
- Known limitations or caveats
### Documentation Style Guidelines:
- Be concise but complete
- Use clear, descriptive language
- Include code signatures for key APIs
- Focus on "what" and "why", not detailed "how"
- Reference related documentation when appropriate
- Use bullet points for readability
### Template Structure:
```markdown
# [Module/File Name]
## Purpose and Scope
[Clear description of responsibilities and role]
## Structure Overview
[Directory structure for modules OR File organization for code files]
## Key Components
### [Component/Class Name 1]
- Description: [Brief description]
- Responsibilities: [What it does]
- Key Methods: [Important methods if applicable]
### [Component/Class Name 2]
...
## Dependencies
### Internal Dependencies
- `[module/file path]` - [purpose]
- ...
### External Dependencies
- `[library name]` - [purpose and usage]
- ...
## Integration Points
### Public APIs
- `[API/function signature]` - [description]
- ...
### Data Flow
[How data flows through this module/file]
### Extension Points
[How this can be extended or customized]
## Implementation Notes
### Design Patterns
- [Pattern name]: [Usage and rationale]
### Technical Decisions
- [Decision]: [Rationale]
### Configuration
- [Config item]: [Purpose and default]
### Considerations
- Performance: [Any performance notes]
- Security: [Any security considerations]
- Limitations: [Known limitations]
```
### Content Restrictions (STRICTLY AVOID):
- Don't duplicate content from other CLAUDE.md files - reference them instead
- Avoid overly detailed code explanations (code should be self-documenting)
- Don't include complete code listings (use signatures and descriptions)
- Avoid version-specific implementation details unless critical
- Don't document every single function - focus on key components
### Special Instructions:
- If analyzing a folder with existing CLAUDE.md files in subdirectories, reference them rather than duplicating their content
- For code files, prioritize exported/public APIs over internal implementation details
- Keep dependency lists focused on direct dependencies, not transitive ones
- Update existing CLAUDE.md files rather than creating new sections unnecessarily
Remember: This template serves both folder-level module documentation and file-level implementation documentation. Adapt the sections based on what you're documenting.

View File

@@ -273,10 +273,7 @@ RULES: Focus on type safety and component composition
| **Planning** | Gemini/Qwen | Task breakdown, migration planning | `planning/task-breakdown.txt` |
| **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
| **Refactoring** | Multiple | Gemini/Qwen for analysis, Codex for execution | `development/refactor.txt` |
| **Memory Layer 1** | Gemini (Qwen fallback) | Root-level project overview, tech stack, architecture principles | `memory/claude-layer1-root.txt` |
| **Memory Layer 2** | Gemini (Qwen fallback) | Domain-level architecture, responsibility boundaries | `memory/claude-layer2-domain.txt` |
| **Memory Layer 3** | Gemini (Qwen fallback) | Module-level implementation patterns, APIs | `memory/claude-layer3-module.txt` |
| **Memory Layer 4** | Gemini (Qwen fallback) | Submodule-level detailed implementation docs | `memory/claude-layer4-submodule.txt` |
| **Module Documentation** | Gemini (Qwen fallback) | Universal module/file documentation for all levels | `memory/claude-module-unified.txt` |
| **Memory Hierarchy** | Gemini (Qwen fallback) | Project structure analysis for optimal doc hierarchy | `memory/hierarchy-analysis.txt` |
### Template System
@@ -296,11 +293,8 @@ prompts/
│ ├── refactor.txt - Refactoring tasks
│ └── testing.txt - Test generation
├── memory/
│ ├── claude-layer1-root.txt - Root-level project documentation
── claude-layer2-domain.txt - Domain-level architecture docs
│ ├── claude-layer3-module.txt - Module-level implementation docs
│ ├── claude-layer4-submodule.txt - Submodule-level detailed docs
│ └── hierarchy-analysis.txt - Project structure analysis
│ ├── claude-module-unified.txt - Universal module/file documentation template
── hierarchy-analysis.txt - Project structure analysis
└── planning/
└── task-breakdown.txt - Task decomposition