mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-04 10:53:16 -04:00
Claude
e33fa8326b
Wave 3 - adoption hardening. Patterns adapted (in original prose, with
attribution) from MIT-licensed shanraisshan/claude-code-best-practice.
Commands (command/enhance-claude-md.md, command/sync-claude-md.md):
- Add allowed-tools / disallowedTools / argument-hint / when_to_use so the
commands auto-suggest in the slash menu and avoid permission prompts.
- disallowedTools blocks WebFetch + WebSearch on both commands.
- Drop the previous broken hooks block (array-of-{matcher, commands} shape
did not match canonical schema; was never firing).
Skills:
- skill/karpathy-guidelines/SKILL.md: paths: glob over 23 code-file
extensions, so the guardrails auto-load only when editing source, not
markdown or data.
- skill/SKILL.md: model: haiku, effort: medium, paths: scoped to CLAUDE.md
+ AGENTS.md + .claude/rules/*.md so validator/generator passes run
cheaply without changing the user-facing model.
CLAUDE.local.md personal tier:
- skill/validator.py BestPracticesValidator now accepts filename=; any
*.local.md basename waives the 150-line cap.
- hooks/validate-claude-md.py reads the exempt suffix from hooks-config.
- .gitignore covers CLAUDE.local.md, **/CLAUDE.local.md,
.claude/settings.local.json, hooks/hooks-config.local.json.
Layered hook config:
- hooks/hooks-config.json: committed defaults
(validateClaudeMd.enabled/maxLines/exemptFilenameSuffix/exitCodeOnViolation,
stopAuditLine.enabled).
- hooks/validate-claude-md.py merges hooks-config.json +
hooks-config.local.json key-by-key; honours enabled=false (silent
exit 0), configurable cap, configurable exit code.
Stop audit hook:
- hooks/audit-claude-md.py walks the project tree, prints one stderr
line: total tracked / OVER cap / near cap (>=80%). Respects
stopAuditLine.enabled from config.
- hooks/hooks.json registers Stop event with matcher "".
Guardian fail-closed contract:
- agent/claude-md-guardian.md Safety & Validation section now explicitly
requires Skill-tool invocation (no inline paraphrase of SKILL.md),
abort on missing validated output, never auto-commit, and respect
local hook config.
Verified (8/8 smoke tests):
- Both commands parse with new fields and no broken hooks block.
- karpathy paths: 23 globs, includes .py/.ts/.go/.rs.
- skill model=haiku effort=medium with CLAUDE.md path scope.
- Validator: *.local.md (300 lines) -> pass; CLAUDE.md (300) -> fail;
legacy ctor without filename -> default behavior preserved.
- hooks-config.json valid; validateClaudeMd.enabled=true, maxLines=150.
- Hook validator: default rc=2 on bloated, rc=0 when local override
disables it, rc=0 on *.local.md (exempt).
- Stop hook entry present; audit script: rc=0 with "5 CLAUDE.md tracked".
- Regression: large-fullstack root still 52 lines with chain imports.
130 lines
4.8 KiB
Markdown
130 lines
4.8 KiB
Markdown
---
|
|
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
|
|
paths:
|
|
- "**/*.py"
|
|
- "**/*.ts"
|
|
- "**/*.tsx"
|
|
- "**/*.js"
|
|
- "**/*.jsx"
|
|
- "**/*.go"
|
|
- "**/*.rs"
|
|
- "**/*.java"
|
|
- "**/*.kt"
|
|
- "**/*.rb"
|
|
- "**/*.php"
|
|
- "**/*.swift"
|
|
- "**/*.c"
|
|
- "**/*.cc"
|
|
- "**/*.cpp"
|
|
- "**/*.h"
|
|
- "**/*.hpp"
|
|
- "**/*.cs"
|
|
- "**/*.scala"
|
|
- "**/*.sh"
|
|
- "**/*.bash"
|
|
- "**/*.zsh"
|
|
- "**/*.sql"
|
|
allowed-tools:
|
|
- Read
|
|
- Glob
|
|
- Grep
|
|
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.
|