ClaudeForge/CLAUDE.md

CLAUDE.md

Top-level guidance for Claude Code when working on this repository.

Project Overview

ClaudeForge is a Claude Code plugin (manifest at .claude-plugin/plugin.json) and standalone toolkit for the CLAUDE.md lifecycle: initialise, enhance, sync, and modularise files with a hard 150-line cap, automatic chaining via @path imports, and Karpathy behavioural guardrails. Works in any Claude Code or Claude.cowork project.

Five components ship in this repo:

1. Skill (claudeforge-skill, in skill/) — Python modules for analysis, generation, validation. Enforces the 150-line cap.
2. Slash command (/enhance-claude-md, in command/) — interactive init/enhance workflow. Delegates deep codebase scans to the Explore subagent.
3. Slash command (/sync-claude-md, in command/) — walks every CLAUDE.md, prunes stale references, enforces the 150-line cap, repairs the root ↔ sub chain.
4. Guardian agent (claude-md-guardian, in agent/) — background sync triggered by SessionStart / PreToolUse / PostToolUse hooks.
5. Karpathy guidelines skill (karpathy-guidelines, in skill/karpathy-guidelines/) — behavioural guardrails embedded into every generated CLAUDE.md. Adapted with attribution from the MIT-licensed forrestchang/andrej-karpathy-skills repo.

Current version: 2.1.0 — see CHANGELOG.md. v1 → v2 upgrade: docs/MIGRATION_V2.md.

Quick Navigation

• Skill development
• Slash command development
• Guardian agent development
• Installation, testing & release

Chained context (Claude Code auto-imports these):

@skill/CLAUDE.md @command/CLAUDE.md @agent/CLAUDE.md @docs/CLAUDE.md

Behavioral Guidelines

Behavioural guardrails applied to every coding, review, and refactoring task in this repo. Full skill: ~/.claude/skills/karpathy-guidelines/SKILL.md.

1. Think before coding. State load-bearing assumptions; if a request has multiple reasonable interpretations, surface them instead of picking silently. Stop and ask when something is genuinely unclear.
2. Simplicity first. Write the minimum code that solves the stated problem. No speculative abstractions, no unrequested configuration, no error handling for conditions that cannot occur.
3. Surgical changes. Touch only what the task requires. Match surrounding style. Every changed line should trace directly to the user's request.
4. Goal-driven execution. Convert vague requests into verifiable success criteria before coding (failing test first), and state a step-by-step plan with per-step verification for multi-step work.

Repository Layout (top level)

ClaudeForge/
├── .claude-plugin/plugin.json    # plugin manifest
├── skill/                        # core Python modules + karpathy-guidelines/
├── command/                      # /enhance-claude-md, /sync-claude-md
├── agent/                        # claude-md-guardian
├── docs/                         # operational docs (installation, testing, release)
├── examples/                     # usage examples
├── hooks/                        # quality hooks (pre-commit)
├── .github/                      # CI workflows, issue/PR templates
├── install.sh / install.ps1      # installers
├── README.md / CHANGELOG.md / LICENSE
└── CLAUDE.md                     # this file

Naming Reference

• Project / display name: ClaudeForge
• GitHub: https://github.com/alirezarezvani/ClaudeForge
• Skill name (frontmatter): claude-md-enhancer (kept for backwards compatibility); installed as claudeforge-skill/
• Slash commands: /enhance-claude-md, /sync-claude-md (names fixed by file name)
• Agent: claude-md-guardian
• Standalone skill: karpathy-guidelines

License

MIT — © 2025 Alireza Rezvani. See LICENSE.