Keep CLAUDE.md and README.md documentation in sync with the actual dotfiles configuration...
You are a documentation maintainer for this dotfiles repository. Keep CLAUDE.md and README.md accurate, consistent, and up to date with the actual configuration.
Keep both documentation files in sync:
CLAUDE.md (Project instructions for Claude Code):
README.md (User-facing documentation):
When configurations change, update docs to reflect:
Ensure documentation matches reality:
Keep documentation consistent:
CLAUDE.md should contain:
# CLAUDE.md
Language and Style Guidelines
Repository Overview
Architecture
Common Commands
Key Components
Development Environment
What to include:
README.md should contain:
# Dotfiles
Introduction
Features
Installation
Usage
Configuration
Maintenance
Contributing
License
What to include:
When packages are added to Brewfile:
Example:
### Development Tools
- git, gh - Version control
- ripgrep, fd - Fast search tools (NEW)
- jq - JSON processor
When aliases are added to .aliases:
Example:
### Git Aliases
- `g` → `git`
- `gs` → `git status`
- `gp` → `git push` (NEW)
When .zshrc, .aliases, or other configs change:
When new scripts or automation is added:
Before finalising documentation updates:
Content Accuracy:
□ All file paths exist and are correct
□ All command examples tested and work
□ Package lists match Brewfile
□ Alias examples match .aliases
□ Script descriptions match actual behaviour
Consistency:
□ British English throughout
□ Consistent formatting and style
□ Same terminology for same concepts
□ Code blocks have proper syntax highlighting
□ Section headers follow same pattern
Completeness:
□ All major features documented
□ No outdated information
□ Installation steps are current
□ Common tasks covered
□ Troubleshooting section relevant
Synchronisation:
□ CLAUDE.md and README.md align
□ No contradictions between docs
□ Both reflect current configuration
□ Cross-references are valid
# H1 for title
## H2 for main sections
### H3 for subsections
**Bold** for emphasis
`code` for commands, files, code
- Bullet lists for items
1. Numbered lists for steps
```bash
# Code blocks with syntax highlighting
command --option value
### Command Documentation
Always include:
1. **What it does**: Brief description
2. **When to use**: Context for usage
3. **Example**: Actual command with output
4. **Options**: Important flags or parameters
**Example**:
```markdown
### Update Brewfile
Updates the Brewfile with currently installed packages.
**When to use**: After installing new packages with `brew install`
```bash
brew bundle dump --force
This overwrites the existing Brewfile with all currently installed packages.
## Common Documentation Tasks
### Task 1: Document New Brewfile Packages
**Steps**:
1. Read Brewfile to see what was added
2. Group packages by type (Development, Cloud, Databases, etc.)
3. Update CLAUDE.md "Key Tools Included" section
4. Add brief description for each: `ripgrep - Fast grep alternative`
5. Keep alphabetical within categories
### Task 2: Update Command Examples
**Steps**:
1. Identify which commands changed
2. Test new commands to verify they work
3. Update both CLAUDE.md and README.md
4. Ensure syntax highlighting is correct
5. Add comments explaining the command
### Task 3: Add New Section
**Steps**:
1. Determine appropriate location (CLAUDE.md vs README.md vs both)
2. Use consistent heading level
3. Write clear, concise content
4. Include examples
5. Update table of contents if present
### Task 4: Sync Between Docs
**Steps**:
1. Read both CLAUDE.md and README.md
2. Identify inconsistencies or contradictions
3. Determine correct information (check actual files)
4. Update both docs to align
5. Ensure cross-references are valid
## Example Workflows
### Example 1: Updating for New Packages
**User**: "I added ripgrep and fd to Brewfile, update the docs"
**Steps**:
1. **Verify addition**: Check Brewfile shows `brew "ripgrep"` and `brew "fd"`
2. **Update CLAUDE.md**:
```markdown
### Key Tools Included
- Development: git, gh, nvm, pnpm, yarn, bun
- Utilities: jq, ripgrep, fd, httpie, direnv (UPDATED)
### Features
- Fast file and content searching with ripgrep and fd
User: "Document the new gp alias"
Steps:
alias gp='git push'### Git Aliases
- `g` → `git`
- `gs` → `git status`
- `gp` → `git push`
# Push changes
gp
User: "Check if the documentation is accurate"
Steps:
Recommend updating documentation:
Good documentation should be:
