zhongwei/gh-yebot-rad-cc-plugins-plugins-documentation-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:07:50 +08:00
commit 5ae7faad9c
8 changed files with 1567 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

430
commands/link-docs-to-claude.md Normal file
View File

@@ -0,0 +1,430 @@
---
description: Link all documentation files to CLAUDE.md for better context availability
allowed-tools:
- Bash
- Glob
- Grep
- Read
- Edit
---
# Link All Documentation to CLAUDE.md
Ensure all documentation files in the repository are properly referenced in CLAUDE.md files for maximum context availability.
## Instructions
1. **Find all CLAUDE.md files in the repository**:
```bash
find . -name "CLAUDE.md" -o -name "claude.md" | grep -v node_modules | grep -v .git
```
- Identify the root CLAUDE.md (typically at repository root)
- Note any subdirectory CLAUDE.md files
- These will be the target files for adding documentation references
2. **Inventory all markdown documentation files**:
Use the Glob tool to find all markdown files:
```
pattern: "**/*.md"
```
**Filter the results to exclude:**
- `node_modules/` directories
- `.git/` directories
- Hidden directories (`.*/`)
- The CLAUDE.md files themselves
- Common non-documentation files:
- `README.md` (usually already referenced)
- `CHANGELOG.md`
- `LICENSE.md`
- Package/build files
**Focus on documentation files like:**
- `docs/**/*.md`
- `documentation/**/*.md`
- Architecture documents
- API documentation
- How-to guides
- Technical specifications
- Any `.md` files in project subdirectories
3. **For each documentation file found**:
a) **Read the file to understand its purpose**:
- Use the Read tool to examine the first 20-50 lines
- Identify the document's primary topic/purpose
- Note any key sections or headings
b) **Check if it's already referenced in any CLAUDE.md**:
- Use Grep to search all CLAUDE.md files for the document's path
- Search for both absolute and relative path references
- Check for variations (with/without leading `./`, etc.)
```bash
# Example grep pattern
grep -r "path/to/doc.md" . --include="CLAUDE.md" --include="claude.md"
```
c) **If NOT already referenced**:
- Mark this file as needing a reference
- Determine the best CLAUDE.md file to add it to (see step 4)
4. **Determine the best CLAUDE.md file for each unreferenced doc**:
**Decision logic:**
- **Root CLAUDE.md**: Use for:
- Repository-wide documentation
- Architecture documents
- Top-level guides
- Cross-cutting concerns
- Docs in `docs/` or `documentation/` at root level
- **Subdirectory CLAUDE.md**: Use for:
- Documentation specific to that subdirectory's domain
- Component-specific guides
- Module-level technical docs
- When a CLAUDE.md exists in or near the doc's directory
**When in doubt**: Default to root CLAUDE.md for broader visibility.
5. **Add references to the appropriate CLAUDE.md file(s)**:
a) **Read the target CLAUDE.md file** to understand its structure
b) **Find or create an appropriate section** for documentation references:
- Look for existing sections like:
- "## Documentation"
- "## Additional Resources"
- "## Reference Materials"
- "## Related Documentation"
- If none exist, create a new section near the end:
```markdown
## Related Documentation
Additional documentation files in this repository:
```
c) **Add the reference with a brief context note**:
```markdown
- [Relative/Path/To/Doc.md](Relative/Path/To/Doc.md) - Brief description of what this doc covers
```
**Guidelines for the brief description:**
- One line, 5-15 words
- Describe the purpose or content
- Use active language
- Examples:
- "API endpoint specifications and request/response formats"
- "Database schema design and migration guide"
- "Component architecture and design patterns"
- "Deployment procedures and environment configuration"
d) **Use the Edit tool** to add the reference to the CLAUDE.md file
- Add to existing documentation section if present
- Maintain alphabetical or logical ordering
- Keep consistent formatting with existing references
6. **Optimize documentation link hierarchy** (handle subdirectory CLAUDE.md files):
**Scenario**: A parent CLAUDE.md may contain links to documentation that would be more appropriately referenced in a newly created subdirectory CLAUDE.md file (closer to the relevant code).
a) **For each subdirectory CLAUDE.md file** (if any exist):
- Identify its directory path (e.g., `components/auth/CLAUDE.md`)
- Determine its "scope" (the subdirectory it covers)
b) **Review parent CLAUDE.md files for potentially misplaced references**:
- Read each parent CLAUDE.md (especially root CLAUDE.md)
- Examine all documentation references in the "Related Documentation" or similar sections
c) **Evaluate each reference for relocation**:
For each documentation link in a parent CLAUDE.md, check:
- **Is the referenced file within or closely related to a subdirectory that has its own CLAUDE.md?**
Example scenarios where relocation makes sense:
- Root CLAUDE.md links to `components/auth/README.md` → Move to `components/auth/CLAUDE.md`
- Root CLAUDE.md links to `services/api/endpoints.md` → Move to `services/CLAUDE.md` or `services/api/CLAUDE.md`
- `src/CLAUDE.md` links to `src/utils/helpers/guide.md` → Move to `src/utils/CLAUDE.md`
- **Would the reference provide more value at the lower level?**
Consider:
- Proximity to relevant code
- Specificity of the documentation (component-specific vs. project-wide)
- Whether the subdirectory CLAUDE.md is missing critical context
- **Should it remain at the parent level?**
Keep references in parent CLAUDE.md if:
- Documentation covers cross-cutting concerns
- File provides repository-wide context
- Documentation spans multiple subdirectories
- The doc is a top-level architecture/overview document
d) **Move references when appropriate**:
For references that should be relocated:
1. **Read the subdirectory CLAUDE.md** to understand its structure
2. **Add the reference** to the subdirectory CLAUDE.md:
- Adjust the relative path from the new location
- Place in appropriate section (create "## Related Documentation" if needed)
- Keep the same description or refine it for local context
3. **Remove the reference** from the parent CLAUDE.md:
- Use Edit tool to cleanly remove the line
- Preserve formatting and surrounding references
- Don't leave empty sections (remove section if last item)
e) **Document moved references**:
Keep track of relocations for the summary report:
```
Moved references:
- docs/auth/oauth.md: CLAUDE.md → components/auth/CLAUDE.md
- services/api/endpoints.md: CLAUDE.md → services/CLAUDE.md
```
**Important considerations**:
- Don't create duplicate references (check subdirectory CLAUDE.md first)
- Relative paths will change when moving between CLAUDE.md files
- When in doubt, leave the reference in the parent (no harm in redundancy)
- This is an optimization step—only move references when clearly beneficial
7. **Group related documentation** (optional enhancement):
If multiple documentation files share a common theme or directory:
- Group them together in the CLAUDE.md
- Use subheadings or bullet point hierarchy
- Example:
```markdown
## Related Documentation
### API Documentation
- [docs/api/endpoints.md](docs/api/endpoints.md) - REST API endpoint reference
- [docs/api/authentication.md](docs/api/authentication.md) - Auth flows and token management
### Development Guides
- [docs/setup.md](docs/setup.md) - Local development environment setup
- [docs/testing.md](docs/testing.md) - Testing strategy and guidelines
```
8. **Link child CLAUDE.md files to parent CLAUDE.md files**:
**Purpose**: Create navigation links from parent CLAUDE.md files to child CLAUDE.md files for easy context discovery.
a) **Identify CLAUDE.md hierarchy**:
- From step 1, you have a list of all CLAUDE.md files
- Identify which is the root CLAUDE.md (typically `./CLAUDE.md`)
- Identify all subdirectory CLAUDE.md files (e.g., `./src/components/CLAUDE.md`)
b) **For the root CLAUDE.md** (and any parent CLAUDE.md files):
- **Find all child CLAUDE.md files**:
- Any CLAUDE.md file in a subdirectory relative to this parent
- Example: If parent is `./CLAUDE.md`, children include:
- `./src/components/design/CLAUDE.md`
- `./packages/api/CLAUDE.md`
- `./services/auth/CLAUDE.md`
- **Read each child CLAUDE.md to get context**:
- Read the first 5-10 lines of the child CLAUDE.md
- Extract the title (first `# Heading`) if present
- Infer purpose from title or path if no clear title
- **Check if child is already referenced**:
- Search parent CLAUDE.md for references to the child file path
- Look for existing "## Subdirectory Context Files" or similar section
- **Add or update the "Subdirectory Context Files" section**:
In the parent CLAUDE.md, find or create this section (typically after main content, before "Related Documentation"):
```markdown
## Subdirectory Context Files
Additional CLAUDE.md files in subdirectories provide focused context for specific areas:
- [src/components/design/CLAUDE.md](src/components/design/CLAUDE.md) - Design system components
- [packages/api/CLAUDE.md](packages/api/CLAUDE.md) - Backend API service
- [services/auth/CLAUDE.md](services/auth/CLAUDE.md) - Authentication service
```
**Guidelines for child CLAUDE.md descriptions**:
- Use the title from the child file if available
- Or describe the subdirectory's purpose (e.g., "Backend API service", "Design system components")
- Keep descriptions brief (3-8 words)
- Focus on what that area contains or does
- **Use relative paths**:
- All paths should be relative to the parent CLAUDE.md location
- Example: Root `./CLAUDE.md` → child `./src/auth/CLAUDE.md` = link path `src/auth/CLAUDE.md`
- **Use Edit tool to add the section**:
- If section doesn't exist, add it before "## Related Documentation"
- If section exists, add missing child references
- Keep links alphabetically sorted or grouped logically by area
- Don't duplicate existing references
c) **Handle nested hierarchies** (if applicable):
- If a subdirectory CLAUDE.md also has children (e.g., `src/CLAUDE.md` and `src/components/CLAUDE.md`):
- Link `./CLAUDE.md` → `src/CLAUDE.md` (child)
- Link `src/CLAUDE.md` → `src/components/CLAUDE.md` (grandchild)
- Each parent only links to its direct children, not grandchildren
- This creates a natural navigation hierarchy:
```
./CLAUDE.md
└── links to: src/CLAUDE.md, packages/CLAUDE.md
src/CLAUDE.md
└── links to: src/components/CLAUDE.md, src/utils/CLAUDE.md
```
d) **Track child CLAUDE.md links for reporting**:
Keep count of:
- Child CLAUDE.md files found
- Child CLAUDE.md links already present
- New child CLAUDE.md links added
- Which parent files were updated
9. **Report results to the user**:
Provide a summary:
```
📚 Documentation Linking Complete!
Total markdown files found: X
Already referenced in CLAUDE.md: Y
Newly added references: Z
References relocated: M
Child CLAUDE.md files:
- Total child CLAUDE.md files found: N
- Child CLAUDE.md links added: P
Updated files:
- CLAUDE.md (+Z references, -M moved, +P child CLAUDE.md links)
- path/to/subdirectory/CLAUDE.md (+N references, +M moved in)
New references added:
- docs/api/endpoints.md → CLAUDE.md
- docs/setup.md → CLAUDE.md
- components/auth/README.md → components/CLAUDE.md
References relocated for better hierarchy:
- components/auth/oauth-guide.md: CLAUDE.md → components/auth/CLAUDE.md
- services/api/endpoints.md: CLAUDE.md → services/CLAUDE.md
Child CLAUDE.md links added:
- src/components/design/CLAUDE.md → CLAUDE.md
- packages/api/CLAUDE.md → CLAUDE.md
```
10. **Suggest next steps**:
- "Review the added references for accuracy"
- "Consider updating the brief descriptions if needed"
- "Run this command periodically to catch new documentation"
## Important Guidelines
### What to Reference
- ✅ Technical documentation files
- ✅ Architecture and design docs
- ✅ API specifications
- ✅ How-to guides and tutorials
- ✅ Developer onboarding docs
- ✅ Configuration references
### What to Skip
- ❌ CLAUDE.md files in "Related Documentation" sections (but DO link them in "Subdirectory Context Files")
- ❌ README.md at root (usually already referenced or primary doc)
- ❌ CHANGELOG.md (version history, not context)
- ❌ LICENSE.md (legal, not development context)
- ❌ node_modules/ and vendor directories
- ❌ Build output or generated files
- ❌ Package manager files (package.json, etc.)
### Reference Format
- Always use relative paths from the CLAUDE.md location
- Use markdown link syntax: `[display text](path/to/file.md)`
- Include brief, helpful descriptions
- Maintain consistent formatting with existing references
### Best Practices
- Group related documentation together
- Use clear section headers
- Keep descriptions concise but informative
- Alphabetize or logically order references
- Use Edit tool to maintain file formatting
- Don't duplicate references (check first!)
## Error Handling
| Issue | Solution |
|-------|----------|
| No CLAUDE.md found | Create one at root with basic structure |
| CLAUDE.md has no documentation section | Create "## Related Documentation" section |
| Ambiguous best location | Default to root CLAUDE.md, note in description |
| File already referenced | Skip, note in summary |
| Circular reference risk | Never reference CLAUDE.md in itself |
| Binary or non-text .md files | Skip after read attempt fails |
## Example Output Structure
For a root CLAUDE.md file after running this command:
```markdown
# Project Name
Project overview and instructions...
## Repository Structure
...existing content...
## Subdirectory Context Files
Additional CLAUDE.md files in subdirectories provide focused context for specific areas:
- [src/components/design/CLAUDE.md](src/components/design/CLAUDE.md) - Design system components
- [packages/api/CLAUDE.md](packages/api/CLAUDE.md) - Backend API service
- [services/auth/CLAUDE.md](services/auth/CLAUDE.md) - Authentication service
## Related Documentation
Additional documentation files in this repository:
- [docs/api/endpoints.md](docs/api/endpoints.md) - REST API endpoint specifications
- [docs/api/authentication.md](docs/api/authentication.md) - OAuth2 authentication flow
- [docs/architecture/database.md](docs/architecture/database.md) - Database schema and design patterns
- [docs/deployment.md](docs/deployment.md) - Production deployment procedures
- [docs/setup.md](docs/setup.md) - Local development environment setup
- [docs/testing.md](docs/testing.md) - Testing strategy and CI/CD integration
```
## Definition of Done
- [ ] All CLAUDE.md files identified
- [ ] All markdown documentation files inventoried
- [ ] Each doc checked for existing references
- [ ] Unreferenced docs identified
- [ ] Best CLAUDE.md target determined for each unreferenced doc
- [ ] References added with appropriate brief descriptions
- [ ] Documentation link hierarchy optimized (references moved to subdirectory CLAUDE.md files where appropriate)
- [ ] Relative paths updated correctly for any moved references
- [ ] Child CLAUDE.md files identified and hierarchy established
- [ ] Parent CLAUDE.md files updated with "Subdirectory Context Files" section
- [ ] All child CLAUDE.md files linked from appropriate parent CLAUDE.md files
- [ ] Child CLAUDE.md descriptions extracted or inferred
- [ ] CLAUDE.md files updated using Edit tool
- [ ] Summary report provided to user (including child CLAUDE.md links)
- [ ] No duplicate references created
- [ ] No circular references created
- [ ] User informed of next steps