@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:

• ✅ Preserves existing operational knowledge - Never loses setup, deployment, or troubleshooting procedures
• ✅ Focuses on custom business logic and unique features
• ✅ Merges rather than replaces - Enhances existing docs with custom functionality focus
• ✅ 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)

• Requires /init to run first
• Restructures README into Standard README format (with TOC, Contributing, License)
• Preserves all operational knowledge (setup, testing, deployment, troubleshooting)
• 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

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

Preservation First: All existing setup, testing, deployment, and troubleshooting procedures are maintained exactly

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 + Preservation)

• README.md - Restructured into Standard README format with:
  • Table of Contents
  • Installation, Usage, Testing sections (all preserved)
  • Contributing, Maintainers, License (added)
  • Professional structure with zero content loss
• CLAUDE.md - Enhanced with development commands and workflows
• docs/DEVELOPMENT.md - Detailed workflows (all original installation steps preserved)
• 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: Preservation-First Approach

• Reads existing documentation first before making any changes
• Preserves all operational knowledge while enhancing with custom functionality focus
• Warns users before destructive changes and requires confirmation
• Merges rather than replaces - maintains setup procedures while adding business context

What Gets Preserved

• ✅ Installation steps - Exact commands, environment configuration, dependency setup
• ✅ Testing procedures - Database setup, test running commands, browser testing
• ✅ Deployment workflows - Production setup, CI/CD, custom deployment procedures
• ✅ Troubleshooting guides - Known issues, debugging procedures, common problems
• ✅ Domain knowledge - Business processes, custom workflows, project-specific information

💡 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