008 ИИ: Анатомия .claude. Контекст, безопасность и масштабирование

Интеграция автономных ИИ-агентов в процесс разработки требует перехода от простых чат-интерфейсов к строгой инженерной дисциплине. Claude Code CLI - один из первых инструментов, который переносит языковую модель непосредственно в терминал разработчика, давая ей доступ к файловой системе, локальным скриптам и контексту проекта.

Поскольку это относительно новый инструмент, академических работ конкретно по его конфигурационному ядру - файлу CLAUDE.md - еще не существует. Однако сама механика его работы базируется на обширных исследованиях в области System Prompting и Agentic Context Management.

Официальная документация - code.claude.com. Здесь вы сможете подробно ознакомиться с базовой механикой файлов конфигурации и иерархией памяти агента. Рекомендую изучить ее лично, так как внутри содержится фундамент, от которого я буду отталкиваться в этой статье, разбирая более сложные промышленные паттерны.

Для более глубокого погружения в экосистему CLI-агента стоит пройти курсы на платформе Anthropic (в частности, Claude Code 101 и Claude Code in Action). Особое внимание уделите модулю Introduction to agent skills, где рассказывается, как писать переиспользуемые инструкции (Skills), которые агент применяет автономно. А также Introduction to subagents - это прямая база для проектирования сложных AI-систем, где контекст разгружается за счет делегирования рутины изолированным сущностям.

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

Топология конфигурации и уровни видимости. Разделение на глобальный уровень и уровень репозитория

Согласно документации, Claude Code собирает настройки из двух основных мест: глобальной директории пользователя и локальной директории проекта. В корпоративной среде это разделение позволяет разделить личные предпочтения разработчика и общие архитектурные стандарты команды.

1. Глобальный уровень (~/.claude/). Это персональный профиль, чаще всего необходим, если работа ведется в команде и при локальной разработке требуются точечные настройки пространства и процесса. Конфигурация здесь применяется ко всем проектам, с которыми вы работаете. Специфика рабочего места, персональные скрипты, уровень экспертизы и подобное.

2. Уровень проекта (/ или /.claude/ внутри репозитория). Здесь лежит конфигурация, специфичная для конкретного микросервиса. Эти файлы обязательно коммитятся в Git, чтобы вся команда и CI/CD-пайплайны (если агент запускается там) работали в едином контексте. По расположению допускается держать CLAUDE.md в корне, но в сложных проектах корень и так перегружен (pom.xml / build.gradle, Dockerfile, манифесты Kubernetes). Практика высоконагруженных сред - прятать всю конфигурацию агента в папку .claude/ в корне проекта (например, .claude/CLAUDE.md), чтобы сохранить чистоту репозитория.

3. Персональные переопределения в проекте (settings.local.json и CLAUDE.local.md). В Enterprise-средах часто бывает ситуация, когда у команды есть строгий CLAUDE.md (например, "использовать только PostgreSQL"), но вы локально разворачиваете базу в специфичном Docker-контейнере с нестандартным портом для дебага. Для этого мы добавляем settings.local.json (позволяет локально переопределить настройки агента. Этот файл автоматически игнорируется Git) и CLAUDE.local.md (можно создать этот файл в корне проекта, добавить его в .gitignore и прописать туда свои личные инструкции для агента на время разработки фичи. Он будет загружен вместе с основным CLAUDE.md).

В промышленной разработке мы не сваливаем всё в один файл. Мы формируем строгую топологию, где глобальный конфиг отвечает за удобство разработчика, .claude/ в репозитории формирует командный контракт, а .local файлы изолируют временные эксперименты.

Напомню, что секреты (токены, API-ключи, пароли к БД, ..) мы продолжаем хранить в отдельном месте, например Vault. Агент умеет читать переменные окружения. В промышленных средах перед запуском терминала (или CI/CD пайплайна, где бежит агент) скрипт авторизуется в Vault, забирает нужные секреты и экспортирует их в переменные окружения сессии (например, export DB_PASSWORD=$(vault kv get -field=password secret/db)). Claude Code прозрачно их использует.

