DEV Community

albert nahas
albert nahas

Posted on • Originally published at github.com

Your CLAUDE.md Instructions Are Being Ignored - Here's Why (and How to Fix It)

#ai #devtools #productivity #opensource

If you use Claude Code, you've probably added development standards to your CLAUDE.md file. Something like "always fix root causes" or "no half solutions."

And you've probably noticed Claude ignoring them mid-session.

This isn't a bug in your instructions. It's a documented problem with how CLAUDE.md content gets injected.

The CLAUDE.md Disclaimer Problem

When Claude Code loads your CLAUDE.md, it wraps the content in a framing that tells Claude it "may or may not be relevant" and should only be followed "if highly relevant to your task."

This is documented across multiple GitHub issues:

  • #22309 — CLAUDE.md content wrapped in dismissive framing
  • #21119 — Claude treats explicit instructions as suggestions
  • #7777, #15443, #21385 — Various reports of Claude ignoring CLAUDE.md rules

The practical effect: as your conversation grows and Claude's context fills with code, tool output, and discussion, your carefully written standards get deprioritized. And when the context window fills up and gets compacted, your CLAUDE.md values get summarized away with everything else.

A Better Approach: Hook-Based Reinforcement

Claude Code hooks are event-driven scripts that fire at specific moments in the session lifecycle. Unlike CLAUDE.md content, hook output arrives as clean system-reminder messages — no disclaimer, no "may or may not be relevant" framing.

I built a plugin called Claude Core Values that uses a three-layer reinforcement strategy:

Layer Hook Event What It Does
Full injection SessionStart Injects all your values at session start — and re-injects them fresh after every compaction
Per-prompt reminder UserPromptSubmit Reinforces your motto on every single prompt
No disclaimer Both Hook output has no "may or may not be relevant" framing

The SessionStart hook fires on startup, resume, clear, and crucially compact — meaning your values are automatically restored every time context gets compressed.

The UserPromptSubmit hook adds a single-line motto reminder (~15 tokens) on every prompt. Over a 50-turn session, that's ~750 tokens — negligible against a 200k context window.

How It Works

Your values live in a simple YAML file:

# ~/.claude/core-values.yml
motto: "Excellence is not negotiable. Quality over speed."

sections:
  - name: Quality Commitment
    values:
      - "No Half Solutions: Always fix everything until it's 100% functional."
      - "No Corner Cutting: Do the real work until completion."
      - "No Band-Aid Solutions: Fix the root cause, not the symptom."
      - "Follow Through: Continue until completely done and verified."

  - name: Standards
    values:
      - "Follow best practices and highest industry standards."
      - "Build efficient, modular code with separation of concerns."
      - "Always consider performance, scalability, and maintainability."
Enter fullscreen mode Exit fullscreen mode

The plugin reads this file and injects it through two hooks defined in hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/inject-values.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/inject-reminder.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

At session start, Claude sees:

## Core Values & Development Standards

**Excellence is not negotiable. Quality over speed.**

### Quality Commitment
- **No Half Solutions**: Always fix everything until it's 100% functional.
- **No Corner Cutting**: Do the real work until completion.
...
Enter fullscreen mode Exit fullscreen mode

On every subsequent prompt, it sees:

Core values reminder: Excellence is not negotiable. Quality over speed.
Enter fullscreen mode Exit fullscreen mode

Both without the disclaimer. Both surviving compaction.

Installation

The plugin installs directly from GitHub — no cloning needed:

/plugin marketplace add albertnahas/claude-core-values
/plugin install claude-core-values@claude-core-values
Enter fullscreen mode Exit fullscreen mode

Then initialize with a starter template:

/core-values init
Enter fullscreen mode Exit fullscreen mode

You'll pick from four templates:

Template Philosophy
Craftsman Quality-obsessed. No half solutions. No shortcuts.
Startup Ship fast, iterate rapidly, pragmatic quality.
Security-First Defense in depth, zero trust, OWASP compliance.
Minimal Simple baseline: working code, follow patterns, test before push.

The config gets saved to ~/.claude/core-values.yml (global) or .claude/core-values.yml (per-project). Edit the YAML directly anytime — changes take effect on the next session.

Beyond CLAUDE.md

The plugin also solves practical management problems:

  • Team distribution: plugin install gives everyone identical standards instead of "copy these 30 lines into your CLAUDE.md."
  • Per-project overrides: Drop a different core-values.yml in any project's .claude/ directory without touching global config.
  • Structured config: YAML with typed sections is easier to diff and review than freeform markdown.
  • Starter templates: Pick a philosophy and go, instead of staring at a blank file.

The Takeaway

CLAUDE.md is great for project-specific context — file conventions, architecture notes, gotchas. But for development standards you want Claude to follow every time, in every session, no exceptions — hook-based injection is the more reliable path.

The plugin is open source and MIT licensed: github.com/albertnahas/claude-core-values

Requirements: Claude Code, Python 3 (ships with macOS/Linux). PyYAML is optional — the plugin includes a zero-dependency fallback parser.

Top comments (0)