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

> Debug Claude Code ignoring guidelines by checking configuration, plugin installation, CLAUDE.md file presence, and cache freshness for quick fixes, not code bugs.

- Repository: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills)
- Tags: how-to-guide
- Published: 2026-04-19

---

**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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md)** | The master instruction file that Claude Code reads directly; defines the four principles. | [`/CLAUDE.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main//CLAUDE.md) |
| **Skill manifest** | Tells Claude Code how to fetch the guidelines as a plugin. | [`.claude-plugin/plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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.

```text
/plugin list

```

Look for `andrej-karpathy-skills` in the output. If missing, install it according to [`README.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/README.md):

```text
/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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:

```text
/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md) content into `.cursor/rules/` as described in [`CURSOR.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md) must reside at the repository root. Verify presence with:

```bash
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:

```text
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:

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

```

Look for entries like:

```text
[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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md), the skill manifest, and `.cursor/rules/`. Editing one without updating the others creates version drift.

After any modification, sync files using:

```bash

# 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:**

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

```

**Minimal debug prompt that should trigger clarification questions:**

```text
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:**

```bash

# 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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md) | Canonical instruction set defining the four Karpathy principles | [/CLAUDE.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md) |
| [`.claude-plugin/plugin.json`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json) | Plugin manifest for Claude Code marketplace integration | [/.claude-plugin/plugin.json](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json) |
| `.cursor/rules/karpathy-guidelines.mdc` | Cursor rule with `alwaysApply: true` for automatic enforcement | [/.cursor/rules/karpathy-guidelines.mdc](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/.cursor/rules/karpathy-guidelines.mdc) |
| [`skills/karpathy-guidelines/SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) | Reusable skill definition for cross-project imports | [/skills/karpathy-guidelines/SKILL.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) |
| [`README.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/README.md) | Installation and usage instructions for both editors | [/README.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/README.md) |
| [`CURSOR.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CURSOR.md) | Cursor-specific troubleshooting and file sync procedures | [/CURSOR.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md) location**: For plugin use, confirm installation via `/plugin list`; for per-project use, ensure [`CLAUDE.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/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`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md) at your repository root instead of relying on the plugin marketplace.