В очень зрелых AI-средах иногда используют гибридный подход. Сам CLAUDE.md в проекте тонкий, но в нем прописана команда: "Прежде чем писать код, выполни скрипт ./fetch-domain-context.sh". Этот скрипт может сходить в корпоративный Confluence (используя токен из Vault), скачать свежую архитектурную схему микросервиса (ADR - Architecture Decision Record) в виде текста и скормить ее агенту в текущую сессию.

Таким образом, статические правила живут в Git, секреты - в Vault, а актуальные знания бизнеса подтягиваются динамически.

Глубокий разбор CLAUDE.md. Загрузка в память, лимиты и формирование жесткого контракта для проекта

CLAUDE.md - это ядро системы управления поведением агента. В промышленной разработке мы перестаем воспринимать его как текстовый файл и начинаем относиться к нему как к манифесту системного промпта, который имеет строгую вычислительную стоимость и ограничения.

Предлагаю разобрать механику под капотом, правила контрактования и продвинутую стратегию динамического контекста.

1. Механика. Загрузка в память и лимиты.

При каждом вашем запросе в терминале Claude Code не просто читает CLAUDE.md. Происходит цикл сборки системного промпта, инструмент берет базовые инструкции (как использовать bash, как читать файлы), добавляет ваши глобальные настройки, затем внедряет CLAUDE.md проекта, и только потом добавляет историю текущего чата и ваш новый промпт.

В высоконагруженных системах мы всегда считаем ресурсы. Здесь ресурсы - это токены и внимание модели.

Ключевые лимиты:

- Современные LLM имеют окно в 200 000 токенов. Вы можете загрузить туда хоть всю документацию по Spring Boot. Но здесь вступает в силу проблема "Lost in the Middle" (Потеря в середине) и деградация Adherence (следования инструкциям). Чем длиннее CLAUDE.md, тем чаще агент будет игнорировать правила из его середины.

- Официальная рекомендация - не более 200 строк. В идеале - ужимать до 50-100. Каждое слово в этом файле должно иметь максимальную информационную плотность.

- Стоимость. Содержимое CLAUDE.md отправляется на API Anthropic при каждом шаге. Если ваш файл весит 5 000 токенов, а агент делает 10 шагов для решения задачи (поиск файла, чтение, написание кода, запуск тестов, исправление ошибки), вы тратите 50 000 токенов только на загрузку контекста. В масштабах корпоративной разработки это ведет к неоправданному сжиганию бюджета.

2. Формирование жесткого контракта проекта.

Чтобы уложиться в лимиты и заставить агента работать предсказуемо, CLAUDE.md должен строиться как Design by Contract (Проектирование по контракту). Мы задаем предусловия, инварианты и постусловия. Каждый этап должен сопровождаться конкретными требованиями.

3. Динамический контекст. Стратегия "Скрипт-Сборщик".

Поскольку CLAUDE.md жестко ограничен размером, мы не можем хранить там спецификации API, схемы БД или актуальные ADR. Здесь применяется паттерн Retrieval on Demand (RoD). Вы прописываете в CLAUDE.md указатель на скрипт (инструмент), а не сами данные. Пример: "Перед написанием интеграции с сервисом аутентификации, выполни bash ./scripts/get-latest-openapi.sh auth-service. Используй полученный JSON для генерации клиента".

Когда стоит использовать динамический сбор контекста?

- При высокой волатильности данных. Схема базы данных (которую могут поменять коллеги в соседней ветке), актуальные эндпоинты соседних микросервисов, открытые баг-репорты в Jira.

- Когда полная документация весит мегабайты, скрипт (например, использующий grep или векторный поиск) должен извлечь только ту часть, которая нужна агенту здесь и сейчас.

- Если ваш код зависит от контракта protobuf из другого репозитория, скрипт должен сходить в Git, скачать .proto файл и отдать его агенту.

Какие риски и ограничения при динамическом сборе контекста?

- Проблема зацикливания. Если скрипт падает с неочевидной ошибкой, агент может пытаться вызвать его снова и снова, сжигая токены. Для решения, скрипты должны возвращать понятные человекочитаемые ошибки (exit code + stderr), например: Error: Auth API is down. Stop task and notify user.

