Как устроен Claude Code

Модель исполнения, skills, агенты и rules

27 марта 2026

Claude Code - агентная система с многоуровневой загрузкой контекста, механизмами расширения и автоматизацией жизненного цикла. Под капотом - не просто вызов API с промптом: при каждом запуске собирается контекст из десятка источников, применяются правила доступа, загружаются skills и описания субагентов. Статья разбирает эту архитектуру: что попадает в контекстное окно, в каком порядке, и как управлять поведением агента через rules, skills, agents и hooks.

Сборка контекста: что видит модель CLAUDE.md: иерархия инструкций Rules: точечные правила для контекста Skills: расширяемые команды Субагенты: изолированный контекст Hooks: автоматизация жизненного цикла Система прав: permissions Settings: техническое управление Кто кого вызывает Как всё связано Ментальная модель: сессии работы в SDLC

Сборка контекста: что видит модель

Claude Code состоит из двух слоёв: harness (TypeScript-приложение) и модель (LLM). Harness управляет жизненным циклом: собирает контекст, проверяет права, запускает hooks, инжектирует инструкции. Модель получает уже собранный контекст и работает внутри него - она не знает, откуда взялись инструкции, и не может управлять их загрузкой.

При запуске сессии harness собирает контекст из нескольких источников. Часть загружается сразу при старте, часть - по мере работы.

Загружается при старте сессии

Harness выполняет всё перечисленное автоматически до первого вызова модели:

Инжектируется по мере работы

Эти инжекции тоже выполняет harness, а не модель. Модель вызывает инструмент (например, Read), а harness перехватывает вызов и проверяет, нужно ли добавить дополнительный контекст:

Содержимое CLAUDE.md инжектируется harness как user message после system prompt, а не как часть системного промпта. Для модели это выглядит как сообщение от пользователя с инструкциями. Это guidance (рекомендация), а не enforcement (ограничение). Техническое ограничение поведения - задача settings и permissions, которые harness проверяет на уровне кода, а не через промпт.

При compaction (сжатии контекста, когда окно приближается к лимиту) harness перечитывает CLAUDE.md с диска и инжектирует заново - поэтому инструкции полностью переживают сжатие. Auto memory тоже сохраняется (хранится на диске). Инструкции, данные только в чате без фиксации в файлах, теряются.

CLAUDE.md: иерархия инструкций

CLAUDE.md - основной механизм передачи инструкций агенту. Три уровня с разным охватом:

Уровень Расположение Кто пишет Область действия
Managed /Library/Application Support/ClaudeCode/CLAUDE.md IT / администраторы Все пользователи на машине
Project ./CLAUDE.md или ./.claude/CLAUDE.md Команда Текущий проект (коммитится в git)
User ~/.claude/CLAUDE.md Разработчик Все проекты пользователя

Более специфичный уровень имеет приоритет. Если project CLAUDE.md говорит "используй tabs", а user CLAUDE.md говорит "используй spaces" - для этого проекта победят tabs.

Синтаксис @import

CLAUDE.md поддерживает ссылки на другие файлы через @path/to/file. При загрузке ссылка раскрывается, и содержимое файла подставляется в контекст. Максимальная глубина вложенности - 5 уровней. Работают как относительные, так и абсолютные пути. 

# CLAUDE.md

## Архитектура
@docs/architecture.md

## Стандарты кодирования
@docs/coding-standards.md

## API-контракты
@docs/api-contracts.md

Это позволяет держать CLAUDE.md компактным, а детальную документацию - в отдельных файлах, которые полезны и без Claude Code.

Экономия токенов

Блочные HTML-комментарии (<!-- ... -->) в CLAUDE.md вырезаются перед инжекцией. Можно оставлять заметки для людей, которые не тратят токены агента: 

<!-- TODO: добавить раздел про миграции после перехода на Rails 8 -->

## Database
Используй `bin/rails db:migrate` для применения миграций.

CLAUDE.md vs Auto Memory

