DOCSEARCHbyAlgolia
Submit Docs

ClaudeForge Documentation

repository·dev·Indexed 19 days ago

https://github.com/alirezarezvani/claudeforge

A toolkit for automating the creation, enhancement, and maintenance of CLAUDE.md files for Claude Code projects. It includes the claudeforge-skill, the /enhance-claude-md and /sync-claude-md slash commands, and the claude-md-guardian background agent for intelligent change detection and documentation synchronization.

Tokens
42.2K
Snippets
114
Records
177
Agent score
64%

What's inside ClaudeForge

  1. Project Architecture and Tech Stack

    dev

    The application is a full-stack production-grade system using a modular service-oriented architecture.

    Core Stack

    • Frontend: React 18 (TypeScript 5) with Tailwind CSS and React Query, served via Nginx.
    • Backend: Node.js 20 with Express 4 (TypeScript) and Prisma ORM.
    • Database: PostgreSQL 15.
    • Caching: Redis 7 for sessions and data caching.
    • Async Processing: RabbitMQ for message queuing.
    • Infrastructure: Docker containers, Kubernetes orchestration, and GitHub Actions for CI/CD.

    Data Flow

    Client (React) → Nginx → Express API → PostgreSQL Additionally, the API interacts with Redis Cache and pushes tasks to the RabbitMQ Queue for asynchronous processing.

  2. Overview of ClaudeForge Skills

    dev

    ClaudeForge includes several specialized skills that extend the capabilities of Claude Code:

    • claudeforge-skill: The core engine for analysis, validation, and generation. It runs on model: haiku and is scoped to trigger only when instruction files (like CLAUDE.md or .cursorrules) are touched.
    • karpathy-guidelines: Automatically embeds behavioral guidelines (Think Before Coding, Simplicity First, etc.) into generated files. It is also available as a standalone skill scoped to common source-file extensions.
    • claude-md-drift-audit: A read-only skill that uses git history to find stale references in your documentation.
    • claude-md-link-check: A read-only skill that verifies all @path imports and markdown links resolve correctly.
    • claude-md-dependency-rescan: A read-only skill that ensures your CLAUDE.md Tech Stack section matches your actual dependency manifests (e.g., package.json, requirements.txt).

  3. Understand the CLAUDE.md Quality Scoring Algorithm

    dev

    ClaudeForge evaluates your CLAUDE.md file using a scoring algorithm (0-100) based on several criteria. This helps you identify where your documentation needs improvement:

    • Length Appropriateness (25 points):
      • 20–300 lines: Full points.
      • 300–400 lines: Partial points (warning: consider modularizing).
      • <20 or >400 lines: Low points.
    • Section Completeness (25 points): Checks for required sections: Core Principles, Tech Stack, and Workflow.
    • Formatting Quality (20 points): Evaluates headings, code blocks, lists, and links.
    • Content Specificity (15 points): Checks if content is project-specific rather than generic.
    • Modular Organization (15 points): Checks if context files are used for larger projects.

  4. Understand the CLAUDE.md initialization workflow

    dev

    When you ask the skill to create a CLAUDE.md file for a project where one does not exist, it follows an intelligent, interactive workflow:

    1. Detection: Checks for an existing CLAUDE.md in the project root.
    2. Exploration: Uses Claude Code's built-in commands to analyze the repository structure, configuration files (like package.json or requirements.txt), and existing documentation.
    3. Intelligent Analysis: Detects project type, tech stack, team size, development phase, and recommended architecture (single file vs. modular).
    4. User Confirmation ✋: Displays all discoveries and the recommended structure. The user must explicitly approve or adjust settings before any files are created.
    5. File Creation: Generates the customized CLAUDE.md file(s) and applies tech-specific best practices.
    6. Enhancement & Validation: Ensures the generated content is complete and follows quality standards.
    7. Summary: Provides a report of created files and suggested next steps.

  5. How claudeforge-skill works: Core Modules

    dev

    The skill is composed of several Python modules that handle different stages of the CLAUDE.md lifecycle:

    • workflow.py (InitializationWorkflow): Manages the 7-step interactive process: checking for existing files, exploring the repo, analyzing discoveries (project type, tech stack, team size), requesting confirmation, creating files, enhancing with best practices, and providing a summary.
    • analyzer.py (CLAUDEMDAnalyzer): Performs comprehensive analysis, detects sections, calculates a quality score (0-100), and generates improvement recommendations.
    • validator.py (BestPracticesValidator): Validates files against specific criteria like length (recommended 20-300 lines), structure, formatting, and anti-patterns (e.g., hardcoded secrets).
    • generator.py (ContentGenerator): Handles the creation of root files, context-specific files (e.g., backend/, frontend/), and individual sections.
    • template_selector.py (TemplateSelector): Selects and customizes templates based on a matrix of Project Type, Team Size, and Complexity.

  6. Token efficiency and model usage

    dev

    ClaudeForge optimizes token usage by using different models for different tasks:

    • Guardian Agent (haiku model): Used for routine updates and targeted section updates. This approach saves 70-80% of tokens compared to full regeneration, typically consuming only 500-1000 tokens per update.
    • Slash Commands (sonnet model): Used for interactive, user-facing commands that require complex reasoning and better understanding.

  7. How claude-md-guardian and claudeforge-skill work together

    dev

    The claude-md-guardian agent acts as the orchestrator, while claudeforge-skill provides the execution logic.

    1. Detection: The claude-md-guardian agent detects changes (e.g., via SessionStart, after feature completion, or after major refactoring).
    2. Invocation: The agent automatically invokes the claudeforge-skill.
    3. Update: The skill processes the changes and updates the CLAUDE.md file to keep it synchronized with the codebase.

    In version 2.0.0+, the agent uses a permissions: syntax to control tool access, such as allowing Bash(git:*), Read, Write, and Skill(claudeforge-skill).

    permissions:
  allow:
    - Bash(git:*)
    - Read
    - Write
    - Skill(claudeforge-skill)

  8. How claude-md-guardian maintains CLAUDE.md

    dev

    The claude-md-guardian agent automates the maintenance of CLAUDE.md files through a four-step process:

    1. Change Detection: Analyzes git history for new dependencies (package.json, requirements.txt), directory/file structure changes, configuration updates (.env.example), and architecture pattern changes.
    2. Scope Determination: Determines if the update is Minor (1-2 sections), Moderate (3-4 sections), or Major (full quality check/refactoring).
    3. Targeted Updates: Uses the claudeforge-skill to update only specific sections to preserve existing content and minimize token usage:
      • Tech Stack: For dependency changes.
      • Project Structure: For directory changes.
      • Setup & Installation: For configuration changes.
      • Architecture: For pattern changes.
      • Common Commands: For script changes.
    4. Validation: Ensures all updates follow native Claude Code formatting rules.

    Model Selection & Efficiency

    • haiku (default): Used for routine, minor, or moderate updates to remain cost-effective.
    • sonnet (escalation): Used for major architecture changes or first-time generation.

    This targeted approach ensures the agent remains token-efficient and does not interrupt active development workflows.

  9. Understand the project architecture and data flow

    dev

    The project follows a Layer Pattern to separate concerns:

    FastAPI → Services → Models → Database

    Component Responsibilities:

    • Endpoints (app/api/v1/endpoints): The HTTP layer. Handles request/response logic using Pydantic schemas.
    • Services (app/services): The business logic layer. Contains reusable logic that is decoupled from HTTP concerns.
    • Models (app/models): The data access layer using async SQLAlchemy 2.0.
    • Schemas (app/schemas): Pydantic models used for request and response validation.
    • Dependencies (app/api/v1/dependencies.py): Shared resources like DB sessions or current user authentication.

    Request Lifecycle:

    HTTP Request → Router → Dependency Injection → Endpoint → Service → Model → Database
    (The response is then returned as a Pydantic schema)

  10. Generate a modular CLAUDE.md architecture

    dev

    For large projects (e.g., full-stack, large teams, or enterprise phase), the skill can generate a modular architecture instead of a single monolithic file. This involves creating a root CLAUDE.md that acts as a navigation hub, along with context-specific files in subdirectories:

    • backend/CLAUDE.md: API design, database, and testing.
    • frontend/CLAUDE.md: Components, state, and styling.
    • database/CLAUDE.md: Schema, migrations, and queries.
    • .github/CLAUDE.md: CI/CD workflows.

  11. Maintain the CLAUDE.md bidirectional link chain

    dev

    The project uses a structured linking system to connect the root documentation to subdirectory documentation. /sync-claude-md ensures this chain is never broken.

    Link Requirements

    • Root CLAUDE.md: Must contain a Quick Navigation block that lists every sub-CLAUDE.md and includes a @<relative-path> import line for each.
    • Sub-CLAUDE.md: Must contain a back-link at the top of the file pointing to the parent (e.g., ../CLAUDE.md) using both a standard markdown link and a @../CLAUDE.md import.

    If sub-files are deleted, the command automatically removes their corresponding entries from the root navigation chain.

  12. Setup modular CLAUDE.md for full-stack applications

    dev

    In large projects with distinct backend and frontend directories, running /enhance-claude-md at the root can result in a modular documentation structure. This typically includes a root CLAUDE.md for navigation and sub-directory CLAUDE.md files (e.g., backend/CLAUDE.md, frontend/CLAUDE.md) containing specific patterns for those layers.

    # Example structure
mkdir fullstack-app
cd fullstack-app
mkdir backend frontend

# Run command at root
/enhance-claude-md