documenting-with-claude-md

bryonjacob's avatarfrom bryonjacob

Hierarchical machine-readable documentation - root CLAUDE.md with module index, per-module CLAUDE.md for significant modules

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025
[Developer Tools]

When & Why to Use This Skill

Optimize your AI-assisted development workflow with the Documenting with CLAUDE.md skill. This tool establishes a hierarchical, machine-readable documentation framework designed specifically for AI agents to grasp codebase context instantly. By organizing project data into a root overview and granular module-level files, it ensures that AI assistants understand your architecture, tech stack, and logic rationale without the overhead of human-centric documentation, leading to more accurate code generation and debugging.

Use Cases

  • AI Project Onboarding: Quickly provide a structured map of a complex repository to an AI agent, reducing the time it takes for the assistant to become productive.
  • Architectural Context Management: Maintain a root CLAUDE.md to define high-level design patterns and tech stacks, ensuring the AI adheres to project-wide standards.
  • Modular Logic Documentation: Use per-module CLAUDE.md files to define public interfaces and dependencies for significant modules, preventing AI errors in cross-module integration.
  • Rationale Tracking: Implement standardized 'why-based' commenting and documentation to help AI agents understand the business logic and constraints behind complex algorithms during refactoring.
namedocumenting-with-claude-md
descriptionHierarchical machine-readable documentation - root CLAUDE.md with module index, per-module CLAUDE.md for significant modules

Documenting with CLAUDE.md

Purpose

Machine-first documentation that loads automatically with code. Two-level hierarchy: root overview + per-module context.

Not for human browsing - for instant AI understanding.

Templates

Root CLAUDE.md (required):

# Project Name

## Purpose
What this does and why it exists

## Architecture Overview
High-level design, key patterns

## Module Index
- `src/auth/` - Authentication (see src/auth/CLAUDE.md)
- `src/api/` - REST API (see src/api/CLAUDE.md)

## Tech Stack
- Language/framework
- Key dependencies

## Development
See ~/.claude/CLAUDE.md for standard workflow

Module CLAUDE.md (significant modules only):

# Module: Authentication

## Purpose
Handles user authentication and sessions

## Responsibilities
- User login/logout
- Token generation/validation
- Session management

## Key Files
- `auth_service.py` - Core logic
- `token_handler.py` - JWT operations

## Dependencies
- **Uses:** db, utils
- **Used by:** api

## Public Interface
- `authenticate(email, password) -> Token`
- `validate_token(token) -> User`

## Architecture Decisions
- JWT for stateless auth (no session storage)
- 24-hour token expiry

When to Create

Significant modules (3+ files, distinct domain):

  • Create module CLAUDE.md
  • Add to root module index
  • Update when responsibilities/interface change

Don't create for:

  • Single-file directories
  • Test directories
  • Utility folders (<3 simple files)

Code Comments

Comment the "why" not the "what":

# ❌ Bad (obvious)
if user_type == "premium":
    return total * 0.2  # Return 20% discount

# ✅ Good (explains rationale)
if user_type == "premium":
    return total * 0.2  # 20% incentivizes membership

Always comment:

  • Non-obvious algorithms
  • Performance/security decisions
  • Bug workarounds
  • Business logic rationale

Usage Patterns

New module: Create module CLAUDE.md from template, add to root module index, keep updated as code evolves.

Existing code: Start with root CLAUDE.md and module index, then add CLAUDE.md for significant modules along with docstrings and comments.

Maintenance

Keep current:

  • Update module CLAUDE.md when responsibilities change
  • Update root index when modules added/removed
  • Update docstrings when signatures change
  • Outdated docs worse than no docs