CLAUDE.md Auto Memory
Кто пишет Разработчик Claude
Содержит Инструкции и правила Наблюдения и паттерны
Загрузка Полностью, каждая сессия Первые 200 строк / 25KB
Compaction Переживает (перечитывается с диска) Переживает (на диске)

Auto memory хранится в ~/.claude/projects/<project>/memory/. Индексный файл MEMORY.md загружается при старте, а topic-файлы (debugging.md, patterns.md) - по запросу. Все worktrees и поддиректории одного git-репозитория разделяют одну директорию auto memory.

Rules: точечные правила для контекста

Rules - это markdown-файлы в .claude/rules/, каждый из которых описывает одну тему: тестирование, API-дизайн, стиль кода. В отличие от монолитного CLAUDE.md, rules позволяют структурировать инструкции по темам и загружать часть из них условно.

Безусловные правила

Файл без frontmatter загружается при каждом старте сессии вместе с CLAUDE.md: 

# .claude/rules/testing.md

Все тесты пишутся на RSpec.
Используй `let` вместо instance variables.
Максимум 3 expectation на example.
Не мокай базу данных в интеграционных тестах.

Path-scoped правила

YAML frontmatter с полем paths делает правило условным. Harness сам отслеживает, какие файлы модель читает через инструмент Read. Если путь файла совпадает с glob-паттерном - harness автоматически инжектирует содержимое правила в контекст. Модель не запрашивает загрузку и не знает о существовании правила до момента инжекции. 

# .claude/rules/api-versioning.md
---
paths:
  - "app/controllers/api/**/*.rb"
  - "spec/requests/api/**/*_spec.rb"
---

API-контроллеры наследуют Api::BaseController.
Версионирование через namespace: Api::V1, Api::V2.
Каждый endpoint покрыт request spec.

Когда модель вызывает Read("app/controllers/api/v1/users_controller.rb"), harness видит совпадение с паттерном app/controllers/api/**/*.rb и добавляет правило в контекст вместе с содержимым файла. При работе с фронтенд-файлами правило не загружается. Это экономит контекстное окно и снижает шум.

User-level правила

