DEV Community: shohei-ai-lab

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

shohei-ai-lab — Tue, 04 Aug 2026 20:34:08 +0000

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

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

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

Principle: Use a 3-layer structure:

CRITICAL (3–5 rules at the top — these are non-negotiable)
Reference info (Stack, Commands — things Claude needs to know)
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

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)

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

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/

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

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.

5 Essential System Prompt Rules to Stop Your AI Agents from Going Rogue

shohei-ai-lab — Tue, 04 Aug 2026 00:01:40 +0000

We are in the era of autonomous AI agents. Tools like Claude Code, Cline, Cursor, and other agentic coding frameworks are replacing simple Q&A chat interfaces. They can read your workspace, run shell commands, write code, and execute tests.

However, with great power comes great chaos. Every developer using AI agents eventually faces these frustrating moments:

The Loop of Doom: Your agent gets stuck in a compilation-error loop, burning your API credits.
The Overzealous Refactor: The agent rewrites unrelated files, breaking your main branch.
The Hallucination: The agent claims "all tests passed" when they didn't even run.

These issues are not failures of the AI models themselves—they are system prompt failures. Just like human developers, AI agents need clear boundaries, explicit constraints, and rigorous execution rules to perform at their best.

Based on our ongoing experiment, AI Autonomous Revenue Project (where we build and iterate on web products using AI agent workflows with structural verification), we compiled 5 core rules for designing system prompts for AI agents.

Rule 1: Tighten the Role and Grant Specific Authority

Instead of a generic role like "You are a world-class software engineer," define a highly specialized domain expert with distinct behavioral boundaries.

Weak: "You are a senior full-stack developer."
Strong: "You are a strict, no-nonsense senior backend engineer specializing in Next.js, Prisma, and PostgreSQL. Your coding style is minimal, avoiding any unnecessary helper libraries or duplicate imports."

Rule 2: Explicitly Restrict File System Mutability

AI agents have powerful file-writing tools. If left unrestricted, they will modify configuration files, GitHub actions, or package dependencies in unexpected ways. You must establish write-protected zones.

### Write-Protected Files (Read-Only)
- `package.json` and `package-lock.json` (Any dependency update requires explicit human approval)
- `.github/workflows/` (Never modify CI pipelines)
- `tsconfig.json` and linter configurations

Rule 3: Design for Non-Determinism (Stochastic Behavior)

Large Language Models are probabilistic. Never assume the agent's action will succeed on the first try. Your system prompt must define a fallback protocol.

Bad: "Fetch the API data and save it to the database."
Good: "When calling the external API, write error-handling logic with exponential backoff up to 3 retries. If the call still fails, write the complete error payload to logs/error.log and stop the task."

Rule 4: Mandate Automated Evidence Preservation (No Verbal Claims)

Agents are prone to hallucinating task completion. Do not allow them to just say "Everything is working!"

Force the agent to execute real tests and preserve the output files.

Require the agent to output shell execution logs, test suite status codes, and built artifact hashes to a designated folder (e.g., verification/results/).
The system prompt should state: "A task is only considered done when the corresponding test runner output file is generated and matches the expected schema."

Rule 5: Enforce Tool-specific Multi-Line Editing

When editing multiple non-contiguous lines of code, agents often break code files using simple single-line replacements. Instruct them to use multi-replace tools or structural parsers specifically designed for non-adjacent lines. This preserves file integrity and prevents syntax breakage.

DEV Community: shohei-ai-lab

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

Mistake 1: Writing Aspirations Instead of Instructions

The Problem

The Fix

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

The Problem

The Fix

Mistake 3: Listing Tech You Don't Actually Use

The Problem

The Fix

Mistake 4: Constraints Without Alternatives

The Problem

The Fix

Mistake 5: Writing It Once and Never Updating

The Problem

The Fix

Quick Checklist: Does Your CLAUDE.md Actually Work?

Resources

5 Essential System Prompt Rules to Stop Your AI Agents from Going Rogue

Rule 1: Tighten the Role and Grant Specific Authority

Rule 2: Explicitly Restrict File System Mutability

Rule 3: Design for Non-Determinism (Stochastic Behavior)

Rule 4: Mandate Automated Evidence Preservation (No Verbal Claims)

Rule 5: Enforce Tool-specific Multi-Line Editing

Further Reading & Resources