CLAUDE.md Authoring
Create and update CLAUDE.md files tailored to project type with appropriate sections and content.
Purpose of CLAUDE.md
CLAUDE.md provides Claude Code with project-specific context:
- •Project structure and architecture
- •Common commands and workflows
- •Conventions and preferences
- •Quick reference information
Section Selection by Project Type
Select sections based on detected project type:
Infrastructure Projects
| Section | Include | Content |
|---|---|---|
| Quick Reference | Always | Common kubectl/helm commands |
| Cluster Architecture | Always | Nodes, resources, network |
| Service Catalog | Always | Services, URLs, ports |
| Storage | If NFS/PV used | Storage classes, PVCs |
| GitOps Workflow | If ArgoCD | App structure, deployment flow |
| Monitoring | If Prometheus/Grafana | Dashboards, alerts |
| Security | If secrets/certs | SealedSecrets, cert-manager |
Code Projects
| Section | Include | Content |
|---|---|---|
| Quick Reference | Always | Build, test, run commands |
| Project Structure | Always | Directory layout |
| Development | Always | Setup, dependencies |
| Testing | If tests exist | Test commands, coverage |
| API Reference | If API project | Endpoints, auth |
| Deployment | If CI/CD exists | Pipeline, environments |
Monorepo Projects
| Section | Include | Content |
|---|---|---|
| Quick Reference | Always | Workspace commands |
| Package Overview | Always | Package list, purposes |
| Dependency Graph | If complex | Internal dependencies |
| Build Order | If relevant | Build sequence |
| Shared Config | If exists | Shared tsconfig, eslint |
CLAUDE.md Structure
Follow this general structure:
markdown
# Project Name ## Quick Reference \`\`\`bash # Most common commands here \`\`\` --- ## 1. [Primary Section] ### 1.1 [Subsection] | Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Data | Data | Data | --- ## 2. [Secondary Section] [Content] --- ## N. User Preferences [Tools, aliases, conventions]
Writing Guidelines
- •Be concise: Use tables over prose where possible
- •Use headers: Create scannable structure with
##and### - •Include commands: Wrap in code blocks with language hints
- •Add separators: Use
---between major sections - •Prefer tables: For lists of items with multiple attributes
- •Keep current: Only document what actually exists
Update Workflow
To update an existing CLAUDE.md:
- •Read current file to understand existing structure
- •Analyze project to detect current state
- •Compare documented vs actual state
- •Generate diff showing proposed changes
- •Present to user for confirmation
- •Apply changes if approved
Diff Format
Present changes as unified diff:
diff
## Services | Service | URL | |---------|-----| - | Old Service | old.url | + | New Service | new.url | | Unchanged | same.url |
Additional Resources
Template Files
Project-specific templates:
- •
templates/infra-template.md- Kubernetes/ArgoCD template - •
templates/code-template.md- Code project template - •
templates/monorepo-template.md- Monorepo template