Файлы в ~/.claude/rules/*.md действуют на все проекты конкретного разработчика. Загружаются до project rules (с более низким приоритетом - project rules переопределяют user-level). Полезны для персональных предпочтений: язык ответов, формат коммитов, стиль комментариев.

Когда rules, а когда CLAUDE.md

Ситуация Механизм
Общие инструкции для всего проекта CLAUDE.md
Правила для конкретной части кодовой базы Path-scoped rule
Персональные предпочтения разработчика User-level rule или ~/.claude/CLAUDE.md
Детальная документация, на которую ссылается CLAUDE.md @import в CLAUDE.md

Skills: расширяемые команды

Skills - markdown-файлы с YAML frontmatter и инструкциями, расширяющие возможности Claude Code. Пользователь вызывает skill как /skill-name, а Claude может вызвать его автоматически, если описание skill совпадает с текущей задачей.

Структура файлов

.claude/skills/
  deploy/
    SKILL.md           # Обязательная точка входа
    checklist.md       # Вспомогательный файл
  review-pr/
    SKILL.md
    templates/
      review.md

SKILL.md: frontmatter

---
name: deploy
description: "Запускает деплой в production с проверкой чеклиста"
allowed-tools:
  - Bash(./optimized_deploy.sh)
  - Read
model: sonnet
---

# Deploy

1. Прочитай чеклист из deploy/checklist.md
2. Проверь, что все пункты выполнены
3. Запусти ./optimized_deploy.sh
4. Сообщи результат

Ключевые поля frontmatter:

Поле Назначение
name Имя, становится /slash-command
description Описание. Claude использует его для автоматического вызова
allowed-tools Инструменты, разрешённые без подтверждения при работе skill
model Модель для выполнения (sonnet, opus, haiku)
context fork - запуск в изолированном контексте субагента
disable-model-invocation true - только пользователь может вызвать
user-invocable false - только Claude может вызвать (фоновые знания)
paths Glob-паттерны, ограничивающие автоматическую активацию

Подстановки и динамический контекст

В теле SKILL.md работают подстановки:

Синтаксис !`command` выполняет shell-команду до отправки содержимого skill модели. Вывод команды подставляется на место плейсхолдера: 

---
name: check-ci
description: "Проверяет статус CI для текущей ветки"
---

# CI Status

Текущая ветка: !`git branch --show-current`
Статус последнего коммита: !`gh run list --limit 1 --json status,conclusion --jq '.[0]'`

Проанализируй результат и предложи действия.

Расположение и приоритеты

Приоритет Расположение Область действия
1 (высший) Enterprise (managed settings) Все пользователи организации
2 ~/.claude/skills/<name>/SKILL.md Все проекты пользователя
3 .claude/skills/<name>/SKILL.md Текущий проект
4 (низший) Plugin skills/ Где подключён plugin

Контроль вызова

Frontmatter Пользователь Claude
(по умолчанию) Может вызвать Может вызвать
disable-model-invocation: true Может вызвать Не может
user-invocable: false Не может Может вызвать

Типичный паттерн: деструктивные операции (деплой, миграции) помечаются disable-model-invocation: true, чтобы Claude не запустил их самостоятельно. Фоновые знания (стайл-гайды, доменные справочники) помечаются user-invocable: false.

Субагенты: изолированный контекст

Когда модель вызывает инструмент Agent, harness создаёт отдельное контекстное окно с собственным системным промптом, набором инструментов и правами. Внутри этого окна запускается новый цикл вызовов модели. Результат возвращается обратно в основной контекст как текст. Всё происходит внутри одного процесса Claude Code - отдельного процесса не запускается. 

Main agent (context window A)
  |
  |-- Agent("найди все эндпоинты API")
  |     \-- Subagent Explore (context window B)
  |          |-- Grep, Glob, Read...
  |          \-- return: "найдено 12 эндпоинтов в api/v1/"
  |
  |-- (результат вернулся в context window A)
  \-- продолжает работу

Claude Code поставляется с несколькими предопределёнными субагентами:

Агент Модель Инструменты Назначение
Explore Haiku (быстрая) Только чтение Поиск и анализ кодовой базы
Plan Наследует Только чтение Исследование для режима планирования
general-purpose Наследует Все Многошаговые задачи
Bash Наследует Терминал Команды в отдельном контексте

Предопределённые и проектные субагенты работают одинаково - разница только в том, кто написал определение. Проектные субагенты определяются как markdown-файлы в .claude/agents/, пользовательские - в ~/.claude/agents/. 

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: "Ревью кода: стиль, безопасность, производительность"
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash(bundle exec rubocop $FILE)
maxTurns: 15
---

# Code Reviewer

Ты - ревьюер кода. Проверяй:
1. Соответствие стандартам проекта (прочитай .claude/CLAUDE.md)
2. Потенциальные проблемы безопасности (SQL injection, XSS)
3. Производительность (N+1 запросы, отсутствие индексов)
4. Покрытие тестами

Не предлагай стилистические изменения, если код проходит rubocop.

Ключевые поля frontmatter:

Поле Назначение
tools Whitelist инструментов
disallowedTools Blacklist инструментов
model sonnet, opus, haiku или inherit
maxTurns Максимум агентных шагов
skills Skills, предзагружаемые в контекст субагента
memory Persistent memory: user, project или local
isolation worktree - работа в изолированной копии репозитория
background true - всегда запускать как фоновую задачу

Ограничения

Способы вызова

  1. Автоматический - Claude делегирует задачу на основе description субагента.
  2. Естественный язык - упоминание имени агента в промпте.
  3. @-mention - @"code-reviewer (agent)" гарантирует вызов конкретного субагента.
  4. Для всей сессии - claude --agent code-reviewer или "agent": "code-reviewer" в settings. В этом режиме .md-файл агента заменяет системный промпт основного агента целиком.

Persistent memory субагентов

Субагенты с полем memory получают собственную директорию памяти:

При старте загружаются первые 200 строк / 25KB из MEMORY.md. Это позволяет субагенту накапливать знания между сессиями: паттерны проекта, типичные ошибки, предпочтения команды.

Hooks: автоматизация жизненного цикла

Hooks - ещё один механизм, который выполняет harness, а не модель. Harness запускает shell-команды, HTTP-запросы, LLM-промпты или вызовы субагентов в определённые моменты жизненного цикла. Модель не контролирует и не инициирует hooks - она даже не знает, какие hooks сконфигурированы. Конфигурация хранится в settings.json.

Типы событий

Категория События Назначение
Сессия SessionStart, SessionEnd, Stop Инициализация окружения, очистка ресурсов
Инструменты PreToolUse, PostToolUse, PostToolUseFailure Валидация и наблюдаемость вызовов инструментов
Ввод UserPromptSubmit Обработка пользовательского ввода до отправки модели
Контекст InstructionsLoaded, PreCompact, PostCompact Управление загрузкой инструкций и сжатием
Субагенты SubagentStart, SubagentStop Реакция на жизненный цикл субагентов
Файлы FileChanged, CwdChanged Отслеживание изменений файловой системы
Права PermissionRequest Реакция на запросы подтверждения

Четыре типа обработчиков

  1. Command - выполняет shell-команду. Получает JSON на stdin.
  2. HTTP - POST-запрос с JSON-телом на указанный endpoint.
  3. Prompt - однократная LLM-оценка (single-turn), без контекста сессии.
  4. Agent - порождает субагента с доступом к инструментам.

Конфигурация

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate-edit.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Session started at $(date)' >> ~/.claude/session.log"
          }
        ]
      }
    ]
  }
}

Exit codes и управление решениями

Для command-хуков exit code определяет поведение:

Через JSON-ответ хук может управлять поведением: 

{
  "decision": "block",
  "reason": "Файл .env не должен редактироваться агентом"
}

Для PreToolUse доступно управление правами: 

{
  "hookSpecificOutput": {
    "permissionDecision": "allow"
  }
}
PreToolUse хуки выполняются до запроса прав. Хук может вернуть "allow", но это не обходит deny-правила из settings - они проверяются после хука.

Система прав: permissions

Каждый инструмент Claude Code требует определённого уровня подтверждения:

Тип Примеры Подтверждение
Read-only Read, Grep, Glob Не требуется
Bash Shell-команды Да (запоминается навсегда для проекта + команда)
File modification Edit, Write Да (до конца сессии)

Порядок проверки: deny -> ask -> allow

Harness проверяет правила в порядке deny, ask, allow. Первое совпадение побеждает. Deny-правила всегда имеют приоритет. Это enforcement на уровне кода - модель не может обойти deny-правило, даже если CLAUDE.md говорит иное. Правила настраиваются в settings.json: 

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(bundle exec rspec *)",
      "Read",
      "Edit(/src/**/*.ts)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Edit(.env*)",
      "Write(.claude/settings.json)"
    ]
  }
}

