@batch/claude-docs

Complete documentation toolkit for Claude Code with specialized commands that focus on custom functionality over framework boilerplate while preserving existing operational knowledge.

🎯 What This Does

This package provides three specialized documentation commands that:

• ✅ Rewrites for consistency - Professional voice throughout while preserving 100% technical accuracy
• ✅ Preserves all factual content - Never loses commands, configurations, or procedures
• ✅ Focuses on custom business logic and unique features
• ✅ Standard README format - Professional, discoverable documentation
• ✅ Reduces information overload with 4-5 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

Initial Setup

1. Install the commands in your project directory:

   npx @batch/claude-docs

2. Open Claude Code with your project:

   claude /path/to/your/project

Generate Complete Documentation

3. Run /init first (required for /docs-generate):

   /init

   This creates foundational project understanding in CLAUDE.md

4. Run /docs-generate for complete documentation:

   /docs-generate

   This creates:

   • Standard README format with TOC, Contributing, License
   • docs/ARCHITECTURE.md (custom features focus)
   • docs/DEVELOPMENT.md (detailed workflows)
   • Enhanced CLAUDE.md with development commands
   • GitHub Actions workflow

Other Workflows

• /docs-update - Update existing docs selectively (no /init needed)
• /onboard - Generate developer onboarding guides (no /init needed)

Result: Professional, standards-compliant documentation that preserves all operational knowledge

🧭 Documentation Workflow

The /init + /docs-generate Approach

New in v4.0: /docs-generate now requires running /init first for better project understanding.

1. /init (Claude's built-in command)

• Creates foundational CLAUDE.md with project understanding
• Analyzes codebase structure and patterns
• Provides context foundation for documentation

2. /docs-generate (This package)

New in v4.1: Now rewrites documentation in consistent professional voice while preserving 100% technical accuracy.

• Requires /init to run first
• Rewrites README into Standard README format with consistent, professional voice
• Preserves all factual content - exact commands, configurations, paths, procedures
• Creates comprehensive supporting docs focusing on custom features (70/20/10 rule)
• Enhances CLAUDE.md with development commands and workflows

Why This Approach?

Better Project Understanding: /init provides deep codebase analysis that informs higher-quality documentation

Professional Consistency: All documentation rewritten in unified, professional voice for better readability

Standard README Format: Your README follows industry conventions, making projects more discoverable

100% Technical Accuracy: Every command, path, and configuration preserved exactly - only presentation improved

Custom Focus: Supporting docs emphasize what makes your project unique (custom business logic, integrations, architecture)

📁 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

/docs-generate - Comprehensive Documentation (Standard README + Consistent Rewriting)

• README.md - Rewritten into Standard README format with:
  • Professional, consistent voice throughout
  • Table of Contents for easy navigation
  • Installation, Usage, Testing sections (all commands preserved exactly)
  • Contributing, Maintainers, License sections added
  • 100% technical accuracy with improved presentation
• CLAUDE.md - Enhanced with development commands and workflows
• docs/DEVELOPMENT.md - Detailed workflows (all procedures rewritten consistently)
• docs/ARCHITECTURE.md - Custom features and technical decisions (70/20/10 focus)
• docs/BACKEND.md - Backend integration patterns (when applicable)

/docs-update - Selective Updates (Preservation-Safe)

• Reads existing documentation first to preserve valuable content
• Intelligent analysis of what actually needs updating
• Avoids documentation churn for minor changes
• Focuses on developer-impacting changes only

/onboard - Developer Onboarding (README-Powered)

• Leverages existing setup procedures from README and docs
• Step-by-step setup guide with verification steps (transforms existing docs into beginner-friendly format)
• 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 (no /init needed)
• Use /init then /docs-generate for comprehensive regeneration with Standard README format

🤖 GitHub Actions Workflow

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

What It Does

• Scans your codebase to detect project structure (Next.js, Gatsby, Craft CMS, Vue.js, Sanity, etc.)
• Monitors only relevant files based on your actual project structure
• Comments automatically when documentation updates may be needed
• Skips reminders if docs were already updated in the PR

When It Triggers (Project-Aware)

• Dependencies changed (package.json, composer.json)
• API routes modified (only paths that exist in your project)
• Configuration files updated (only configs you actually use)
• Environment variables changed (.env.example)
• Project structure changes (templates, schemas, etc. based on your tech stack)

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.

🛡️ Documentation Preservation

The Problem We Solve

Traditional documentation generators destructively replace existing documentation, causing loss of critical operational knowledge like:

• Detailed installation procedures (environment setup, binary paths, database configuration)
• Testing workflows and debugging procedures
• Deployment processes and production setup
• Troubleshooting guides and known issues
• Domain-specific business knowledge

Our Solution: Content Preservation with Professional Consistency (v4.1+)

• Reads existing documentation first before making any changes
• Extracts all factual content - commands, configurations, paths, procedures
• Rewrites in consistent professional voice - unified style throughout
• Preserves 100% technical accuracy - every command and configuration exact
• Enhances with context - explains WHY behind steps and features

What Gets Preserved (with Improved Presentation)

• ✅ Installation commands - Exact commands with enhanced explanatory text
• ✅ Configuration details - All paths, credentials, environment vars preserved exactly
• ✅ Testing procedures - Database setup and test commands preserved with clear context
• ✅ Deployment workflows - All production setup steps rewritten for consistency
• ✅ Troubleshooting guides - Solutions preserved exactly, explanations improved
• ✅ Domain knowledge - Business context enhanced with professional writing

💡 Philosophy

Traditional documentation generators create comprehensive but overwhelming docs while often destroying valuable existing knowledge. This toolkit provides workflow-specific commands that help developers understand what makes your project special while preserving all operational knowledge.

Three specialized workflows:

• Generate - Comprehensive docs for new projects or major overhauls (with preservation-first approach)
• Update - Selective updates that maintain quality without churn (preservation-safe)
• Onboard - Focused guides that get new developers productive quickly (leverages existing setup docs)

🤝 Contributing

Issues and PRs welcome at batch/claude-docs

📄 License

MIT License - See LICENSE file for details