lmiranda
7c8a20c804
Refactored commands to extract reusable skills following the Commands → Skills separation pattern. Each command is now <50 lines and references skill files for detailed knowledge. Plugins refactored: - claude-config-maintainer: 5 commands → 7 skills - code-sentinel: 3 commands → 2 skills - contract-validator: 5 commands → 6 skills - data-platform: 10 commands → 6 skills - doc-guardian: 5 commands → 6 skills (replaced nested dir) - git-flow: 8 commands → 7 skills Skills contain: workflows, validation rules, conventions, reference data, tool documentation Commands now contain: YAML frontmatter, agent assignment, skills list, brief workflow steps, parameters Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
114 lines
2.6 KiB
Markdown
114 lines
2.6 KiB
Markdown
# CLAUDE.md Structure Reference
|
|
|
|
This skill defines the standard structure, required sections, and templates for CLAUDE.md files.
|
|
|
|
## Required Sections
|
|
|
|
Every CLAUDE.md MUST have these sections:
|
|
|
|
| Section | Purpose | Priority |
|
|
|---------|---------|----------|
|
|
| Project Overview | What the project does | Required |
|
|
| Quick Start | Build/test/run commands | Required |
|
|
| Critical Rules | Must-follow constraints | Required |
|
|
| Pre-Change Protocol | Dependency check before edits | **MANDATORY** |
|
|
|
|
## Recommended Sections
|
|
|
|
| Section | When to Include |
|
|
|---------|-----------------|
|
|
| Architecture | Complex projects with multiple components |
|
|
| Common Operations | Projects with repetitive tasks |
|
|
| File Structure | Large codebases |
|
|
| Troubleshooting | Projects with known gotchas |
|
|
| Integration Points | Projects with external dependencies |
|
|
|
|
## Header Hierarchy
|
|
|
|
```
|
|
# CLAUDE.md (H1 - only one)
|
|
## Section (H2 - main sections)
|
|
### Subsection (H3 - within sections)
|
|
#### Detail (H4 - rarely needed)
|
|
```
|
|
|
|
**Rules:**
|
|
- Never skip levels (no H3 before H2)
|
|
- Maximum depth: 4 levels
|
|
- No orphaned content before first header
|
|
|
|
## Templates
|
|
|
|
### Minimal Template
|
|
For small projects:
|
|
```markdown
|
|
# CLAUDE.md
|
|
|
|
## Project Overview
|
|
[Description]
|
|
|
|
## Quick Start
|
|
[Commands]
|
|
|
|
## Critical Rules
|
|
[Constraints]
|
|
|
|
## Pre-Change Protocol
|
|
[Mandatory section - see pre-change-protocol.md]
|
|
```
|
|
|
|
### Standard Template (Default)
|
|
```markdown
|
|
# CLAUDE.md
|
|
|
|
## Project Overview
|
|
## Quick Start
|
|
## Architecture
|
|
## Critical Rules
|
|
## Pre-Change Protocol
|
|
## Common Operations
|
|
## File Structure
|
|
```
|
|
|
|
### Comprehensive Template
|
|
For large projects - adds:
|
|
- Detailed Architecture
|
|
- Troubleshooting
|
|
- Integration Points
|
|
- Development Workflow
|
|
- Deployment Notes
|
|
|
|
## Auto-Detection Signals
|
|
|
|
| Technology | Detection Method |
|
|
|------------|------------------|
|
|
| Language | File extensions, config files |
|
|
| Framework | package.json, requirements.txt, Cargo.toml |
|
|
| Build system | Makefile, scripts in package.json |
|
|
| Testing | pytest.ini, jest.config.js, go.mod |
|
|
| Docker | Dockerfile, docker-compose.yml |
|
|
| Database | ORM configs, connection strings |
|
|
|
|
## Section Content Guidelines
|
|
|
|
### Project Overview
|
|
- 1-3 sentences describing purpose
|
|
- Target audience if relevant
|
|
- Key technologies used
|
|
|
|
### Quick Start
|
|
- Install command
|
|
- Test command
|
|
- Run command
|
|
- Each with brief inline comment
|
|
|
|
### Critical Rules
|
|
- Numbered or bulleted list
|
|
- Specific, actionable constraints
|
|
- Include rationale for non-obvious rules
|
|
|
|
### Architecture
|
|
- High-level component diagram (ASCII or description)
|
|
- Data flow explanation
|
|
- Key file/directory purposes
|