Синтаксис правил

Permission modes

Режим Поведение
default Стандартные запросы подтверждения
acceptEdits Автоматическое одобрение редактирования файлов
plan Только чтение, без модификаций
auto Фоновый классификатор безопасности (research preview)
bypassPermissions Без подтверждений (кроме записи в .git, .claude, .vscode, .idea)

Settings: техническое управление

Settings контролируют техническое поведение Claude Code: какие инструменты доступны, как работает sandbox, какие хуки запускаются. В отличие от CLAUDE.md (guidance для модели), settings - enforcement, который Claude не может обойти.

Файлы и приоритеты

Приоритет Файл Назначение
1 (высший) Managed settings (plist/registry/server) Корпоративные политики. Нельзя переопределить.
2 CLI-аргументы Временные переопределения для сессии
3 .claude/settings.local.json Локальные настройки (gitignored)
4 .claude/settings.json Проектные настройки (в git)
5 (низший) ~/.claude/settings.json Пользовательские настройки

Ключевые параметры

{
  "permissions": {
    "allow": ["Bash(bundle exec *)"],
    "deny": ["Edit(.env*)"]
  },
  "hooks": { },
  "env": {
    "RAILS_ENV": "test",
    "DATABASE_URL": "postgres://localhost/myapp_test"
  },
  "model": "sonnet",
  "agent": "code-reviewer",
  "autoMemoryEnabled": true,
  "includeGitInstructions": true,
  "claudeMdExcludes": ["packages/legacy/**"]
}

