diff --git a/CHANGELOG.md b/CHANGELOG.md index 98e3cea..8b585e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **Karpathy Guidelines skill** (`skill/karpathy-guidelines/SKILL.md`): a behavioral-guardrail skill installed alongside ClaudeForge that applies to every coding, review, and refactoring task. Covers four principles — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository. +- **Automatic embedding into every CLAUDE.md**: `skill/template_selector.py` and `skill/generator.py` now insert a `## Behavioral Guidelines` section into every generated and enhanced CLAUDE.md, so the principles ship with every project that runs `/enhance-claude-md`. +- **Installer support for the new skill**: `install.sh` and `install.ps1` now copy the skill to `~/.claude/skills/karpathy-guidelines/` (or the project-level equivalent) and include it in the uninstall instructions. +- **Slash command documentation**: `command/enhance-claude-md.md` documents the always-on Behavioral Guidelines section as a required part of the workflow. + --- ## [2.0.0] - 2026-01-08 diff --git a/CLAUDE.md b/CLAUDE.md index 992575b..a838f88 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,11 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -**ClaudeForge** is a comprehensive toolkit for automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects. The repository consists of three integrated components: +**ClaudeForge** is a comprehensive toolkit for automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects. The repository consists of four integrated components: 1. **Skill** (`claudeforge-skill`) - Core Python modules for analysis, generation, and validation 2. **Slash Command** (`/enhance-claude-md`) - Interactive multi-phase discovery workflow 3. **Guardian Agent** (`claude-md-guardian`) - Background maintenance agent +4. **Karpathy Guidelines Skill** (`karpathy-guidelines`) - Behavioral guardrails embedded into every generated CLAUDE.md and installed as a standalone skill, adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository --- diff --git a/README.md b/README.md index 54b9b68..821247a 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,9 @@ Interactive interface with multi-phase discovery workflow ### 3. **Guardian Agent** (`claude-md-guardian`) Background agent for automatic CLAUDE.md maintenance and synchronization +### 4. **Karpathy Guidelines Skill** (`karpathy-guidelines`) +Behavioral guardrails — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — installed as a standalone skill and automatically embedded into every CLAUDE.md generated or enhanced by `/enhance-claude-md`. Adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository, inspired by Andrej Karpathy's observations on common LLM coding failure modes. + --- ## 🚀 Quick Start diff --git a/command/enhance-claude-md.md b/command/enhance-claude-md.md index 4193268..ce511fc 100644 --- a/command/enhance-claude-md.md +++ b/command/enhance-claude-md.md @@ -82,6 +82,14 @@ The skill provides: - 🔧 **Enhancement**: Adds missing sections and improves existing files - 📦 **Modular Architecture**: Supports context-specific files (backend/, frontend/, database/) +### Always-On: Karpathy Behavioral Guidelines + +Every generated or enhanced CLAUDE.md MUST include a `## Behavioral Guidelines` section summarising the four Karpathy principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) with a link to the installed `karpathy-guidelines` skill. + +The `claude-md-enhancer` skill inserts this section automatically — both in `template_selector.customize_template()` for new files and in `generator.merge_with_existing()` for enhanced files. Do not strip it during enhancement; if it is missing from an existing CLAUDE.md, treat that as a required addition. + +The full skill is installed at `~/.claude/skills/karpathy-guidelines/SKILL.md` (or `./.claude/skills/karpathy-guidelines/SKILL.md` for project-level installs). + ### Option B: Agent Invocation (Recommended for Maintenance) For ongoing maintenance and automatic updates throughout your project lifecycle, I can invoke the `claude-md-guardian` agent instead: diff --git a/install.ps1 b/install.ps1 index 80cbe2f..20f8a5d 100644 --- a/install.ps1 +++ b/install.ps1 @@ -177,6 +177,7 @@ while (-not $validChoice) { Write-Host "" Write-Info "Installation will create:" Write-Host " • Skill: $skillsDir\claudeforge-skill\" +Write-Host " • Skill: $skillsDir\karpathy-guidelines\" Write-Host " • Command: $commandsDir\enhance-claude-md\" Write-Host " • Agent: $agentsDir\claude-md-guardian.md" Write-Host "" @@ -211,6 +212,25 @@ if (Test-Path $skillPath) { Copy-Item -Path "skill" -Destination $skillPath -Recurse -Force Write-Success "Skill installed → $skillPath\" +# Install karpathy-guidelines as a separate top-level skill so it is +# discoverable as its own skill and applies to every project (not only +# during /enhance-claude-md runs). +Write-Info "Installing karpathy-guidelines skill..." +$karpathyPath = "$skillsDir\karpathy-guidelines" +if (Test-Path $karpathyPath) { + Write-Warning "Existing karpathy-guidelines skill found. Creating backup..." + $backupName = "karpathy-guidelines.backup.$(Get-Date -Format 'yyyyMMdd_HHmmss')" + Move-Item -Path $karpathyPath -Destination "$skillsDir\$backupName" -Force + Write-Success "Backup created" +} +Copy-Item -Path "skill\karpathy-guidelines" -Destination $karpathyPath -Recurse -Force +# Remove the nested duplicate inside claudeforge-skill so the skill exists once. +$nestedKarpathy = "$skillPath\karpathy-guidelines" +if (Test-Path $nestedKarpathy) { + Remove-Item -Path $nestedKarpathy -Recurse -Force +} +Write-Success "Karpathy guidelines installed → $karpathyPath\" + # Install slash command Write-Info "Installing /enhance-claude-md command..." $commandPath = "$commandsDir\enhance-claude-md" @@ -342,10 +362,12 @@ Write-Info "To uninstall, run:" Write-Host "" if ($scope -eq "user-level") { Write-Host " Remove-Item -Recurse -Force ~\.claude\skills\claudeforge-skill" + Write-Host " Remove-Item -Recurse -Force ~\.claude\skills\karpathy-guidelines" Write-Host " Remove-Item -Recurse -Force ~\.claude\commands\enhance-claude-md" Write-Host " Remove-Item -Force ~\.claude\agents\claude-md-guardian.md" } else { Write-Host " Remove-Item -Recurse -Force .\.claude\skills\claudeforge-skill" + Write-Host " Remove-Item -Recurse -Force .\.claude\skills\karpathy-guidelines" Write-Host " Remove-Item -Recurse -Force .\.claude\commands\enhance-claude-md" Write-Host " Remove-Item -Force .\.claude\agents\claude-md-guardian.md" } diff --git a/install.sh b/install.sh index 26b8e18..16e5fa9 100755 --- a/install.sh +++ b/install.sh @@ -158,6 +158,7 @@ done echo "" print_info "Installation will create:" echo " • Skill: $SKILLS_DIR/claudeforge-skill/" +echo " • Skill: $SKILLS_DIR/karpathy-guidelines/" echo " • Command: $COMMANDS_DIR/enhance-claude-md/" echo " • Agent: $AGENTS_DIR/claude-md-guardian.md" echo "" @@ -188,6 +189,20 @@ fi cp -r skill "$SKILLS_DIR/claudeforge-skill" print_success "Skill installed → $SKILLS_DIR/claudeforge-skill/" +# Install karpathy-guidelines as a separate top-level skill so it is +# discoverable as its own skill (and applies to every project, not only +# during /enhance-claude-md runs). +print_info "Installing karpathy-guidelines skill..." +if [ -d "$SKILLS_DIR/karpathy-guidelines" ]; then + print_warning "Existing karpathy-guidelines skill found. Creating backup..." + mv "$SKILLS_DIR/karpathy-guidelines" "$SKILLS_DIR/karpathy-guidelines.backup.$(date +%Y%m%d_%H%M%S)" + print_success "Backup created" +fi +cp -r skill/karpathy-guidelines "$SKILLS_DIR/karpathy-guidelines" +# Remove the nested duplicate so the karpathy skill exists once. +rm -rf "$SKILLS_DIR/claudeforge-skill/karpathy-guidelines" +print_success "Karpathy guidelines installed → $SKILLS_DIR/karpathy-guidelines/" + # Install slash command print_info "Installing /enhance-claude-md command..." if [ -d "$COMMANDS_DIR/enhance-claude-md" ]; then @@ -303,10 +318,12 @@ print_info "To uninstall, run:" echo "" if [ "$SCOPE" == "user-level" ]; then echo " rm -rf ~/.claude/skills/claudeforge-skill" + echo " rm -rf ~/.claude/skills/karpathy-guidelines" echo " rm -rf ~/.claude/commands/enhance-claude-md" echo " rm -f ~/.claude/agents/claude-md-guardian.md" else echo " rm -rf ./.claude/skills/claudeforge-skill" + echo " rm -rf ./.claude/skills/karpathy-guidelines" echo " rm -rf ./.claude/commands/enhance-claude-md" echo " rm -f ./.claude/agents/claude-md-guardian.md" fi diff --git a/skill/generator.py b/skill/generator.py index ffb9c4b..ecb7a10 100644 --- a/skill/generator.py +++ b/skill/generator.py @@ -61,6 +61,12 @@ class ContentGenerator: lines.extend(principles) lines.append("") + # Behavioral Guidelines (Karpathy principles - applied to every project) + lines.append("## Behavioral Guidelines") + lines.append("") + lines.extend(self._generate_karpathy_guidelines()) + lines.append("") + # Tech Stack (summary only) if self.project_context.get('tech_stack'): lines.append("## Tech Stack") @@ -388,6 +394,13 @@ class ContentGenerator: lines.append("") lines.append(new_section) + # Always ensure the Karpathy behavioral guidelines section is present + if "Behavioral Guidelines" not in existing_sections: + lines.append("") + lines.append("## Behavioral Guidelines") + lines.append("") + lines.extend(self._generate_karpathy_guidelines()) + return '\n'.join(lines) def _extract_existing_sections(self, content: str) -> List[str]: @@ -448,6 +461,33 @@ class ContentGenerator: return principles + def _generate_karpathy_guidelines(self) -> List[str]: + """Emit the embedded Karpathy guidelines section. + + Distilled summary applied to every generated CLAUDE.md. The full skill + text lives in the ``karpathy-guidelines`` skill installed alongside + ClaudeForge. + """ + return [ + "Behavioral guardrails applied to every coding, review, and refactoring task.", + "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. If the first draft is " + "much larger than necessary, rewrite before shipping.", + "3. **Surgical changes.** Touch only what the task requires. Do not " + "opportunistically reformat or refactor adjacent code, and match the " + "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 (e.g. failing test first), and state a " + "step-by-step plan with per-step verification for multi-step work.", + ] + def _generate_tech_stack_summary(self) -> List[str]: """Generate tech stack summary.""" lines = [] diff --git a/skill/karpathy-guidelines/SKILL.md b/skill/karpathy-guidelines/SKILL.md new file mode 100644 index 0000000..7dc434b --- /dev/null +++ b/skill/karpathy-guidelines/SKILL.md @@ -0,0 +1,101 @@ +--- +name: karpathy-guidelines +description: Behavioral guardrails for LLM-assisted coding. Use when writing, reviewing, or refactoring code in any project to avoid overcomplication, keep changes surgical, surface assumptions early, and execute against verifiable success criteria. +license: MIT +permissions: + allow: + - Read + - Glob + - Grep +--- + +# Karpathy Guidelines for LLM Coding + +Behavioral guardrails for code generation in Claude Code projects, distilled from observations on common LLM coding failure modes. Apply these to every editing, reviewing, and refactoring task. + +> Attribution: adapted from the MIT-licensed `karpathy-guidelines` skill by Forrest Chang +> (https://github.com/forrestchang/andrej-karpathy-skills), inspired by Andrej Karpathy's +> commentary on where LLM-generated code typically goes wrong. +> ClaudeForge integrates these principles so every project initialised or enhanced through +> `/enhance-claude-md` ships with them in its CLAUDE.md. + +--- + +## When to Apply + +Apply on every non-trivial task: writing new code, editing existing code, code review, refactoring, and bug fixing. They are intentionally conservative — bias toward caution over speed. + +--- + +## 1. Think Before Coding + +Surface what is uncertain. Do not paper over confusion with plausible-sounding code. + +- State assumptions before implementing; if any are load-bearing and you are not sure, ask. +- If the request admits more than one reasonable interpretation, list them rather than silently picking one. +- If a simpler approach exists than the one the user proposed, say so and explain the tradeoff. +- When something is genuinely unclear, stop. Identify what is unclear in concrete terms, then ask. + +--- + +## 2. Simplicity First + +Write the minimum code that solves the stated problem. Nothing speculative. + +- Do not add features that were not requested. +- Do not introduce abstractions when there is only one call site. +- Do not add configuration knobs or extension points on speculation. +- Do not add error handling for conditions that cannot occur in this code path. +- If the first draft is 200 lines and a 50-line version would do, rewrite it before shipping. + +Self-check: a senior engineer skimming this diff — would they say it is overcomplicated for what was asked? If yes, simplify. + +--- + +## 3. Surgical Changes + +Touch only what the task requires. Do not opportunistically refactor. + +- Do not "improve" adjacent code, comments, or formatting that the task did not require touching. +- Do not refactor code that is working, even when you would have written it differently. +- Match the surrounding code's style and conventions, even when they differ from your defaults. +- If you notice unrelated dead code or bugs, surface them in the response — do not silently delete or fix them. + +When your own changes leave orphans: + +- Remove imports, variables, and helpers that your edits made unreachable. +- Do not remove pre-existing dead code unless explicitly asked. + +Diff test: every changed line should be traceable to the user's request. If a line is not, drop it. + +--- + +## 4. Goal-Driven Execution + +Turn the task into a verifiable goal, then iterate until the verification passes. + +- Convert vague requests into checkable success criteria before coding: + - "Add validation" → write the failing tests for invalid inputs first, then make them pass. + - "Fix the bug" → write a test that reproduces the bug, then make it pass. + - "Refactor X" → confirm the existing tests pass, refactor, confirm they still pass. +- For multi-step tasks, state the plan inline with verification per step: + +``` +1. → verify: +2. → verify: +3. → verify: +``` + +Strong success criteria let you loop without supervision. Vague ones ("make it work") force the user back into the loop. + +--- + +## Integration with ClaudeForge + +- The slash command `/enhance-claude-md` injects a `## Behavioral Guidelines` section into every generated or enhanced `CLAUDE.md`, summarising these four principles with a link back to this skill. +- The `claude-md-guardian` agent preserves the section across automated maintenance updates. +- `skill/generator.py` and `skill/template_selector.py` insert the section unconditionally — these principles are not opt-in. + +## Effectiveness Indicators + +The guidelines are working when diffs trend smaller, rewrites caused by overcomplication drop, and clarifying questions arrive before implementation rather than after a failed attempt. diff --git a/skill/template_selector.py b/skill/template_selector.py index 02ed66b..763e94f 100644 --- a/skill/template_selector.py +++ b/skill/template_selector.py @@ -352,6 +352,12 @@ class TemplateSelector: lines.extend(self._generate_core_principles(template)) lines.append("") + # Add behavioral guidelines (Karpathy principles) - applied to every project + lines.append("## Behavioral Guidelines") + lines.append("") + lines.extend(self._generate_karpathy_guidelines()) + lines.append("") + # Add tech stack section if self.tech_stack: lines.append("## Tech Stack") @@ -437,6 +443,33 @@ class TemplateSelector: return lines + def _generate_karpathy_guidelines(self) -> List[str]: + """Emit the embedded Karpathy guidelines section. + + Distilled summary intended for every generated CLAUDE.md. Full skill + text lives in the ``karpathy-guidelines`` skill installed alongside + ClaudeForge. + """ + return [ + "Behavioral guardrails applied to every coding, review, and refactoring task.", + "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. If the first draft is " + "much larger than necessary, rewrite before shipping.", + "3. **Surgical changes.** Touch only what the task requires. Do not " + "opportunistically reformat or refactor adjacent code, and match the " + "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 (e.g. failing test first), and state a " + "step-by-step plan with per-step verification for multi-step work.", + ] + def _generate_workflow_section(self) -> List[str]: """Generate workflow section based on specified workflows.""" lines = []