mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-03 02:13:15 -04:00
Alireza Rezvani
71 lines
3.9 KiB
Markdown
71 lines
3.9 KiB
Markdown
# 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](https://github.com/forrestchang/andrej-karpathy-skills) repo.
|
|
|
|
Current version: **2.1.0** — see `CHANGELOG.md`. v1 → v2 upgrade: `docs/MIGRATION_V2.md`.
|
|
|
|
## Quick Navigation
|
|
|
|
- [Skill development](skill/CLAUDE.md)
|
|
- [Slash command development](command/CLAUDE.md)
|
|
- [Guardian agent development](agent/CLAUDE.md)
|
|
- [Installation, testing & release](docs/CLAUDE.md)
|
|
|
|
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`.
|