claudeMdExcludes полезен в монорепозиториях: можно исключить CLAUDE.md из нерелевантных пакетов, чтобы не тратить контекст.

Enterprise-only параметры

Managed settings добавляют параметры, недоступные на других уровнях:

Кто кого вызывает

Claude Code - агентный цикл: модель получает контекст, решает какой инструмент вызвать, получает результат, решает снова. Ключевой вопрос - кто может инициировать вызов и в каком контексте он выполняется.

Цепочка вызова инструмента

Модель генерирует вызов инструмента (например, Edit("app/models/user.rb", ...)). Дальше управление переходит к harness, который прогоняет вызов через цепочку проверок. Модель не участвует в этих проверках - она ждёт результат. 

Модель генерирует tool_use
  -> [harness] PreToolUse hooks (могут заблокировать)
    -> [harness] Permission rules: deny -> ask -> allow
      -> [harness] Запрос подтверждения у пользователя (если нужен)
        -> [harness] Выполнение инструмента
          -> [harness] Инжекция path-scoped rules (если Read)
            -> [harness] PostToolUse hooks (наблюдаемость)
              -> Результат возвращается модели

Кто может вызвать кого

Вызывающий Может вызвать
Пользователь Основной агент (через промпт), skill (через /name), субагент (через @name или --agent)
Основной агент Любой инструмент, любой субагент, любой skill
Субагент Только инструменты из своего tools списка. Не может вызвать другого субагента
Skill Инструменты из allowed-tools (без подтверждения) + остальные (с подтверждением)
Hook Shell-команду, HTTP-запрос, LLM-промпт или субагента (тип agent)

Где выполняется вызов

Механизм Контекст выполнения Видит историю чата
Инструменты (Read, Bash, Edit...) Основной Да
Skill (по умолчанию) Основной - содержимое инжектируется в текущий разговор Да
Skill с context: fork Изолированный (порождается субагент) Нет
Субагент (Agent) Всегда изолированный Нет
Hook (command / http) Вне контекста модели (shell-процесс или HTTP-вызов) Нет - получает JSON о текущем событии
Hook (prompt) Одноразовый LLM-вызов без контекста сессии Нет
Hook (agent) Изолированный (порождается субагент) Нет
--agent name (режим сессии) Заменяет основной агент - .md-файл становится системным промптом Да (это и есть основной контекст)
Skill без context: fork работает в основном контексте - Claude видит всю историю, CLAUDE.md, rules и память. Это удобно, когда skill должен учитывать текущий разговор. context: fork полезен для тяжёлых или независимых задач: изоляция защищает основное окно от загрязнения большим объёмом промежуточных результатов.

Ограничения вложенности

Пользователь
  \-- Основной агент
       |-- Субагент A          (свой контекст)
       |    |-- Read, Grep...   (инструменты)
       |    \-- Agent(B)        X ЗАПРЕЩЕНО
       |
       |-- Субагент B          (свой контекст)
       |    \-- Read, Bash...   (инструменты)
       |
       |-- Skill "deploy"      (основной контекст)
       |    \-- Bash, Read...   (инструменты)
       |
       \-- Skill "review"      (context: fork -> субагент)
            \-- Read, Grep...   (инструменты)

