How to Combine Project-Specific Rules with Default Karpathy Guidelines

You merge project-specific rules with the default Karpathy guidelines by appending a custom markdown section to the CLAUDE.md file after the four core principles, creating a single document that Claude reads automatically.

The forrestchang/andrej-karpathy-skills repository provides a foundation for LLM-assisted development based on Andrej Karpathy's observed best practices. To adapt these universal guidelines to your specific codebase, you combine the base CLAUDE.md with custom project rules rather than modifying the core principles directly. This layered approach preserves the original safety nets while injecting domain-specific requirements into Claude's context window.

Core Files for Guideline Integration

The repository structures its guidance across two primary locations that explicitly support merging:

• skills/karpathy-guidelines/SKILL.md – Contains the canonical skill definition used by the Claude Code plugin. This file defines the four pillars and serves as the upstream source.
• CLAUDE.md – A ready-to-drop markdown file designed for immediate use in your project root. According to the repository's README.md (lines 141-151), this file is specifically intended to be extended with project-specific instructions.

Both files state that the four pillars—Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution—form the base layer, while explicitly leaving room for additional constraints unique to your repository.

The Recommended Merge Workflow

Follow this five-step pattern to combine default Karpathy guidelines with your custom rules:

1. Install the Base Guidelines

Copy the canonical CLAUDE.md into your project root or install via the Claude Code plugin:

# Option A: Direct download

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

# Option B: Plugin installation within Claude Code

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

2. Append Project-Specific Rules

Add a distinct section at the end of CLAUDE.md that follows the same markdown style. Place this after the four Karpathy principles to ensure the base philosophy remains foundational:

cat <<'EOF' >> CLAUDE.md

## Project-Specific Guidelines

- Enforce TypeScript `strict` mode (`"strict": true` in tsconfig.json)
- Every public API endpoint must have a unit test (`src/tests/**/*.test.ts`)
- Follow the error handling pattern defined in `src/utils/errors.ts`
- Require approval before modifying database schemas
EOF

3. Maintain Structural Order

Keep the project-specific block at the bottom of the file. This ordering ensures that Claude processes the universal guidelines (thinking before coding, simplicity) before applying your custom constraints (TypeScript strictness, specific file patterns).

4. Document the Combination

Update your project README.md to acknowledge that your CLAUDE.md represents a merged configuration:

This project uses a modified version of the Andrej Karpathy guidelines. 
See `CLAUDE.md` for the combined set of base principles and project-specific rules.

5. Enforce via Tooling (Optional)

Configure CI pipelines to validate that changes adhere to both the base and custom guidelines:

# Example GitHub Actions step

- name: Check Guidelines
  run: |
    if ! grep -q "Project-Specific Guidelines" CLAUDE.md; then
      echo "Missing project-specific rules section"
      exit 1
    fi

Why This Merging Strategy Works

This approach delivers three distinct advantages for AI-assisted development:

• Layered architecture – The default principles act as guardrails that prevent common LLM pitfalls (rushing to code, over-engineering), while your rules add necessary specificity without overriding the core philosophy.
• Single source of truth – The merged CLAUDE.md becomes the definitive instruction set that both human developers and Claude Code reference, eliminating context switching between multiple guideline documents.
• Future-proof maintenance – When the upstream forrestchang/andrej-karpathy-skills repository updates, you can replace the base section of CLAUDE.md without touching your custom appendix, preserving your project-specific investments.

Summary

• Copy CLAUDE.md from forrestchang/andrej-karpathy-skills to your project root to establish the four Karpathy pillars.

• Append a ## Project-Specific Guidelines section at the end of the file to inject custom rules without modifying the base principles.

• Install the repository as a Claude Code plugin (/plugin install andrej-karpathy-skills@karpathy-skills) for automatic skill application.

• Document the merge in your project README to clarify that guidelines are combined, not replaced.

• Optionally add CI checks to ensure the merged guidelines remain present and up-to-date.

Frequently Asked Questions

Where should I place my custom rules in the CLAUDE.md file?

Place your custom rules after the four Karpathy principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) and before any closing matter. The README.md in the source repository (lines 141-151) explicitly recommends appending project-specific sections to ensure the base guidelines retain priority in Claude's context processing.

Can I modify the original Karpathy guidelines instead of appending to them?

Avoid editing the core principles. The CLAUDE.md file and the canonical SKILL.md are designed to be extended rather than modified. Changing the base text breaks the mental model that "these are universal truths" and makes future updates from the upstream repository difficult to merge. Instead, add constraints or exceptions in your appended section.

How does the Claude Code plugin interact with my merged guidelines?

When you install the skill via /plugin install andrej-karpathy-skills@karpathy-skills, Claude loads the canonical definitions from skills/karpathy-guidelines/SKILL.md. However, if your project root contains a CLAUDE.md file with merged content, Claude automatically reads that file in addition to the plugin, effectively layering your project-specific rules on top of the default skill behavior.

Do I need to include all four pillars if I only care about specific ones?

Include all four pillars. The repository structure assumes the complete set forms a cohesive safety net. Removing pillars (like "Simplicity First") eliminates guardrails against common anti-patterns. If a principle doesn't apply to a specific task, Claude will naturally deviate based on your appended project-specific instructions, but the base principles should remain intact for general context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}