- Задержки. Если скрипт выполняется 30 секунд (например, компилирует соседний проект), агент будет простаивать, а UX вашей работы резко упадет. Решение - кеширование. Скрипт должен кешировать результат (например, Swagger JSON) локально и обновлять его не чаще, чем раз в час (если не передан флаг --force).

- Раздувание контекста. Если скрипт просто делает curl http://api/swagger.json и вываливает в консоль агента 50 000 строк, агент перегрузится и забудет ваши первоначальные инструкции. Решение - скрипты должны возвращать выжимку, либо сохранять результат в файл и возвращать агенту путь: Schema saved to /tmp/schema.json. Read only the necessary endpoints.

- Безопасность. Агент запускает скрипт с вашими правами. Если скрипт уязвим для инъекций (например, принимает аргументы от агента без санитизации), это можно использовать для атаки. Скрипты-сборщики должны быть строго Read-Only.

Пройдем немного глубже. Архитекторы решают проблему стоимости контекста с помощью двух основных инженерных практик:

1. Prompt Caching (Кеширование промптов). Это главный механизм экономии в современных LLM (включая Anthropic API, на котором работает Claude Code):

- Если начало вашего контекста (а это базовые системные инструкции + ваш CLAUDE.md) не меняется от запроса к запросу, серверы Anthropic кешируют эту часть графа вычислений.

- Вы платите за запись в кеш один раз (что стоит стандартно), но при каждом следующем шаге агента (чтение из кеша) стоимость токенов снижается на 90%, а скорость ответа вырастает в разы.

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

2. Context Routing (Контекстная маршрутизация). Вместо одного глобального CLAUDE.md на 5000 токенов, создается иерархия. Основной CLAUDE.md в корне репозитория весит 300 токенов (только самые критичные правила). А специфичные инструкции кладутся в подпапки (например, /src/main/java/com/bank/loan/CLAUDE.md). Агент платит за загрузку этих локальных правил только тогда, когда начинает работать с файлами в конкретной директории.

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

Паттерн 1: Task-Driven Context (Контекст под задачу). Например, если мы пишем фичу интеграции с Kafka, то не нужно пытаться запихнуть задачу в глобальные настройки. Согласно паттерну, применяем несколько этапов:

- Создай временный файл задачи, например docs/tasks/kafka-integration.md. Опиши там требования, куски старого кода(или пути до него) и желаемый результат.

- В терминале вызови агента с прямой ссылкой: claude "Прочитай задачу в docs/tasks/kafka-integration.md и начни реализацию".

- Агент прочитает базовые правила безопасности из CLAUDE.md, затем прочитает твой файл задачи, совместит их и начнет писать код. Файл задачи удаляется или уходит в архив после завершения.

Паттерн 2: Указатели на инструменты

- Под скрипты мы создаем отдельное хранилище (например, /.claude/scripts/ или /scripts/).

- Далее в CLAUDE.md оставляем указатели: "В репозитории есть набор скриптов в директории ./scripts/. Прежде чем менять схемы БД, всегда запускай ./scripts/fetch_db_schema.sh, чтобы получить актуальную структуру.".

Итого, CLAUDE.md - это узкое горлышко. Мы храним в нем только статические правила маршрутизации и безопасности (контракт). Всю динамическую, тяжеловесную логику (схемы, статусы, доступы) мы выносим в детерминированные bash-скрипты, вызываемые агентом по мере необходимости.

Безопасность и автоматизация (settings.json и Hooks). Управление правами агента, pre/post-скрипты, работа с переменными окружения.

На этом этапе мы даем понять агенту то, что он имеет право делать. К ИИ-агентам применяется тот же принцип, что и к любым другим микросервисам: Zero Trust (Нулевое доверие) и Минимизация радиуса поражения (Blast Radius).

settings.json и Управление правами (Permission Management)

Файл .claude/settings.json на уровне проекта кардинально отличается от CLAUDE.md. Если md-файл отправляется в нейросеть (в LLM), то settings.json читается только локальным клиентом (CLI). Нейросеть ничего о нем не знает. Этот файл хардкодит границы дозволенного для терминала.
Главной задачей в промышленной среде является настройка баланса между автономностью (чтобы агент не дергал вас подтверждением на каждую команду ls) и безопасностью (чтобы он случайно не дропнул базу).