Запрет на вложенность субагентов - принципиальное ограничение. Если субагенту нужна помощь другого специалиста, он возвращает результат основному агенту, а тот решает, кого вызвать следующим.

Что видит каждый участник

Участник CLAUDE.md Rules Auto Memory Skills История чата
Основной агент Да Да Да Описания + полное содержимое при вызове Вся
Субагент Нет (только если прочитает файл сам) Нет Своя memory (если настроена) Только из поля skills Только своя
Hook (command) Нет Нет Нет Нет Нет (получает JSON о текущем вызове)
Субагент не наследует контекст основного агента. Он не знает, о чём вы разговаривали, какие файлы уже читали, какие решения принимали. Всё, что ему нужно, должно быть передано в промпте при вызове Agent или определено в его .md-файле.

Как всё связано

Компоненты Claude Code образуют систему с чёткими зонами ответственности.

CLAUDE.md и settings

CLAUDE.md Settings
Природа Guidance (рекомендация) Enforcement (ограничение)
Может Claude обойти Теоретически да Нет
Содержит Стандарты кода, рабочие процессы Права, хуки, sandbox, модель
Когда использовать "Пиши тесты на RSpec" "Запрети редактировать .env"

Memory и compaction

Практическое правило: если инструкция должна действовать дольше одного разговора - CLAUDE.md. Если дольше одной сессии и для конкретной части кода - rule. Если нужно техническое ограничение - settings. Если нужна повторяемая процедура - skill. Если нужна изоляция контекста - субагент.

Полная картина

+--------------------------------------------------+
|                  Claude Code                      |
|                                                   |
|  +--------------------------------------------+  |
|  |           Context Window                    |  |
|  |                                             |  |
|  |  System Prompt                              |  |
|  |  + Managed CLAUDE.md                        |  |
|  |  + Directory CLAUDE.md (hierarchy)          |  |
|  |  + Project / User CLAUDE.md                 |  |
|  |  + Rules (unconditional)                    |  |
|  |  + Auto Memory (MEMORY.md, 200 lines)       |  |
|  |  + Skill descriptions (2% budget)           |  |
|  |  + Git status                               |  |
|  |  + Conversation history                     |  |
|  |  + [on demand] Path-scoped rules            |  |
|  |  + [on invoke] Full skill content           |  |
|  +--------------------------------------------+  |
|                                                   |
|  Settings --> Permissions --> deny/ask/allow       |
|           --> Hooks       --> Pre/Post lifecycle   |
|           --> Sandbox     --> FS/network limits    |
|                                                   |
|  Subagents --> Own context window                 |
|            --> Own tools, model, permissions       |
|            --> Cannot spawn subagents              |
|            --> Optional persistent memory          |
+--------------------------------------------------+

Ментальная модель: сессии работы в SDLC

Техническое понимание архитектуры - половина дела. Вторая половина - как выстроить рабочий процесс, чтобы инструменты из предыдущих секций работали вместе. Ниже - модель, выработанная на практике: какие типы сессий бывают, что в проекте должно быть настроено под каждую, и как это выглядит в повседневной работе.

Типы сессий

Каждая сессия с Claude Code - это одна задача с определённым масштабом. Не монолитный рабочий день, а дискретная единица работы:

Тип сессии Пример Что задействовано
E2E фича Добавить endpoint /api/v1/bookmarks с контроллером, моделью, миграцией, спекой CLAUDE.md (архитектура, стандарты), path-scoped rules (API, тесты), skills (генерация спек, ревью)
Только тесты Покрыть request spec-ами существующий контроллер Path-scoped rules (тестирование), skill для генерации спек, CLAUDE.md (тест-фреймворк, покрытие)
Рефакторинг Вынести shared logic в concern или service CLAUDE.md (паттерны проекта), Explore-субагент (поиск зависимостей), hooks (rubocop post-edit)
Баг-фикс Исправить N+1 в отчёте CLAUDE.md, auto memory (если похожий баг уже встречался), path-scoped rules (SQL, performance)
Code review Проверить PR коллеги Субагент code-reviewer с read-only tools, skill для ревью
Исследование Разобраться, как работает legacy-модуль Plan mode (read-only), Explore-субагент, auto memory (сохранит находки)

