feat(skill): integrate Karpathy behavioral guidelines into every CLAUDE.md (#25)

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 = []

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. <step> → verify: <how you will check>
+2. <step> → verify: <how you will check>
+3. <step> → verify: <how you will check>
+```
+
+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.

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 = []