@batch/claude-docs

Complete documentation toolkit for Claude Code with specialized commands that focus on custom functionality over framework boilerplate.

🎯 What This Does

This package provides three specialized documentation commands that:

• ✅ Focuses on custom business logic and unique features
• ✅ Skips standard framework patterns that developers already know
• ✅ Reduces information overload with 3-4 focused files max
• ✅ Maintains universality across any project type

🚀 Quick Start

# Run in any project directory
npx @batch/claude-docs

This installs a complete command suite in .claude/commands/ for use with Claude Code.

📋 Usage

1. Install the commands in your project directory: npx @batch/claude-docs
2. Open Claude Code with your project
3. Choose your workflow:
   • /docs-generate - Create comprehensive project documentation
   • /docs-update - Update existing docs selectively
   • /onboard - Generate developer onboarding guides
4. Get focused documentation that highlights what makes your project unique

🧭 CLAUDE.md vs Claude's /init

/docs-generate creates a comprehensive CLAUDE.md

• Multiple files: Creates README.md, DEVELOPMENT.md, ARCHITECTURE.md, AND a sophisticated CLAUDE.md
• Rich content: The CLAUDE.md includes project-specific commands, 70/20/10 documentation structure, implementation details
• Integration: References and connects to the other documentation files

Claude's built-in /init creates basic CLAUDE.md

• Single file: Just creates a basic CLAUDE.md
• Basic content: Simple project overview and context
• Quick setup: Minimal starter file

Key Difference

/docs-generate gives you a supercharged CLAUDE.md as part of a complete documentation ecosystem, while /init just creates a basic starter file.

What the generated CLAUDE.md does:

• Steers documentation outputs towards custom functionality (aligns with the 70/20/10 rule)
• Signals the PR reminder workflow when documentation is updated (the workflow checks CLAUDE.md casing)
• Provides context that helps Claude produce more accurate, consistent docs
• Remains owner‑maintained (subsequent installs won't overwrite it)

🎨 What You Get

The generated documentation emphasizes:

• 70% Custom Business Logic - Your unique algorithms, workflows, integrations
• 20% Modified Framework Patterns - How you've customized standard patterns
• 10% Essential Setup - Only what's needed to get started

📁 What You Get

/docs-generate - Comprehensive Documentation

• README.md - Project overview with custom feature highlights
• docs/DEVELOPMENT.md - Essential setup and custom workflows
• docs/ARCHITECTURE.md - Unique architectural decisions and WHY
• docs/BACKEND.md - Backend integration patterns (when applicable)
• CLAUDE.md - Comprehensive project guide for Claude and developers

/docs-update - Selective Updates

• Intelligent analysis of what actually needs updating
• Avoids documentation churn for minor changes
• Focuses on developer-impacting changes only

/onboard - Developer Onboarding

• Step-by-step setup guide with verification steps
• Common issues and solutions for new team members
• Success criteria for completed onboarding

🔄 Updating

Updating the Package

# Re-run to get latest version and update commands + workflow
npx @batch/claude-docs@latest

What gets updated:

• ✅ Commands - Latest versions replace existing commands in .claude/commands/
• ✅ GitHub Actions workflow - Updated workflow replaces existing one
• ✅ No action needed - Your existing documentation stays untouched

Updating Documentation in Your Project

After updating the package, no additional steps are required. Your documentation remains as-is.

When you want to refresh documentation:

• Use /docs-update command in Claude Code for selective updates
• Use /docs-generate for comprehensive regeneration (overwrites existing docs)

🤖 GitHub Actions Workflow

When you run npx @batch/claude-docs, it automatically creates .github/workflows/docs-update.yml that:

What It Does

• Monitors PRs for significant changes (dependencies, API routes, config files)
• Comments automatically when documentation updates may be needed
• Skips reminders if docs were already updated in the PR
• Detects project type (Next.js, Gatsby, Craft CMS, PHP, Sanity) for relevant suggestions

When It Triggers

• Dependencies changed (package.json, composer.json)
• API routes modified (src/app/api/, functions/, etc.)
• Configuration files updated (next.config.js, middleware, etc.)
• Environment variables changed (.env.example)
• Schema or data structure changes (src/queries/, schemas/)

Smart Behavior

• ✅ Already Updated: "Documentation files were updated in this PR"
• 📚 Needs Update: Specific suggestions based on what changed
• 🎯 Project-Aware: Tailored advice for your tech stack

This helps maintain documentation quality without being annoying - it only reminds when genuinely needed.

💡 Philosophy

Traditional documentation generators create comprehensive but overwhelming docs. This toolkit provides workflow-specific commands that help developers understand what makes your project special, not how to use React.

Three specialized workflows:

• Generate - Comprehensive docs for new projects or major overhauls
• Update - Selective updates that maintain quality without churn
• Onboard - Focused guides that get new developers productive quickly

🤝 Contributing

Issues and PRs welcome at batchnz/claude-docs

📄 License

MIT License - See LICENSE file for details