Вы можете настроить CLI так, чтобы он автоматически одобрял безопасные Read-Only команды и требующие детерминированной проверки локальные тесты, но блокировал любые деструктивные действия или сетевые вызовы.

Пример для .claude/settings.json:

{
  "preferredModel": "claude-3-5-sonnet-20241022",
  "autoApprove": {
    "readFiles": true,
    "commands": [
      "ls", "cat", "grep", "find",
      "./mvnw clean test",
      "./mvnw checkstyle:check",
      "git status", "git diff"
    ]
  },
  "requireConfirmation": {
    "commands": [
      "git commit", "git push",
      "docker run", "docker stop",
      "npm install", "./mvnw install"
    ],
    "networkAccess": true
  }
}

Если агент загаллюцинирует и решит выполнить curl -X DELETE production-db.internal, CLI перехватит этот вызов на уровне песочницы терминала и заблокирует его, запросив ваше явное y/N.

Как мы уже обсуждали, мы никогда не коммитим секреты. Claude Code работает внутри вашей текущей bash/zsh сессии, а значит, наследует все ее переменные окружения. Агент не должен иметь долгоживущих ключей доступа. Вместо того чтобы просто писать claude в терминале, мы создаем shell-wrapper:

#!/bin/bash

echo "Запрашиваем временные токены из Vault..."
Получаем токен с TTL = 1 час
export DB_TEST_PASSWORD=(vault read -field=password secret/dev/db_test)
export JIRA_API_TOKEN=(vault read -field=token secret/dev/jira_agent_token)

Переопределяем базовый URL, если в компании весь AI-трафик идет через внутренний прокси/DLP-систему
export ANTHROPIC_BASE_URL="https://ai-gateway.corp.internal/v1"
echo "Запуск Claude Code..."

claude
echo "Очистка секретов из памяти..."

unset DB_TEST_PASSWORD

unset JIRA_API_TOKEN

Это гарантирует, что даже если агент случайно попытается залогировать свои переменные окружения (например, через команду env), после закрытия сессии секреты будут уничтожены, а их срок действия (TTL) в Vault истечет.

Pre/Post-Скрипты и Хуки (Автоматизация жизненного цикла)

Сам по себе Claude CLI не имеет встроенной системы триггеров вроде pre-prompt или post-generation на уровне конфигурации. Мы реализуем эту автоматизацию архитектурно, оборачивая сессию агента в хуки локального репозитория.

Pre-Hooks (Подготовка песочницы). Прежде чем агент начнет читать файлы и тратить токены, среда должна быть консистентной.

- Синхронизируем контракты. Скрипт скачивает свежие .proto файлы или Swagger-спецификации соседних микросервисов из artifactory.

- Сбрасываем состояние. Делаем чистку тестовой БД, чтобы агент не пытался чинить фантомные ошибки от предыдущих запусков.

- Реализуем это через тот же wrapper start-agent.sh или через Makefile (например, make claude-session, который выполняет make prepare-env перед запуском CLI).

Post-Hooks (Верификация и аудит). Нам не стоит доверять коду, написанному агентом, пока он не пройдет статический анализ.

- Локальный Git Pre-Commit Hook. Настраиваем .husky (или стандартный pre-commit в Git), который запускает линтеры (SonarLint, Checkstyle). Если агент пытается сделать коммит (и вы это одобряете), хук проверит код. Если код не проходит - коммит отбрасывается, а в терминал падает ошибка. Агент прочитает эту ошибку и сам пойдет исправлять свой код.

- DLP (Data Loss Prevention) сканирование. Post-hook может сканировать сгенерированный агентом диф (git diff) на наличие захардкоженных паролей с помощью инструментов вроде TruffleHog или TGitleaks до того, как это попадет в ревью к коллегам.

Дополнительно советую изучить следующие работы и стандарты:

Системное управление знаниями (Rules, Skills, Subagents). Как масштабировать инструкции для сложных микросервисов, не перегружая базовый контекст

