Модульные правила: как не утонуть в CLAUDE.md

Сережа Рис · 17 January 2026

CLAUDE.md раздулся до 400 строк. Агент читает, но запоминает выборочно.

Спросил количество студентов — выдал 19. В базе 24.

Документация врала в трёх местах по-разному.

Как это случилось

Начинаешь проект — пишешь CLAUDE.md. Команды запуска, структура папок, правила коммитов. Через неделю добавляешь схему базы. Ещё через неделю — тесты и особенности фронтенда.

К концу месяца файл на 400 строк. Агент его читает. Но когда данные противоречат друг другу — выбирает случайно.

Количество студентов оказалось записано в трёх местах:

• CLAUDE.md — 19 человек
• .claude/rules/students.md — 19 человек
• База данных — 24 человека

Я забыл обновить документацию после добавления пяти новых студентов. База была правильной, но агент читал markdown.

Решение: .claude/rules/

Claude Code умеет подгружать правила из папки .claude/rules/. Каждый файл — отдельный домен. База данных, тесты, фронтенд, студенты.

.claude/
├── rules/
│   ├── database.md      # схема, миграции, частые ошибки
│   ├── testing.md       # как запускать тесты, фикстуры
│   ├── students.md      # API телеграма, синхронизация
│   ├── atoms.md         # концепция атомов знаний
│   └── frontend/
│       └── ui-patterns.md
└── skills/
    └── ...

В корневом CLAUDE.md остаётся только навигация. Что где искать. Основные команды. Ссылки на rules.

Пример: database.md

Агент трижды пытался сделать SELECT lesson_date FROM lessons. Такой колонки нет — она называется date. Потом пробовал SELECT title и SELECT topic. Тоже мимо — это summary.

Добавил секцию «Before Querying» с командой проверки схемы:

## Before Querying

**Проверяй схему перед SELECT:**

\`\`\`bash
sqlite3 backend/cohorts.db ".schema lessons"
\`\`\`

**Частые ошибки:**
- lesson_date → date
- title, topic → summary
- name → first_name, last_name

Сначала .schema, потом запрос. После этого ошибки прекратились.

Что куда класть

Фильтрация по путям

В начале файла можно указать, когда его подгружать:

---
paths: backend/**/*.py, migrations/**
---

# Database Rules
...

Теперь правила базы подгружаются только когда агент работает с бэкендом. Фронтендеру они не нужны.

Когда обновлять

Документация устаревает. Три правила помогают:

• Добавил фичу — проверь rules
• Нашёл рассинхрон — исправь сразу
• Данные в базе — не дублируй, опиши как достать

Агент находит рассинхроны: читает документацию, проверяет базу, видит противоречие. Спрашивает или ошибается — оба пути ведут к исправлению.

Структура

CLAUDE.md — точка входа: навигация, команды запуска, ссылки на rules.

Правила по доменам — в .claude/rules/. Маленький файл проще обновить и проще найти где ошибка.

База данных — источник правды для изменяемых данных. Агент будет ошибаться. Но не из-за устаревшей документации.

Источники

• The Complete Guide to CLAUDE.md — Builder.io
• Creating the Perfect CLAUDE.md — Dometrain
• Claude Code Project Configuration Showcase — GitHub
• Using AI coding assistants — Modular Docs

Об авторе

Подписаться на обновления — @sereja_tech