DEV Community

shohei-ai-lab
shohei-ai-lab

Posted on

5 CLAUDE.md Mistakes That Make Claude Code Ignore Your Rules (and How to Fix Them)

#ai #productivity #programming #claudecode

You wrote a CLAUDE.md. You dropped it in your project root. But Claude Code still uses any, still picks Express when you wanted Next.js, and still ignores your naming conventions.

Sound familiar? You're not alone.

In our previous article, we covered 5 rules for designing system prompts. Today we zoom in on a specific file — CLAUDE.md — and the mistakes that make it ineffective.

After setting up CLAUDE.md configurations across multiple projects in our AI Autonomous Revenue Project, we identified 5 common failure patterns that explain why your CLAUDE.md "doesn't work" — and how to fix each one.

Mistake 1: Writing Aspirations Instead of Instructions

The Problem 

# Philosophy
- Clean code is important
- We value readability over cleverness
- Tests should be comprehensive
Enter fullscreen mode Exit fullscreen mode

This reads like a team manifesto, not an instruction set. "Clean code is important" gives Claude Code zero actionable information. What counts as clean? How do you measure it?

Human teammates can infer meaning from cultural context. AI cannot. It interprets text literally.

The Fix 

# Coding Rules
- Functions must be under 30 lines. Extract into smaller functions if longer
- Variable names: camelCase, minimum 3 characters (single-letter only for loop counters)
- Every public function needs JSDoc with @param and @returns
- No nested ternary operators — use if/else or early return
Enter fullscreen mode Exit fullscreen mode

Principle: Write rules that can be evaluated as pass/fail. If you can't check whether it was followed, Claude Code can't follow it either.

Mistake 2: Too Much Content (Important Rules Get Buried)

The Problem

Your CLAUDE.md is 200+ lines covering everything: stack details, all commands, every directory explained, 80 coding rules, Git workflow, deploy instructions...

When everything is important, nothing is important. Long configuration files dilute the weight of critical rules.

The Fix 

# CRITICAL (always follow these)
- TypeScript strict mode. No `any` type ever
- Server Components by default. "use client" only with explicit directive
- All DB access through src/lib/db/ (never direct Prisma calls in components)

# Stack
- Next.js 14+ (App Router), TypeScript, Tailwind CSS, Prisma

# Commands
- Dev: `pnpm dev` | Build: `pnpm build` | Test: `pnpm test`

# Conventions (see docs/ for full details)
- Named exports only (except page.tsx/layout.tsx)
- Zod schemas in src/schemas/, validated at API boundary
Enter fullscreen mode Exit fullscreen mode

Principle: Use a 3-layer structure:

  1. CRITICAL (3–5 rules at the top — these are non-negotiable)
  2. Reference info (Stack, Commands — things Claude needs to know)
  3. Details elsewhere (link to docs/ for comprehensive conventions)

Mistake 3: Listing Tech You Don't Actually Use

The Problem 

# Stack
- Next.js 14 with App Router
- NextAuth.js v5 for authentication    ← not installed yet
- Prisma + PostgreSQL                   ← actually using Drizzle + SQLite
- Redis for caching                     ← planned but not implemented
Enter fullscreen mode Exit fullscreen mode

Claude Code treats CLAUDE.md as ground truth. If you list libraries that don't exist in your project:

  • It imports modules that aren't installed
  • It writes code against APIs that aren't available
  • It generates structures that contradict your actual setup

This usually happens when you copy a template and forget to customize it.

The Fix 

# Stack (ACTUALLY INSTALLED — verify against package.json)
- Next.js 14 with App Router
- Drizzle ORM + SQLite (src/lib/db/schema.ts)
- Tailwind CSS + shadcn/ui

# NOT AVAILABLE (do not use or suggest these)
- No auth library yet (login handled by basic middleware)
- No caching layer (all queries hit DB directly)
- No state management library (use React state + URL params)
Enter fullscreen mode Exit fullscreen mode

Principle: Only list what's actually installed. Explicitly state what's NOT available — this prevents Claude from suggesting it.

Mistake 4: Constraints Without Alternatives

The Problem 

# Rules
- Do NOT use any type
- Do NOT add new dependencies
- Do NOT use class components
- Do NOT modify .env files
- Do NOT use default exports
- Do NOT write inline styles
Enter fullscreen mode Exit fullscreen mode

A list of "don'ts" tells Claude what to avoid, but not what to use instead. If any is banned, should it use unknown with type guards? Generics? Explicit type definitions?

The Fix 

# Type Safety
- Never use `any`. Instead:
  - External API responses → define with Zod schema, use `z.infer<typeof schema>`
  - Unknown runtime values → `unknown` with type guard functions in src/lib/guards/
  - Generic containers → TypeScript generics with constraints

# Styling
- No inline styles. Instead:
  - Standard styling → Tailwind utility classes
  - Conditional styles → `clsx()` or `cn()` from src/lib/utils
  - Animations → Tailwind's built-in animation utilities

# Dependencies
- No new deps without justification. Use what's already available:
  - Date handling → native Date (no moment/dayjs)
  - HTTP → native fetch (no axios)
  - Validation → existing Zod setup in src/schemas/
Enter fullscreen mode Exit fullscreen mode

Principle: Pair every "don't" with a "do instead". This eliminates ambiguity and gives Claude a clear path forward.

Mistake 5: Writing It Once and Never Updating

The Problem

Your CLAUDE.md was written 3 months ago when the project started. Since then:

  • Package manager changed from npm → pnpm
  • Test framework switched from Jest → Vitest
  • Directory structure was reorganized

Claude Code now runs npm test (fails), writes Jest syntax (wrong), and creates files in directories that no longer exist.

The Fix

Add an update trigger section:

# Meta
Last updated: 2026-08-01
Update this file when:
- [ ] package.json dependencies change
- [ ] Directory structure changes
- [ ] New coding conventions are adopted
- [ ] CI/CD pipeline changes
- [ ] Test framework or build tools change
Enter fullscreen mode Exit fullscreen mode

Principle: CLAUDE.md is a living document. Review it monthly or whenever your project setup changes. Outdated instructions are worse than no instructions.

Quick Checklist: Does Your CLAUDE.md Actually Work?

  • [ ] Rules are concrete and pass/fail testable (not aspirational)
  • [ ] CRITICAL section exists with ≤5 rules at the top of the file
  • [ ] Every tech in Stack section is actually installed (check package.json)
  • [ ] Every "don't" has a corresponding "do instead"
  • [ ] File was reviewed within the last 30 days
  • [ ] Total length is under 100 lines (details are in separate docs)

Resources

If you want to skip the trial-and-error of writing CLAUDE.md from scratch:

🎁 Claude Code Config Starter Pack (FREE) — 3 templates (Next.js, TypeScript Library, Python FastAPI) that follow all the principles above.

🛠️ Claude Code Config Pack — 20 Templates ($5) — Docker-verified configurations for 20 project types including Go, Rust, Flutter, Terraform, and more.

📘 The AI Coding Prompt Toolkit ($5) — 52 structured prompts for project setup, feature implementation, testing, and refactoring.

What CLAUDE.md mistakes have you encountered? Drop a comment below — I'd love to hear about patterns I missed.

Top comments (0)