Сессия E2E: как это выглядит

Типичная сессия для добавления фичи от начала до конца: 

1. Запуск: claude
   -> harness загружает CLAUDE.md, rules, auto memory
   -> модель видит архитектуру проекта, стандарты, тест-паттерны

2. Промпт: "Добавь endpoint POST /api/v1/bookmarks..."
   -> модель читает routes.rb, существующие контроллеры
   -> harness инжектирует path-scoped rule для API
   -> модель создаёт миграцию, модель, контроллер, спеку

3. Проверка: модель запускает bundle exec rspec
   -> harness проверяет permission (Bash разрешён для bundle exec)
   -> тесты проходят или падают
   -> модель фиксит то, что упало

4. Линтер: модель запускает bundle exec rubocop
   -> фиксит offenses

5. Результат: готовый PR с кодом, тестами, миграцией

В рамках одной сессии контекст накапливается: модель помнит, какие файлы создала, какие тесты упали, какие решения приняла. При переходе к новой сессии (новая задача) контекст сбрасывается, но CLAUDE.md и auto memory сохраняются.

Что добавлять в проект под каждый тип работы

Базовая настройка (один раз)

.claude/
  CLAUDE.md               # Архитектура, стек, команды, стандарты
  settings.json           # Permissions: allow bundle exec, deny .env edits
  rules/
    testing.md            # RSpec-конвенции, покрытие, без моков БД
    code-style.md         # Rubocop, именование, структура файлов
  agents/
    code-reviewer.md      # Read-only агент для ревью

Для E2E фич

.claude/
  rules/
    api-design.md         # paths: app/controllers/api/** - REST-конвенции
    migrations.md         # paths: db/migrate/** - правила миграций
  skills/
    new-endpoint/
      SKILL.md            # Генерирует контроллер + спеку по шаблону

Для тестирования

.claude/
  rules/
    rspec-patterns.md     # paths: spec/** - паттерны, shared examples
  skills/
    write-spec/
      SKILL.md            # Генерирует спеку для указанного файла

Для code review

.claude/
  agents/
    code-reviewer.md      # tools: Read, Grep, Glob (без Edit/Write)
  skills/
    review-pr/
      SKILL.md            # disable-model-invocation: true

Паттерн: одна сессия - одна задача

Контекстное окно - конечный ресурс. Чем дольше сессия, тем больше в окне накапливается промежуточных результатов, и тем выше вероятность, что модель начнёт путать ранние и поздние решения. Compaction сохраняет CLAUDE.md, но теряет нюансы обсуждений.

Практические следствия:

Эволюция проектной конфигурации

Конфигурация Claude Code растёт вместе с проектом. Типичная траектория:

Этап Что добавляется Зачем
Неделя 1 CLAUDE.md с архитектурой и командами Агент перестаёт спрашивать "какой фреймворк?" каждую сессию
Неделя 2 Settings с permissions (allow/deny) Не нужно подтверждать bundle exec rspec каждый раз
Неделя 3 Rules для тестов и API Агент пишет спеки в стиле проекта, а не generic RSpec
Месяц 1 1-2 skills для повторяемых задач Генерация endpoint-а или спеки за один /command
Месяц 2 Субагент для code review Ревью PR-ов без ручной настройки read-only режима
По необходимости Hooks для CI, линтеров, валидации Автоматические проверки без промпта "запусти rubocop"
Конфигурация - это кодификация рабочих соглашений команды. CLAUDE.md описывает "как мы пишем код". Rules описывают "как мы пишем код в этой части проекта". Skills описывают "как мы выполняем эту конкретную операцию". Если соглашения не формализованы - Claude Code будет работать, но каждый разработчик получит разный результат.

Источники