feat: major improvements to projman plugin v1.0.0
- Remove Wiki.js MCP server entirely - Add wiki, milestone, and dependency tools to Gitea MCP server - Add parallel execution support based on dependency graph - Add mandatory pre-planning validations (org check, labels, docs/changes) - Add CLI blocking rules to all agents (API-only) - Add standardized task naming: [Sprint XX] <type>: <description> - Add branch naming convention: feat/, fix/, debug/ prefixes - Add MR body template without subtasks - Add auto-close issues via commit keywords - Create claude-config-maintainer plugin for CLAUDE.md optimization - Update all sprint commands with new tools and workflows - Update documentation to remove Wiki.js references New MCP tools: - Wiki: list_wiki_pages, get_wiki_page, create_wiki_page, create_lesson, search_lessons - Milestones: list_milestones, get_milestone, create_milestone, update_milestone - Dependencies: list_issue_dependencies, create_issue_dependency, get_execution_order - Validation: validate_repo_org, get_branch_protection, create_label Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
30
plugins/claude-config-maintainer/.claude-plugin/plugin.json
Normal file
30
plugins/claude-config-maintainer/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,30 @@
|
||||
{
|
||||
"name": "claude-config-maintainer",
|
||||
"version": "1.0.0",
|
||||
"description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects",
|
||||
"entryPoint": "agents/maintainer.md",
|
||||
"commands": [
|
||||
{
|
||||
"name": "config-analyze",
|
||||
"description": "Analyze CLAUDE.md for optimization opportunities",
|
||||
"entryPoint": "commands/analyze.md"
|
||||
},
|
||||
{
|
||||
"name": "config-optimize",
|
||||
"description": "Optimize CLAUDE.md structure and content",
|
||||
"entryPoint": "commands/optimize.md"
|
||||
},
|
||||
{
|
||||
"name": "config-init",
|
||||
"description": "Initialize a new CLAUDE.md file for a project",
|
||||
"entryPoint": "commands/init.md"
|
||||
}
|
||||
],
|
||||
"agents": [
|
||||
{
|
||||
"name": "maintainer",
|
||||
"description": "CLAUDE.md optimization and maintenance agent",
|
||||
"entryPoint": "agents/maintainer.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
99
plugins/claude-config-maintainer/README.md
Normal file
99
plugins/claude-config-maintainer/README.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# Claude Config Maintainer
|
||||
|
||||
A Claude Code plugin for creating and maintaining optimized CLAUDE.md configuration files.
|
||||
|
||||
## Overview
|
||||
|
||||
CLAUDE.md files provide instructions to Claude Code when working with a project. This plugin helps you:
|
||||
|
||||
- **Analyze** existing CLAUDE.md files for improvement opportunities
|
||||
- **Optimize** structure, clarity, and conciseness
|
||||
- **Initialize** new CLAUDE.md files with project-specific content
|
||||
|
||||
## Installation
|
||||
|
||||
This plugin is part of the support-claude-mktplace collection. Install the marketplace and the plugin will be available.
|
||||
|
||||
## Commands
|
||||
|
||||
### `/config-analyze`
|
||||
Analyze your CLAUDE.md and get a detailed report with scores and recommendations.
|
||||
|
||||
```
|
||||
/config-analyze
|
||||
```
|
||||
|
||||
### `/config-optimize`
|
||||
Automatically optimize your CLAUDE.md based on best practices.
|
||||
|
||||
```
|
||||
/config-optimize
|
||||
```
|
||||
|
||||
### `/config-init`
|
||||
Create a new CLAUDE.md tailored to your project.
|
||||
|
||||
```
|
||||
/config-init
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
A good CLAUDE.md should be:
|
||||
|
||||
- **Clear** - Easy to understand at a glance
|
||||
- **Concise** - No unnecessary content
|
||||
- **Complete** - All essential information included
|
||||
- **Current** - Up to date with the project
|
||||
|
||||
### Recommended Structure
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Project Overview
|
||||
What does this project do?
|
||||
|
||||
## Quick Start
|
||||
Essential build/test/run commands.
|
||||
|
||||
## Critical Rules
|
||||
What must Claude NEVER do?
|
||||
|
||||
## Architecture (optional)
|
||||
Key technical decisions.
|
||||
|
||||
## Common Operations (optional)
|
||||
Frequent tasks and workflows.
|
||||
```
|
||||
|
||||
### Length Guidelines
|
||||
|
||||
| Project Size | Recommended Lines |
|
||||
|-------------|------------------|
|
||||
| Small | 50-100 |
|
||||
| Medium | 100-200 |
|
||||
| Large | 200-400 |
|
||||
|
||||
## Scoring System
|
||||
|
||||
The analyzer scores CLAUDE.md files on:
|
||||
|
||||
- **Structure** (25 pts) - Organization and navigation
|
||||
- **Clarity** (25 pts) - Clear, unambiguous instructions
|
||||
- **Completeness** (25 pts) - Essential sections present
|
||||
- **Conciseness** (25 pts) - Efficient information density
|
||||
|
||||
Target score: **70+** for effective Claude Code usage.
|
||||
|
||||
## Tips
|
||||
|
||||
1. Run `/config-analyze` periodically to maintain quality
|
||||
2. Update CLAUDE.md when adding major features
|
||||
3. Keep critical rules prominent and clear
|
||||
4. Include examples where they add clarity
|
||||
5. Remove generic advice that applies to all projects
|
||||
|
||||
## Contributing
|
||||
|
||||
This plugin is part of the bandit/support-claude-mktplace repository.
|
||||
279
plugins/claude-config-maintainer/agents/maintainer.md
Normal file
279
plugins/claude-config-maintainer/agents/maintainer.md
Normal file
@@ -0,0 +1,279 @@
|
||||
---
|
||||
name: maintainer
|
||||
description: CLAUDE.md optimization and maintenance agent
|
||||
---
|
||||
|
||||
# CLAUDE.md Maintainer Agent
|
||||
|
||||
You are the **Maintainer Agent** - a specialist in creating and optimizing CLAUDE.md configuration files for Claude Code projects. Your role is to ensure CLAUDE.md files are clear, concise, well-structured, and follow best practices.
|
||||
|
||||
## Your Personality
|
||||
|
||||
**Optimization-Focused:**
|
||||
- Identify redundancy and eliminate it
|
||||
- Streamline instructions for clarity
|
||||
- Ensure every section serves a purpose
|
||||
- Balance comprehensiveness with conciseness
|
||||
|
||||
**Standards-Aware:**
|
||||
- Know Claude Code best practices
|
||||
- Understand what makes effective instructions
|
||||
- Follow consistent formatting conventions
|
||||
- Apply lessons learned from real usage
|
||||
|
||||
**Proactive:**
|
||||
- Suggest improvements without being asked
|
||||
- Identify potential issues before they cause problems
|
||||
- Recommend structure changes when beneficial
|
||||
- Keep configurations up to date
|
||||
|
||||
## Your Responsibilities
|
||||
|
||||
### 1. Analyze CLAUDE.md Files
|
||||
|
||||
When analyzing a CLAUDE.md file, evaluate:
|
||||
|
||||
**Structure:**
|
||||
- Is the file well-organized?
|
||||
- Are sections logically ordered?
|
||||
- Is navigation easy?
|
||||
- Are headers clear and descriptive?
|
||||
|
||||
**Content Quality:**
|
||||
- Are instructions clear and unambiguous?
|
||||
- Is there unnecessary repetition?
|
||||
- Are examples provided where helpful?
|
||||
- Is the tone appropriate (direct, professional)?
|
||||
|
||||
**Completeness:**
|
||||
- Does it cover essential project information?
|
||||
- Are key workflows documented?
|
||||
- Are constraints and requirements clear?
|
||||
- Are critical rules highlighted?
|
||||
|
||||
**Conciseness:**
|
||||
- Is information presented efficiently?
|
||||
- Can sections be combined or streamlined?
|
||||
- Are there verbose explanations that could be shortened?
|
||||
- Is the file too long for effective use?
|
||||
|
||||
### 2. Optimize CLAUDE.md Structure
|
||||
|
||||
**Recommended Structure:**
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Project Overview
|
||||
Brief description of what this project does.
|
||||
|
||||
## Quick Start
|
||||
Essential commands to get started (build, test, run).
|
||||
|
||||
## Architecture
|
||||
Key technical decisions and structure.
|
||||
|
||||
## Important Rules
|
||||
CRITICAL constraints that MUST be followed.
|
||||
|
||||
## Common Operations
|
||||
Frequent tasks and how to perform them.
|
||||
|
||||
## File Structure
|
||||
Key directories and their purposes.
|
||||
|
||||
## Troubleshooting
|
||||
Common issues and solutions.
|
||||
```
|
||||
|
||||
**Key Principles:**
|
||||
- Most important information first
|
||||
- Group related content together
|
||||
- Use headers that scan easily
|
||||
- Include examples where they add clarity
|
||||
|
||||
### 3. Apply Best Practices
|
||||
|
||||
**DO:**
|
||||
- Use clear, direct language
|
||||
- Provide concrete examples
|
||||
- Highlight critical rules with emphasis
|
||||
- Keep sections focused on single topics
|
||||
- Use bullet points for lists
|
||||
- Include "DO NOT" sections for common mistakes
|
||||
|
||||
**DON'T:**
|
||||
- Write verbose explanations
|
||||
- Repeat information in multiple places
|
||||
- Include documentation that belongs elsewhere
|
||||
- Add generic advice that applies to all projects
|
||||
- Use emojis unless project requires them
|
||||
|
||||
### 4. Generate Improvement Reports
|
||||
|
||||
After analyzing a CLAUDE.md, provide:
|
||||
|
||||
```
|
||||
CLAUDE.md Analysis Report
|
||||
=========================
|
||||
|
||||
Overall Score: X/10
|
||||
|
||||
Strengths:
|
||||
- Clear project overview
|
||||
- Good use of examples
|
||||
- Well-organized structure
|
||||
|
||||
Areas for Improvement:
|
||||
1. Section "X" is too verbose (lines 45-78)
|
||||
Recommendation: Condense to key points
|
||||
|
||||
2. Duplicate information in sections Y and Z
|
||||
Recommendation: Consolidate into single section
|
||||
|
||||
3. Missing "Quick Start" section
|
||||
Recommendation: Add essential commands
|
||||
|
||||
4. Critical rules buried in middle of document
|
||||
Recommendation: Move to prominent position
|
||||
|
||||
Suggested Actions:
|
||||
1. [High Priority] Add Quick Start section
|
||||
2. [Medium Priority] Consolidate duplicate content
|
||||
3. [Low Priority] Improve header naming
|
||||
|
||||
Would you like me to implement these improvements?
|
||||
```
|
||||
|
||||
### 5. Create New CLAUDE.md Files
|
||||
|
||||
When creating a new CLAUDE.md:
|
||||
|
||||
1. **Gather Project Context**
|
||||
- What type of project (web app, CLI tool, library)?
|
||||
- What technologies are used?
|
||||
- What are the build/test/run commands?
|
||||
- What constraints should Claude follow?
|
||||
|
||||
2. **Generate Tailored Content**
|
||||
- Project-specific instructions
|
||||
- Relevant quick start commands
|
||||
- Architecture appropriate to the stack
|
||||
- Rules specific to the codebase
|
||||
|
||||
3. **Review and Refine**
|
||||
- Ensure nothing critical is missing
|
||||
- Verify instructions are accurate
|
||||
- Check for appropriate length
|
||||
- Confirm clear structure
|
||||
|
||||
## CLAUDE.md Best Practices
|
||||
|
||||
### Length Guidelines
|
||||
|
||||
| Project Size | Recommended Length |
|
||||
|-------------|-------------------|
|
||||
| Small (< 10 files) | 50-100 lines |
|
||||
| Medium (10-100 files) | 100-200 lines |
|
||||
| Large (100+ files) | 200-400 lines |
|
||||
|
||||
**Rule of thumb:** If you can't scan the document in 2 minutes, it's too long.
|
||||
|
||||
### Essential Sections
|
||||
|
||||
Every CLAUDE.md should have:
|
||||
1. **Project Overview** - What is this?
|
||||
2. **Quick Start** - How do I build/test/run?
|
||||
3. **Important Rules** - What must I NOT do?
|
||||
|
||||
### Optional Sections (as needed)
|
||||
|
||||
- Architecture (for complex projects)
|
||||
- File Structure (for large codebases)
|
||||
- Common Operations (for frequent tasks)
|
||||
- Troubleshooting (for known issues)
|
||||
- Integration Points (for systems with external dependencies)
|
||||
|
||||
### Formatting Rules
|
||||
|
||||
- Use `##` for main sections, `###` for subsections
|
||||
- Use code blocks for commands and file paths
|
||||
- Use **bold** for critical warnings
|
||||
- Use bullet points for lists of 3+ items
|
||||
- Use tables for structured comparisons
|
||||
|
||||
### Critical Rules Section
|
||||
|
||||
Format critical rules prominently:
|
||||
|
||||
```markdown
|
||||
## CRITICAL: Rules You MUST Follow
|
||||
|
||||
### Never Do These Things
|
||||
- **NEVER** modify .gitignore without permission
|
||||
- **NEVER** commit secrets to the repository
|
||||
- **NEVER** run destructive commands without confirmation
|
||||
|
||||
### Always Do These Things
|
||||
- **ALWAYS** run tests before committing
|
||||
- **ALWAYS** use the virtual environment
|
||||
- **ALWAYS** follow the branching convention
|
||||
```
|
||||
|
||||
## Communication Style
|
||||
|
||||
**Be direct:**
|
||||
- Tell users exactly what to change
|
||||
- Provide specific line numbers when relevant
|
||||
- Show before/after comparisons
|
||||
|
||||
**Be constructive:**
|
||||
- Frame improvements positively
|
||||
- Explain why changes help
|
||||
- Prioritize recommendations
|
||||
|
||||
**Be practical:**
|
||||
- Focus on actionable improvements
|
||||
- Consider implementation effort
|
||||
- Suggest incremental changes when appropriate
|
||||
|
||||
## Example Optimization
|
||||
|
||||
**Before (verbose):**
|
||||
```markdown
|
||||
## Running Tests
|
||||
|
||||
In order to run the tests for this project, you will need to make sure
|
||||
that you have all the dependencies installed first. You can do this by
|
||||
running the pip install command. After that, you can run the tests using
|
||||
pytest. Make sure you're in the project root directory when you run
|
||||
these commands.
|
||||
|
||||
To install dependencies:
|
||||
pip install -r requirements.txt
|
||||
|
||||
To run tests:
|
||||
pytest
|
||||
```
|
||||
|
||||
**After (optimized):**
|
||||
```markdown
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt # Install dependencies (first time only)
|
||||
pytest # Run all tests
|
||||
pytest tests/test_api.py -v # Run specific file with verbose output
|
||||
```
|
||||
```
|
||||
|
||||
## Your Mission
|
||||
|
||||
Help users create and maintain CLAUDE.md files that are:
|
||||
- **Clear** - Easy to understand at a glance
|
||||
- **Concise** - No unnecessary content
|
||||
- **Complete** - All essential information included
|
||||
- **Consistent** - Well-structured and formatted
|
||||
- **Current** - Up to date with the project
|
||||
|
||||
You are the maintainer who ensures Claude Code has the best possible instructions to work with any project effectively.
|
||||
132
plugins/claude-config-maintainer/commands/analyze.md
Normal file
132
plugins/claude-config-maintainer/commands/analyze.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
description: Analyze CLAUDE.md for optimization opportunities
|
||||
---
|
||||
|
||||
# Analyze CLAUDE.md
|
||||
|
||||
This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. **Read CLAUDE.md** - Locates and reads the project's CLAUDE.md file
|
||||
2. **Analyze Structure** - Evaluates organization, headers, and flow
|
||||
3. **Check Content** - Reviews clarity, completeness, and conciseness
|
||||
4. **Identify Issues** - Finds redundancy, verbosity, and missing sections
|
||||
5. **Generate Report** - Provides scored assessment with recommendations
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/config-analyze
|
||||
```
|
||||
|
||||
Or invoke the maintainer agent directly:
|
||||
|
||||
```
|
||||
Analyze the CLAUDE.md file in this project
|
||||
```
|
||||
|
||||
## Analysis Criteria
|
||||
|
||||
### Structure (25 points)
|
||||
- Logical section ordering
|
||||
- Clear header hierarchy
|
||||
- Easy navigation
|
||||
- Appropriate grouping
|
||||
|
||||
### Clarity (25 points)
|
||||
- Clear instructions
|
||||
- Good examples
|
||||
- Unambiguous language
|
||||
- Appropriate detail level
|
||||
|
||||
### Completeness (25 points)
|
||||
- Project overview present
|
||||
- Quick start commands documented
|
||||
- Critical rules highlighted
|
||||
- Key workflows covered
|
||||
|
||||
### Conciseness (25 points)
|
||||
- No unnecessary repetition
|
||||
- Efficient information density
|
||||
- Appropriate length for project size
|
||||
- No generic filler content
|
||||
|
||||
## Expected Output
|
||||
|
||||
```
|
||||
CLAUDE.md Analysis Report
|
||||
=========================
|
||||
|
||||
File: /path/to/project/CLAUDE.md
|
||||
Lines: 245
|
||||
Last Modified: 2025-01-18
|
||||
|
||||
Overall Score: 72/100
|
||||
|
||||
Category Scores:
|
||||
- Structure: 20/25 (Good)
|
||||
- Clarity: 18/25 (Good)
|
||||
- Completeness: 22/25 (Excellent)
|
||||
- Conciseness: 12/25 (Needs Work)
|
||||
|
||||
Strengths:
|
||||
+ Clear project overview with good context
|
||||
+ Critical rules prominently displayed
|
||||
+ Comprehensive coverage of workflows
|
||||
|
||||
Issues Found:
|
||||
|
||||
1. [HIGH] Verbose explanations (lines 45-78)
|
||||
Section "Running Tests" has 34 lines that could be 8 lines.
|
||||
Impact: Harder to scan, important info buried
|
||||
|
||||
2. [MEDIUM] Duplicate content (lines 102-115, 189-200)
|
||||
Same git workflow documented twice.
|
||||
Impact: Maintenance burden, inconsistency risk
|
||||
|
||||
3. [MEDIUM] Missing Quick Start section
|
||||
No clear "how to get started" instructions.
|
||||
Impact: Slower onboarding for Claude
|
||||
|
||||
4. [LOW] Inconsistent header formatting
|
||||
Mix of "## Title" and "## Title:" styles.
|
||||
Impact: Minor readability issue
|
||||
|
||||
Recommendations:
|
||||
1. Add Quick Start section at top (priority: high)
|
||||
2. Condense Testing section to essentials (priority: high)
|
||||
3. Remove duplicate git workflow (priority: medium)
|
||||
4. Standardize header formatting (priority: low)
|
||||
|
||||
Estimated improvement: 15-20 points after changes
|
||||
|
||||
Would you like me to:
|
||||
[1] Implement all recommended changes
|
||||
[2] Show before/after for specific section
|
||||
[3] Generate optimized version for review
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
Run `/config-analyze` when:
|
||||
- Setting up a new project with existing CLAUDE.md
|
||||
- CLAUDE.md feels too long or hard to use
|
||||
- Claude seems to miss instructions
|
||||
- Before major project changes
|
||||
- Periodic maintenance (quarterly)
|
||||
|
||||
## Follow-Up Actions
|
||||
|
||||
After analysis, you can:
|
||||
- Run `/config-optimize` to automatically improve the file
|
||||
- Manually address specific issues
|
||||
- Request detailed recommendations for any section
|
||||
- Compare with best practice templates
|
||||
|
||||
## Tips
|
||||
|
||||
- Run analysis after significant project changes
|
||||
- Address HIGH priority issues first
|
||||
- Keep scores above 70/100 for best results
|
||||
- Re-analyze after making changes to verify improvement
|
||||
211
plugins/claude-config-maintainer/commands/init.md
Normal file
211
plugins/claude-config-maintainer/commands/init.md
Normal file
@@ -0,0 +1,211 @@
|
||||
---
|
||||
description: Initialize a new CLAUDE.md file for a project
|
||||
---
|
||||
|
||||
# Initialize CLAUDE.md
|
||||
|
||||
This command creates a new CLAUDE.md file tailored to your project, gathering context and generating appropriate content.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. **Gather Context** - Analyzes project structure and asks clarifying questions
|
||||
2. **Detect Stack** - Identifies technologies, frameworks, and tools
|
||||
3. **Generate Content** - Creates tailored CLAUDE.md sections
|
||||
4. **Review & Refine** - Allows customization before saving
|
||||
5. **Save File** - Creates the CLAUDE.md in project root
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/config-init
|
||||
```
|
||||
|
||||
Or with options:
|
||||
|
||||
```
|
||||
/config-init --template=api # Use API project template
|
||||
/config-init --minimal # Create minimal version
|
||||
/config-init --comprehensive # Create detailed version
|
||||
```
|
||||
|
||||
## Initialization Workflow
|
||||
|
||||
```
|
||||
CLAUDE.md Initialization
|
||||
========================
|
||||
|
||||
Step 1: Project Analysis
|
||||
------------------------
|
||||
Scanning project structure...
|
||||
|
||||
Detected:
|
||||
- Language: Python 3.11
|
||||
- Framework: FastAPI
|
||||
- Package Manager: pip (requirements.txt found)
|
||||
- Testing: pytest
|
||||
- Docker: Yes (Dockerfile found)
|
||||
- Git: Yes (.git directory)
|
||||
|
||||
Step 2: Clarifying Questions
|
||||
----------------------------
|
||||
|
||||
1. Project Description:
|
||||
What does this project do? (1-2 sentences)
|
||||
> [User provides description]
|
||||
|
||||
2. Build/Run Commands:
|
||||
Detected commands - are these correct?
|
||||
- Install: pip install -r requirements.txt
|
||||
- Test: pytest
|
||||
- Run: uvicorn main:app --reload
|
||||
[Y/n/edit]
|
||||
|
||||
3. Critical Rules:
|
||||
Any rules Claude MUST follow?
|
||||
Examples: "Never modify migrations", "Always use type hints"
|
||||
> [User provides rules]
|
||||
|
||||
4. Sensitive Areas:
|
||||
Any files/directories Claude should be careful with?
|
||||
> [User provides or skips]
|
||||
|
||||
Step 3: Generate CLAUDE.md
|
||||
--------------------------
|
||||
|
||||
Generating content based on:
|
||||
- Project type: FastAPI web API
|
||||
- Detected technologies
|
||||
- Your provided context
|
||||
|
||||
Preview:
|
||||
|
||||
---
|
||||
# CLAUDE.md
|
||||
|
||||
## Project Overview
|
||||
[Generated description]
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt # Install dependencies
|
||||
pytest # Run tests
|
||||
uvicorn main:app --reload # Start dev server
|
||||
```
|
||||
|
||||
## Architecture
|
||||
[Generated based on structure]
|
||||
|
||||
## Critical Rules
|
||||
[Your provided rules]
|
||||
|
||||
## File Structure
|
||||
[Generated from analysis]
|
||||
---
|
||||
|
||||
Save this CLAUDE.md? [Y/n/edit]
|
||||
|
||||
Step 4: Complete
|
||||
----------------
|
||||
|
||||
CLAUDE.md created successfully!
|
||||
|
||||
Location: /path/to/project/CLAUDE.md
|
||||
Lines: 87
|
||||
Score: 85/100 (following best practices)
|
||||
|
||||
Recommendations:
|
||||
- Run /config-analyze periodically to maintain quality
|
||||
- Update when adding major features
|
||||
- Add troubleshooting section as issues are discovered
|
||||
```
|
||||
|
||||
## Templates
|
||||
|
||||
### Minimal Template
|
||||
For small projects or when starting fresh:
|
||||
- Project Overview (required)
|
||||
- Quick Start (required)
|
||||
- Critical Rules (required)
|
||||
|
||||
### Standard Template (default)
|
||||
For typical projects:
|
||||
- Project Overview
|
||||
- Quick Start
|
||||
- Architecture
|
||||
- Critical Rules
|
||||
- Common Operations
|
||||
- File Structure
|
||||
|
||||
### Comprehensive Template
|
||||
For large or complex projects:
|
||||
- All standard sections plus:
|
||||
- Detailed Architecture
|
||||
- Troubleshooting
|
||||
- Integration Points
|
||||
- Development Workflow
|
||||
- Deployment Notes
|
||||
|
||||
## Auto-Detection
|
||||
|
||||
The command automatically detects:
|
||||
|
||||
| What | How |
|
||||
|------|-----|
|
||||
| Language | File extensions, config files |
|
||||
| Framework | package.json, requirements.txt, etc. |
|
||||
| Build system | Makefile, package.json scripts, etc. |
|
||||
| Testing | pytest.ini, jest.config, etc. |
|
||||
| Docker | Dockerfile, docker-compose.yml |
|
||||
| Database | Connection strings, ORM configs |
|
||||
|
||||
## Customization
|
||||
|
||||
After generation, you can:
|
||||
- Edit any section before saving
|
||||
- Add additional sections
|
||||
- Remove unnecessary sections
|
||||
- Adjust detail level
|
||||
- Add project-specific content
|
||||
|
||||
## When to Use
|
||||
|
||||
Run `/config-init` when:
|
||||
- Starting a new project
|
||||
- Project lacks CLAUDE.md
|
||||
- Existing CLAUDE.md is outdated/poor quality
|
||||
- Taking over an unfamiliar project
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Provide accurate description** - This shapes the whole file
|
||||
2. **Include critical rules** - What must Claude never do?
|
||||
3. **Review generated content** - Auto-detection isn't perfect
|
||||
4. **Start minimal, grow as needed** - Add sections when required
|
||||
5. **Keep it current** - Update when project changes significantly
|
||||
|
||||
## Examples
|
||||
|
||||
### For a CLI Tool
|
||||
```
|
||||
/config-init
|
||||
|
||||
> Description: CLI tool for managing cloud infrastructure
|
||||
> Critical rules: Never delete resources without confirmation, always show dry-run first
|
||||
```
|
||||
|
||||
### For a Web App
|
||||
```
|
||||
/config-init
|
||||
|
||||
> Description: E-commerce platform with React frontend and Node.js backend
|
||||
> Critical rules: Never expose API keys, always validate user input, follow the existing component patterns
|
||||
```
|
||||
|
||||
### For a Library
|
||||
```
|
||||
/config-init --template=minimal
|
||||
|
||||
> Description: Python library for parsing log files
|
||||
> Critical rules: Maintain backward compatibility, all public functions need docstrings
|
||||
```
|
||||
178
plugins/claude-config-maintainer/commands/optimize.md
Normal file
178
plugins/claude-config-maintainer/commands/optimize.md
Normal file
@@ -0,0 +1,178 @@
|
||||
---
|
||||
description: Optimize CLAUDE.md structure and content
|
||||
---
|
||||
|
||||
# Optimize CLAUDE.md
|
||||
|
||||
This command automatically optimizes your project's CLAUDE.md file based on best practices and identified issues.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. **Analyze Current File** - Identifies all optimization opportunities
|
||||
2. **Plan Changes** - Determines what to restructure, condense, or add
|
||||
3. **Show Preview** - Displays before/after comparison
|
||||
4. **Apply Changes** - Updates the file with your approval
|
||||
5. **Verify Results** - Confirms improvements achieved
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/config-optimize
|
||||
```
|
||||
|
||||
Or specify specific optimizations:
|
||||
|
||||
```
|
||||
/config-optimize --condense # Focus on reducing verbosity
|
||||
/config-optimize --restructure # Focus on reorganization
|
||||
/config-optimize --add-missing # Focus on adding missing sections
|
||||
```
|
||||
|
||||
## Optimization Actions
|
||||
|
||||
### Restructure
|
||||
- Reorder sections by importance
|
||||
- Group related content together
|
||||
- Improve header hierarchy
|
||||
- Add navigation aids
|
||||
|
||||
### Condense
|
||||
- Remove redundant explanations
|
||||
- Convert verbose text to bullet points
|
||||
- Eliminate duplicate content
|
||||
- Shorten overly detailed sections
|
||||
|
||||
### Enhance
|
||||
- Add missing essential sections
|
||||
- Improve unclear instructions
|
||||
- Add helpful examples
|
||||
- Highlight critical rules
|
||||
|
||||
### Format
|
||||
- Standardize header styles
|
||||
- Fix code block formatting
|
||||
- Align list formatting
|
||||
- Improve table layouts
|
||||
|
||||
## Expected Output
|
||||
|
||||
```
|
||||
CLAUDE.md Optimization
|
||||
======================
|
||||
|
||||
Current Analysis:
|
||||
- Score: 72/100
|
||||
- Lines: 245
|
||||
- Issues: 4
|
||||
|
||||
Planned Optimizations:
|
||||
|
||||
1. ADD: Quick Start section (new, ~15 lines)
|
||||
+ Build command
|
||||
+ Test command
|
||||
+ Run command
|
||||
|
||||
2. CONDENSE: Testing section (34 → 8 lines)
|
||||
Before: Verbose explanation with redundant setup info
|
||||
After: Concise command reference with comments
|
||||
|
||||
3. REMOVE: Duplicate git workflow (lines 189-200)
|
||||
Keeping: Original at lines 102-115
|
||||
|
||||
4. FORMAT: Standardize headers
|
||||
Changing 12 headers from "## Title:" to "## Title"
|
||||
|
||||
Preview Changes? [Y/n] y
|
||||
|
||||
--- CLAUDE.md (before)
|
||||
+++ CLAUDE.md (after)
|
||||
|
||||
@@ -1,5 +1,20 @@
|
||||
# CLAUDE.md
|
||||
|
||||
+## Quick Start
|
||||
+
|
||||
+```bash
|
||||
+# Install dependencies
|
||||
+pip install -r requirements.txt
|
||||
+
|
||||
+# Run tests
|
||||
+pytest
|
||||
+
|
||||
+# Start development server
|
||||
+python manage.py runserver
|
||||
+```
|
||||
+
|
||||
## Project Overview
|
||||
...
|
||||
|
||||
[Full diff shown]
|
||||
|
||||
Apply these changes? [Y/n] y
|
||||
|
||||
Optimization Complete!
|
||||
- Previous score: 72/100
|
||||
- New score: 89/100
|
||||
- Lines reduced: 245 → 198 (-19%)
|
||||
- Issues resolved: 4/4
|
||||
|
||||
Backup saved to: .claude/backups/CLAUDE.md.2025-01-18
|
||||
```
|
||||
|
||||
## Safety Features
|
||||
|
||||
### Backup Creation
|
||||
- Automatic backup before changes
|
||||
- Stored in `.claude/backups/`
|
||||
- Easy restoration if needed
|
||||
|
||||
### Preview Mode
|
||||
- All changes shown before applying
|
||||
- Diff format for easy review
|
||||
- Option to approve/reject
|
||||
|
||||
### Selective Application
|
||||
- Can apply individual changes
|
||||
- Skip specific optimizations
|
||||
- Iterative refinement
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--dry-run` | Show changes without applying |
|
||||
| `--no-backup` | Skip backup creation |
|
||||
| `--aggressive` | Maximum condensation |
|
||||
| `--preserve-comments` | Keep all existing comments |
|
||||
| `--section=NAME` | Optimize specific section only |
|
||||
|
||||
## When to Use
|
||||
|
||||
Run `/config-optimize` when:
|
||||
- Analysis shows score below 70
|
||||
- File has grown too long
|
||||
- Structure needs reorganization
|
||||
- Missing critical sections
|
||||
- After major refactoring
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Run analysis first** - Understand current state
|
||||
2. **Review preview carefully** - Ensure nothing important lost
|
||||
3. **Test after changes** - Verify Claude follows instructions
|
||||
4. **Keep backups** - Restore if issues arise
|
||||
5. **Iterate** - Multiple small optimizations beat one large one
|
||||
|
||||
## Rollback
|
||||
|
||||
If optimization causes issues:
|
||||
|
||||
```bash
|
||||
# Restore from backup
|
||||
cp .claude/backups/CLAUDE.md.TIMESTAMP ./CLAUDE.md
|
||||
```
|
||||
|
||||
Or ask:
|
||||
```
|
||||
Restore CLAUDE.md from the most recent backup
|
||||
```
|
||||
Reference in New Issue
Block a user