`.claude/rules/` с path-scoping: модульные правила

Проблема

CLAUDE.md отлично работает для одного проекта. Но когда команда растёт:

• API-конвенции для backend-файлов
• Frontend-правила для React
• Тестовые стандарты отдельно
• Правила безопасности
• Соглашения деплоя

Получается CLAUDE.md на 300+ строк который никто не поддерживает и все игнорируют.

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

Папка с markdown-файлами, каждый с YAML-фронтматтером paths:.

.claude/rules/
├── api-conventions.md      # только для src/api/
├── react-patterns.md       # только для src/components/
├── testing.md              # только для **/*.test.*
├── db-layer.md             # только для src/db/
└── security.md             # только для src/auth/

Пример файла с path-scoping

.claude/rules/api-conventions.md:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
 
API Design Rules
- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients
- Log errors with request_id correlation

Claude не загрузит это правило когда редактирует React-компонент. Оно сработает только если Claude работает внутри src/api/ или src/handlers/.

Чисто. Фокусированно. Эффективно.

Ещё примеры

.claude/rules/testing.md

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "tests/**/*.ts"
---
 
Testing Rules
- Tests use Vitest, not Jest
- No mocks for database — use real test DB (npm run db:test:reset first)
- Every test file must have at least one "edge case" test
- Prefer data-driven tests with describe.each

.claude/rules/react-components.md

---
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---
 
React Component Rules
- Functional components only, no classes
- Props typed with interface, not type
- Default exports for pages, named for components
- Use Tailwind utility classes, no CSS modules

.claude/rules/infra.md

---
paths:
  - "terraform/**/*.tf"
  - "infra/**/*.yaml"
  - "docker-compose*.yml"
---
 
Infrastructure Rules
- Always review IAM changes with extra scrutiny
- No hardcoded secrets — use AWS Secrets Manager refs
- Container images must be pinned to SHA, not latest
- Terraform state is remote (s3), never commit .tfstate

Преимущество перед CLAUDE.md в поддиректориях

Альтернатива: разместить CLAUDE.md в каждой поддиректории проекта.

Не работает когда:

• Файлы разбросаны (тесты лежат рядом с кодом: Button.tsx и Button.test.tsx)
• Конвенции охватывают файлы в разных директориях
• Нужна гибкость glob-паттернов

.claude/rules/ с paths: решает все эти случаи.

Вопрос экзамена Architect (вопрос 6)

Именно это решение — правильный ответ на задачу: "Кодбейз имеет разные конвенции для разных областей, тесты рядом с кодом, как применить автоматически?"

• ✅ .claude/rules/ с YAML-frontmatter и glob-паттернами
• ❌ CLAUDE.md в поддиректориях (не работает для тестов)
• ❌ Skills (требуют явного вызова)
• ❌ Объединить всё в корневой CLAUDE.md (расплывается внимание)

Как работает загрузка

Когда Claude открывает файл src/api/users.ts:

1. Читает корневой CLAUDE.md (общие правила)
2. Сканирует .claude/rules/*.md
3. Для каждого файла проверяет paths: — подходит ли src/api/users.ts
4. api-conventions.md (paths: src/api/**/*.ts) ✅ — загружается
5. react-patterns.md (paths: src/components/**) ❌ — пропускается
6. Собирается финальный системный промпт

Результат: контекст чистый, правил ровно столько сколько нужно.

Рекомендуемый паттерн организации

.claude/
├── CLAUDE.md               # общие правила для всего проекта (≤ 100 строк)
└── rules/
    ├── api.md              # backend
    ├── react.md            # frontend
    ├── testing.md          # тесты
    ├── db.md               # модели, миграции
    ├── security.md         # auth, secrets
    └── infra.md            # IaC, докер

CLAUDE.md содержит только то что нужно везде (команды, общая архитектура). Остальное — в специализированные правила.

Миграция с раздутого CLAUDE.md

Если сейчас CLAUDE.md на 400 строк:

1. Сгруппируй секции по area ("API", "Frontend", "Tests"...)
2. Найди для каждой группы glob-паттерн путей
3. Вынеси в отдельный файл .claude/rules/<area>.md с paths:
4. В CLAUDE.md оставь только универсальное (команды, общая структура)
5. Проверь размер: wc -l CLAUDE.md — должно быть ≤150

Практика (20 минут)

Задача 1. Миграция

1. Открой свой CLAUDE.md
2. Найди 1 секцию которая относится только к одной области (например, "API conventions")
3. Создай .claude/rules/api.md с paths: ["src/api/**/*.ts"]
4. Скопируй секцию туда
5. Удали её из CLAUDE.md
6. Проверь: /memory в сессии, увидишь что rule подгружается только при работе с API

Задача 2. Testing rules

Если у тебя есть тесты — создай .claude/rules/testing.md со своими предпочтениями (какой раннер, моки или реальная DB, coverage требования). Path: **/*.test.*.

Что дальше

Следующий урок: управление контекстом как навык #1. Правило двух попыток, scratchpads, lost-in-the-middle эффект.