Когда наша архитектура разрастается до сотен тысяч строк кода, со сложной доменной моделью и десятками интеграций, нужно искать другие варианты для работы с контекстом, так как один CLAUDE.md на 200 строк уже не подойдет. Нам нужно передать агенту знания о секьюрити-политиках, правилах работы с Kafka, гайдлайнах по написанию тестов и особенностях легаси-кода. Если загрузить всё это в базовый контекст, модель станет медленной и начнет галлюцинировать.

Существует паттерн инверсии контекста - мы не пушим знания в агента, мы даем ему навыки для самостоятельного извлечения знаний по мере необходимости.

В текущей статье рассмотрю три уровня масштабирования - Локальные правила, Навыки (скрипты/MCP) и Субагенты.

1. Rules (Локальные и доменные правила).

Вместо одного монолитного файла, мы строим дерево контекста. Claude Code (и аналогичные инструменты) умеет читать контекст иерархически. В корне лежит Конституция (базовые запреты), а специфика размазана по директориям. Агент платит токенами за эти правила, только если заходит в соответствующую папку.

Ниже оставлю простые примеры для наглядности:

- /CLAUDE.md - (Корень) «Пиши на Java 25. Не коммить секреты. Используй гексагональную архитектуру».

- /src/main/java/com/bank/loan/domain/CLAUDE.md - «В этом домене запрещено использовать сеттеры. Все сущности иммутабельны. Деньги считай через BigDecimal».

- /src/test/CLAUDE.md - «Используй Testcontainers для БД. Запрещено мокать транзакции, тестируй их на реальной базе».

В данном случае, например когда вы просите агента добавить логику расчета в домен займов, то он переходит в папку domain. Его системный промпт динамически собирается из корневого CLAUDE.md + доменного CLAUDE.md. Контекст остается узким и релевантным задаче.

2. Skills (Навыки и Инкапсуляция сложности).

Многие совершают частую ошибку, пытаясь описать текстом в CLAUDE.md объяснить агенту алгоритм действий. Следует инкапсулировать сложную логику в детерминированные инструменты (bash, python, ..) и предоставить их агенту как навыки.

Для экосистемы Claude (и Claude Code CLI) стандартом для масштабирования навыков стал MCP (Model Context Protocol). Это протокол с открытым исходным кодом от Anthropic, который позволяет подключать к агентам внешние источники данных и инструменты стандартизированным образом. Вместо того чтобы учить агента ходить в базу данных через bash, вы поднимаете локальный mcp-postgres-server.

Тем самым, вы даете агенту интерфейс, а не сами данные. Если ему нужно написать миграцию, он сам вызовет навык проверки схемы, получит ровно те 5 таблиц, которые ему нужны, и напишет код.

3. Subagents (Субагенты и Агентные Workflow).

Один инстанс LLM не может одинаково хорошо и глубоко держать в голове архитектуру, писать код и выступать строгим QA-инженером. Когда задача сложная, мы переходим к паттерну Оркестрации (Agentic Workflows).

Поскольку терминальный Claude Code - это единый процесс, мы эмулируем субагентов через скрипты-делегаты, которые обращаются к API LLM с узкоспециализированными промптами.

Жизненный цикл данных и аудит. Транскрипты, управление историей и очистка чувствительных данных

Большинство разработчиков и пользователей воспринимают ИИ-агента как умную консоль, забывая, что под капотом он работает как пылесос - собирает контекст, читает логи, анализирует переменные среды и сохраняет всё это, чтобы поддерживать иллюзию непрерывного диалога.
Неконтролируемое оседание таких данных на локальных машинах - это прямой путь к нарушению стандартов (PCI-DSS, ФЗ-152, GDPR) и критическим инцидентам безопасности.

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

Анатомия цифрового следа (Что и где сохраняется?)

По умолчанию Claude Code спроектирован для максимального удобства, поэтому он кэширует почти всё. Согласно официальной документации, в глобальной директории ~/.claude/ формируется целое хранилище данных приложения:

- Транскрипты сессий. Это самая опасная зона. Сюда в открытом виде пишется каждое сообщение, каждый вызов инструмента и, что критично, результаты работы инструментов. Если агент сделал cat production.log, весь лог с потенциальными конфиденциальными данными или токенами ляжет в этот файл.

