How to Debug When Claude Code Doesn't Follow Behavioral Guidelines

When Claude Code ignores the Karpathy-inspired behavioral guidelines, the issue is almost always a configuration problem—not a code bug—and can be fixed by verifying plugin installation, file presence in CLAUDE.md, and cache freshness.

The andrej-karpathy-skills repository provides a minimal, text-based knowledge base that injects four "Karpathy" principles into Claude Code and Cursor. Because the repository contains no executable code—only instruction files—debugging behavioral non-compliance requires checking that the plugin system can locate and read the canonical guidelines.

Understanding the Repository Structure

The repository distributes the same behavioral guidelines across multiple files to support different integration methods. Knowing which file your editor reads is the first step to debugging.

Component	Purpose	Location
CLAUDE.md	The master instruction file that Claude Code reads directly; defines the four principles.	/CLAUDE.md
Skill manifest	Tells Claude Code how to fetch the guidelines as a plugin.	.claude-plugin/plugin.json
Cursor rule	Cursor-specific format with alwaysApply: true for automatic enforcement.	.cursor/rules/karpathy-guidelines.mdc
Skill definition	Reusable skill for other projects importing the guidelines.	skills/karpathy-guidelines/SKILL.md

Debugging Checklist for Claude Code Behavioral Guidelines

When Claude Code generates code without stating assumptions or asking clarifying questions (violating the "Think Before Coding" principle), work through this checklist.

1. Confirm the Plugin Is Installed

Run the plugin list command to verify the skill is active.

/plugin list

Look for andrej-karpathy-skills in the output. If missing, install it according to README.md:

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

2. Verify the Correct Version Is Loaded

The plugin pulls raw text from CLAUDE.md. Stale caches or outdated local copies cause mismatches.

In the Claude Code UI, navigate to Plugins → andrej-karpathy-skills → View source and confirm the displayed text matches the repository version. If it diverges, force a fresh fetch:

/plugin reinstall andrej-karpathy-skills@karpathy-skills

3. Check the Cursor Rule (If Using Cursor)

For Cursor users, the rule file must exist and contain alwaysApply: true. Open .cursor/rules/karpathy-guidelines.mdc and verify the flag appears near the top. If the file is missing or the flag is absent, copy the updated CLAUDE.md content into .cursor/rules/ as described in CURSOR.md.

4. Ensure CLAUDE.md Is in the Project Root (Per-Project Use)

When using the "plain file" method without the plugin, CLAUDE.md must reside at the repository root. Verify presence with:

ls -1 CLAUDE.md

If the file is nested in a subdirectory or named differently, Claude Code will not detect it.

5. Inspect Claude Code's Response for System-Prompt Leakage

Claude Code prepends the guideline text to every request. If the response does not contain phrases like "Think Before Coding" or "Goal-Driven Execution," the prompt was not injected.

Trigger a minimal test prompt:

User: "Add a function to compute the average of a list."

Expected behavior includes a preamble with guideline headings before the code solution. If this block is missing, return to step 2 and clear the plugin cache.

6. Review Plugin Logs

Claude Code logs plugin load events. Search logs for karpathy-guidelines to identify network or permission failures:

grep "karpathy" ~/.claude/code/logs/*.log

Look for entries like:

[INFO] Loaded plugin karpathy-guidelines version 1.2.0 from https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md

Errors indicate the plugin cannot reach the raw file URL, often due to corporate proxies or stale authentication tokens.

7. Synchronize All Source Files

The repository maintains identical text across CLAUDE.md, the skill manifest, and .cursor/rules/. Editing one without updating the others creates version drift.

After any modification, sync files using:

# Update the rule used by Cursor

cp CLAUDE.md .cursor/rules/karpathy-guidelines.mdc

# Update the skill definition

cp CLAUDE.md skills/karpathy-guidelines/SKILL.md

Code Examples for Verification

Use these commands to test whether the guidelines are active.

Reinstall the plugin to clear cache:

/plugin reinstall andrej-karpathy-skills@karpathy-skills

Minimal debug prompt that should trigger clarification questions:

User: "Export user data."

Under active guidelines, Claude should respond with clarification questions (Scope? Format? Fields? Volume?) before generating code. If it jumps straight to implementation, the guidelines are not loaded.

Check file presence:

# For Claude Code plugin method

ls -1 .claude-plugin/plugin.json

# For per-project file method

ls -1 CLAUDE.md

# For Cursor integration

ls -1 .cursor/rules/karpathy-guidelines.mdc

Key Files Reference

File	Purpose	Repository Path
CLAUDE.md	Canonical instruction set defining the four Karpathy principles	/CLAUDE.md
.claude-plugin/plugin.json	Plugin manifest for Claude Code marketplace integration	/.claude-plugin/plugin.json
.cursor/rules/karpathy-guidelines.mdc	Cursor rule with alwaysApply: true for automatic enforcement	/.cursor/rules/karpathy-guidelines.mdc
skills/karpathy-guidelines/SKILL.md	Reusable skill definition for cross-project imports	/skills/karpathy-guidelines/SKILL.md
README.md	Installation and usage instructions for both editors	/README.md
CURSOR.md	Cursor-specific troubleshooting and file sync procedures	/CURSOR.md

Summary

• Configuration, not code: The andrej-karpathy-skills repository contains only text instructions; debugging focuses on file presence and plugin state, not logic errors.
• Verify CLAUDE.md location: For plugin use, confirm installation via /plugin list; for per-project use, ensure CLAUDE.md sits at the repository root.
• Check for prompt injection: If responses lack the "Think Before Coding" preamble, the guidelines are not being prepended; reinstall the plugin to clear stale caches.
• Synchronize cross-editor files: When modifying guidelines, update .cursor/rules/karpathy-guidelines.mdc and skills/karpathy-guidelines/SKILL.md to prevent version drift.

Frequently Asked Questions

Why does Claude Code ignore the guidelines after I updated the repository?

Claude Code caches the plugin content locally. After updating files in the repository, run /plugin reinstall andrej-karpathy-skills@karpathy-skills to force a fresh fetch of CLAUDE.md. Without this step, Claude continues using the cached version from the previous session.

How do I know if the Karpathy guidelines are actually active?

Submit a vague request like "Export user data." If the guidelines are active, Claude will prepend a "Think Before Coding" block to its response and ask clarification questions (Scope? Format? Fields?) before writing code. If Claude immediately outputs code without the preamble, the guidelines are not loaded.

Can I use these guidelines in Cursor instead of Claude Code?

Yes. The repository includes .cursor/rules/karpathy-guidelines.mdc with alwaysApply: true. Copy this file to your project's .cursor/rules/ directory, or place it in your Cursor user settings to apply the rules globally. The content mirrors CLAUDE.md exactly, ensuring consistent behavior across editors.

What should I do if the plugin fails to load entirely?

Check the Claude Code console logs for entries containing karpathy-guidelines. Errors such as "failed to download CLAUDE.md" indicate network restrictions, proxy issues, or authentication token expiration. Resolve connectivity issues, then reinstall the plugin. If problems persist, use the per-project method by placing CLAUDE.md at your repository root instead of relying on the plugin marketplace.

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