Why Most CLAUDE.md Files Fail and How a 65‑Line Guide Got 180K Stars

01 How the 180K stars were earned

In early 2026 Andrej Karpathy posted on X that he shifted from writing 80% of his code manually to letting an AI write 80% of it, then reversed to let an AI agent do 80% of the work while he only reviewed 20%.

He listed four AI‑coding pitfalls:

AI tends to over‑engineer, turning a 100‑line solution into 1,000 lines.

AI silently makes assumptions and pursues them without questioning.

AI arbitrarily refactors unrelated code it dislikes.

AI considers a task done once the code runs, regardless of whether the original problem is solved.

Developer forrestchang packaged these four pitfalls into a 65‑line CLAUDE.md file, pushed it to GitHub, and it quickly amassed 180,000 stars (repository multica-ai/andrej-karpathy-skills).

02 Claude’s “selective reading” mode

When Claude Code loads a CLAUDE.md, it wraps the content with a disclaimer: “The following may be relevant to your current task; if it is highly relevant, obey it; otherwise ignore it.” This means each rule is evaluated for relevance to the current operation.

If a rule is deemed unrelated—e.g., “Never modify test files” while fixing a variable name—Claude skips it, which explains why many rules appear ineffective.

03 Why Karpathy’s 65‑line version works

The file succeeds because it targets the specific mistakes Claude tends to make rather than stating generic coding ideals.

Four core rules and their failure scenarios:

Ask before you act – prevents AI from proceeding on hidden wrong assumptions.

Simplicity first, avoid over‑design – stops AI from rewriting large modules when only a small change is needed.

Touch only task‑relevant code – avoids AI cleaning up unrelated parts.

Validate the real goal, not just that code runs – ensures the intended functionality is achieved.

04 Typical ineffective CLAUDE.md files

Common versions list abstract principles such as “write clear code” or “avoid over‑design”. Claude already knows these concepts, so it treats them as already satisfied and may ignore them.

A concrete example of a bad file:

# 编码规范
- 写清晰、简洁的代码
- 遵循最佳实践
- 保持代码质量
- 做好错误处理
- 写有意义的注释
- 函数要保持短小
- 不要过度设计

Claude can comply with “write clear code” by generating a 1,000‑line function it deems clear.

A good file provides explicit, actionable constraints tied to the project’s structure:

# 项目规范

## 必跑命令（提交前）
- 测试：`npm test`
- 类型检查：`npx tsc --noEmit`
- Lint：`npm run lint`

## 强制约束
- 不允许修改 `src/core/` 目录下的任何文件，除非明确说明可以改
- 函数超过 50 行必须拆分，不允许例外
- 不允许引入新的第三方依赖，除非确认

## 项目特殊情况
- `utils/legacy.ts` 是历史遗留代码，不要动它，但也不要删除
- 测试文件在 `__tests__/` 目录，使用 Jest，不是 Vitest
- 环境变量必须从 `config/env.ts` 读取，不允许直接 `process.env.XXX`

The first version offers principles that Claude can skip; the second lists concrete, task‑specific boundaries that Claude cannot deem irrelevant.

05 Four counter‑intuitive writing tips

Shorter is better, not more comprehensive – Internal Anthropic guidance suggests keeping CLAUDE.md between 20 and 80 lines to avoid exhausting Claude’s context window.

Place the most critical rules at the top – Claude’s attention decays; rules at the beginning are obeyed far more often.

Use imperative language, not descriptive – “Run `npm test`; if it fails, stop and report” gives a clear action, condition, and outcome.

Use nested files instead of one huge document – Claude Code can load src/api/CLAUDE.md, src/database/CLAUDE.md, etc., so each directory only loads the rules it actually needs.

06 An additional pitfall: occasional regression

In April 2026 users reported a rise in ignored directives across versions v2.1.87 to v2.1.92. Anthropic’s post‑mortem confirmed a regression in instruction‑following after an update.

Therefore, CLAUDE.md must be treated as a living document. When Claude violates a rule, either make the rule more specific and imperative, or prepend “No matter what, under any circumstances” to raise its priority.

Summary

The 65‑line file earned 180 K stars because it directly blocks the four most common AI‑coding failure modes with concrete, actionable rules.

Ask yourself: does your CLAUDE.md address the mistakes Claude actually makes, or does it merely repeat generic advice it already knows?

Three immediate actions:

Run the /init command to let Claude auto‑scan the project and generate a base CLAUDE.md, then trim it to under 80 lines.

Fork Karpathy’s 65‑line version and add project‑specific constraints.

When Claude breaks a rule, refine that rule to be more specific and add the “no matter what” prefix; treat CLAUDE.md as an evolving guide, not a static artifact.