- Слепки файлов (file-history/). Копии файлов кода до того, как агент их изменил (для функции отмены).

- История промптов (history.jsonl). Все ваши запросы, которые вы вводили в терминал.

- Кэш буфера обмена и изображений (paste-cache/, image-cache/).

Эти файлы никак не зашифрованы. Защита опирается исключительно на правах доступа ОС.

Практики управления жизненным циклом (Best Practices)

Уровень 1: Радикальный (Stateless Mode / Zero Retention)

Для работы с критическими системами (например, ядром процессинга) история чатов не нужна вовсе. Агент должен работать как эфемерная лямбда-функция. Реализуется следующим образом: перед запуском терминала мы экспортируем системную переменную export CLAUDE_CODE_SKIP_PROMPT_HISTORY=1. Это заставит инструмент работать исключительно в оперативной памяти. Никакие транскрипты и логи на диск не запишутся. Сессия закрылась - данные уничтожены.

Уровень 2: Управляемое устаревание (Aggressive Cleanup)

Если транскрипты нужны для отладки сложного многошагового агента, мы берем под контроль сборку мусора. По умолчанию файлы лежат 30 дней (параметр cleanupPeriodDays). В промышленной среде это слишком долго.

- Можем снизить срок жизни кэша до 1 дня.

- Либо включить принудительную очистку (Post-hooks). Внедрением команды claude project purge --yes в скрипты завершения работы. Эта команда точечно вычищает все транскрипты, авто-память и слепки для конкретного репозитория, не трогая глобальные настройки разработчика.

Уровень 3: Интеграция с SIEM и аудит (Shadow Logging)

Если речь идет о промышленных средах, то безопасникам не нужны ваши философские дискуссии с моделью о паттернах проектирования. Им нужен структурированный аудит-лог: кто, когда и какие скрипты запускал от имени агента.

- Поскольку мы оборачиваем запуск агента и вызов сложных команд в bash или MCP-серверы, мы настраиваем логирование именно на уровне этих инструментов, а не самого клиента Claude.

- Если агент вызывает наш скрипт scripts/db_migrate.sh, именно этот скрипт отправляет событие в корпоративный Splunk/ELK: [ALERT] AI Agent initiated migration on DB: loan_service_db.

Защита данных в транзите (Data in Transit & DLP)

Даже если мы отключили сохранение на диск, агент всё равно отправляет собранный контекст на серверы Anthropic (в LLM). Как гарантировать, что коммерческая тайна не улетит наружу?

Можем использовать паттерн AI Gateway (DLP Proxy). В зрелых энтерпрайз-архитектурах инженеры настраивают клиент (через переменные HTTP_PROXY или переопределение базового URL API) так, чтобы трафик шел не напрямую в интернет, а на внутренний шлюз компании.

- Агент формирует запрос (например, кусок кода с захардкоженным тестовым JWT-токеном).

- Запрос уходит на корпоративный AI Gateway.

- Встроенная система DLP (Data Loss Prevention, например, Microsoft Presidio или самописный NER-модуль) на лету сканирует JSON.

- Токен заменяется на REDACTED_CREDENTIAL, и только этот очищенный текст уходит в модель.

Мы верхнеуровнево разобрали все 5 слоев. Теперь давай посмотрим на итоговый профиль системы, которую проектируем:

- Топология. Глобальный конфиг обеспечивает комфорт разработчика, локальный .claude/ диктует правила репозитория.

- Контракт (CLAUDE.md). Жесткий, лаконичный (до 200 строк), сфокусированный на архитектурных запретах.

- Безопасность (settings.json). Запрет на деструктивные команды и сеть (requireConfirmation), проброс временных ключей из Vault через переменные окружения.

- Масштабирование (Skills/Subagents). Дробление логики на вложенные папки, использование MCP и bash-скриптов вместо длинных инструкций.

- Данные (Audit). Эфемерные сессии (SKIP_PROMPT_HISTORY), агрессивная зачистка (purge) и аудит через обертки инструментов.

Такая система становится прогнозируемым, безопасным и мощным промышленным инструментом.