---
title: "The Real Reason AI Coding Automation Fails: The Curse of a 300-Line CLAUDE.md and the Conditional-Rules Fix"
date: 2026-09-29
model: admin
category: knowhow
summary: "When CLAUDE.md grows to hundreds of lines, token cost explodes and the model starts ignoring rules. We lay out @import versus the paths-based conditional loading in .claude/rules, the precedence order, and a five-step troubleshooting sequence."
tags: ClaudeCode,CLAUDEmd,context-management,token-optimization,rules,agent
---

AI coding agents raise developer productivity dramatically. But the moment you use one in practice, you hit a wall: the token cost bomb and the **drop in instruction compliance**.

Put your TypeScript conventions, React component rules, API route guidance, and security guidelines all into a project configuration file called `CLAUDE.md`, and the file quickly runs past several hundred lines. The official documentation warns that once a file exceeds **200 lines**, the model's rule compliance rate drops sharply `[00:00:34]`.

You start a single documentation edit session, and several hundred lines of coding rules are loaded into context wholesale, while the instructions that actually matter get ignored `[00:01:13]`. Tokens are spent and the density of the output falls. To solve this you have to understand and apply the conditional rules and file reference structures that Claude Code provides.

Original video: [Claude Code Introduction E23](https://www.youtube.com/watch?v=ICDN7_lry98)

## 1. Static integration (`@` import) versus dynamic loading (`paths`)

When `CLAUDE.md` becomes bloated, the approaches split in two. One does not save tokens. The other genuinely does.

### The `@` mention import (static integration)

You write a file path such as `@README.md` or `@package.json` inside `CLAUDE.md` to merge instructions `[00:05:13]`.

- Reference depth is supported **up to 5 levels** `[00:05:48]`.
- It is loaded into context unconditionally at session start. Splitting and managing files becomes easier, but **the token cost itself does not go down** `[00:06:57]`.

In short, this is a solution to management convenience, not to cost. Merely having split your rules across files does not relieve the context pressure.

### `.claude/rules/` and the `paths` frontmatter (dynamic conditional loading)

The mechanism that actually saves tokens lives here `[00:07:20]`.

- Distribute markdown files by topic (for example `testing.md`, `security.md`) in the `.claude/rules/` directory, and specify a `paths` glob pattern in YAML at the top of the file `[00:03:08]`.
- Instead of always loading at session start, the rule is activated dynamically **at the moment the AI actually reads a file matching the pattern**, such as `src/api/**/*.ts` `[00:02:56]`.
- During unrelated work (for example editing a sentence in the README), unnecessary rules do not occupy context, so token cost drops sharply and instruction compliance rises `[00:02:56]`.

The decisive difference is *when* loading happens. Static integration stacks everything at startup; conditional loading injects only the rule in question, at the moment it is needed. The larger the project, the more this gap grows: not linearly, but proportionally.

## 2. Rule precedence and monorepo/team sharing strategy

When rules conflict across several layers, Claude Code's loading precedence works as follows `[00:08:34]`.

1. **Personal rules (`~/.claude/rules/`)**: personal preferences applied across the whole machine `[00:08:02]`.
2. **Team-wide rules (`.claude/rules/`)**: standard guidance committed to the Git repository and shared with every team member `[00:08:55]`.
3. **How precedence behaves**: personal rules load first, and the team project rules that load later sit closer in context, so the team standard overrides the personal preference `[00:08:34]`.

In multi-repository or monorepo environments, when you need to synchronize company-wide security rules or standard guides, using symbolic links lets you update everything in one place `[00:09:47]`.

## 3. A five-step checklist when rules do not apply

After applying conditional rules, "why isn't the rule I wrote taking effect?" is a common situation. Checking in the following order narrows the cause down quickly `[00:14:21]`.

1. **Check the actual load state with the `/memory` command**: inspect the directory listing of which files are loaded in the current session `[00:12:05]`.
2. **Validate the glob pattern**: check that the `paths` pattern matches the target file path. Matching is done against a path relative to the working directory, not an absolute path `[00:15:00]`.
3. **Check whether the Read trigger fired**: a plain `ls` or bash command is not enough. Claude must actually execute the Read tool on the file for the rule to activate `[00:15:07]`.
4. **Use the `instructions_loaded` hook**: set up an observation hook under `hooks` to record and analyze, in an audit log, the moment a rule loads and the reason why `[00:12:56]`.
5. **Check for conflicting rules**: verify that no other `rules` file contains the exact opposite instruction `[00:14:46]`.

## Conclusion: precise context design is the real competitive edge

In an era where agents flood the market, stuffing every instruction into the prompt leaves nothing but a cost bomb and degraded quality as side effects.

A design like `.claude/rules/` and the `paths` frontmatter — **injecting the minimum necessary context only at the moment it is needed** — is what turns an AI tool into a genuine productivity weapon. Writing fewer rules is not a virtue. Rules being read precisely, at the exact moment they are required, is design.

## References

- Original video: [새로운 시작 (neosarchizo) channel — Claude Code Introduction E23](https://www.youtube.com/watch?v=ICDN7_lry98)
- The `[00:00:34]` timestamps in the body refer to positions in the original video
- Detailed rule behavior may change with Claude Code updates, so check the official documentation for the currently deployed version

## How to install the document skills used above

This guide references Claude Code rules. If you also want the document tooling, the official Anthropic skill repository is available:

```bash
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
```

The repository exposes `skills/docx`, `skills/pdf`, `skills/pptx`, and `skills/xlsx` as open source. Keep in mind that document skills follow progressive disclosure: roughly 100 tokens of metadata per skill are always resident, the `SKILL.md` body stays under 5k tokens and loads only on trigger, and scripts load only when they are actually needed. That structure is the same principle this article recommends for project rules.