Skip to content

profile-loading.md

Latest commit

 

History

History
149 lines (103 loc) · 17.2 KB

profile-loading.md

File metadata and controls

149 lines (103 loc) · 17.2 KB
Raw

Загрузка правил по профилям

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

Цель механики - держать стартовый контекст компактным (ядро ~3.5k токенов вместо ~40k), но в нужный момент догружать узкоспециализированные правила (стандарты кодирования, антипаттерны, MCP-справку, скиллы метаданных и т.д.).

Три слоя правил

Слой Где живет Когда грузится Состав
Auto-core .claude/rules/ При каждом старте сессии (платформенный механизм Claude Code) user_rules.md, typography.md + path-scoped правила форм
Профильные .claude/lib/ По активному профилю либо по подтверждению агентом-предложения project_rules.md, dev-standards-*.md, anti-patterns.md, mcp-tools.md, powershell-windows.md, sdd-integrations.md, 1c-metadata-manage.md, skills_instructions.md
Path-scoped .claude/rules/ с paths: [...] во frontmatter При открытии файла, попадающего под glob dev-standards-forms.md (**/Form.Module.bsl + **/Form.xml), form_module_rules.md, forms_events_add.md (**/Form.Module.bsl)

Профили - что это и где они

Профиль - именованный набор файлов из .claude/lib/ (и .claude/) под класс задач: «писать код», «делать ревью», «оптимизировать», «работать со структурой метаданных» и т.д.

Каталог профилей закоммичен в .claude/profiles.json. Сейчас доступны:

Профиль Назначение Что грузит
code Написание и правка BSL project_rules.md, dev-standards-core.md, dev-standards-architecture.md, mcp-tools.md
review Ревью модуля или PR code + anti-patterns.md
refactor Чистка и реструктуризация code + anti-patterns.md
metadata_management Структура конфигурации (объекты, формы, СКД, роли, расширения, ИБ, веб-публикация) 1c-metadata-manage.md, skills_instructions.md, dev-standards-core.md, mcp-tools.md
performance Оптимизация запросов и алгоритмов project_rules.md, dev-standards-core.md, anti-patterns.md, mcp-tools.md
shell PowerShell-скрипты под Windows, CI powershell-windows.md
full Все разом - для отладки/нестандартных кейсов все девять файлов

Состав и описание каждого профиля - единым источником истины - в profiles.json. Этот документ - справочный.

Доменные индексы вне профильной модели

Два файла играют роль доменных индексов и попадают в контекст не только через профиль, но и по ссылкам:

  • .claude/1c-metadata-manage.md - карта знаний по структуре метаданных (объекты, формы, СКД, MXL, роли, расширения, подсистемы, EPF/ERF, ИБ, веб-публикация). Таблица «домен → скилл», проектные правила, грабли.
  • .claude/skills_instructions.md - реестр всех 68 локальных скиллов с dispatch-таблицей. SSOT по скиллам.

Триггеры подгрузки:

Источник Кто грузит Когда
Профили metadata_management и full хук + агент авто, по активному профилю или после подтверждения предложения
Ссылки из CLAUDE.md, lib/project_rules.md, lib/mcp-tools.md, агентов сам агент ad-hoc, когда задача в любом профиле упирается в метаданные/скилл
Sub-agent metadata-manager подагент авто, через свой Required reading before task
Команда «добавь файл Y» в чате агент вручную по запросу юзера

На профилях code / review / refactor / performance / shell хук эти файлы не зачитывает - расчет на то, что агент сам перейдет по ссылке при первой метадатной/скилловой задаче. Это сознательно: на чистом BSL-кодинге держать в контексте 60+ скиллов и доменную карту - лишние токены.

Как агент узнает, какой профиль активен

Между «есть profiles.json» и «агент знает каталог» стоит SessionStart-хук .claude/hooks/session-start-load-profile.ps1.

Он зарегистрирован в .claude/settings.json на матчеры startup | resume | clear | compact и при каждом из них:

  1. Читает .claude/profiles.json (закоммичен, общий для всех).
  2. Читает .claude/profile.local.json (gitignored, локальный выбор разработчика; опционален).
  3. Формирует Markdown-манифест: полный каталог профилей + блок про активный профиль.
  4. Возвращает этот текст в hookSpecificOutput.additionalContext.

Платформа упаковывает содержимое в <system-reminder> и приклеивает к следующему user-turn'у. Агент видит каталог как часть своего входа; отдельный Read profiles.json ему не нужен.

Если активный профиль задан - агент обязан прочитать список файлов из profiles[active].files через Read до содержательного ответа на первый промпт. Read идемпотентен: если по контексту видно, что файлы уже зачитаны и не сжаты компактом, повторный Read пропускается.

Если активный профиль не задан или невалиден - агент анализирует первый промпт и предлагает 1-3 ранжированных профиля (если в промпте есть тематические маркеры) или весь каталог (если маркеров нет). Read и кодовая работа - только после подтверждения юзером. Эвристика ранжирования - в .claude/rules/user_rules.md, раздел «Эвристика ранжирования профиля».

Как переключить профиль постоянно

«Постоянно» = до следующего ручного переключения. Имеется в виду - для всех новых сессий Claude Code в этом репо.

  1. Скопировать .claude/profile.local.json.example в .claude/profile.local.json (если еще не сделано).

  2. Указать нужный профиль:

    { "active": "code" }

  3. В уже открытой сессии - выполнить /clear (или открыть новую сессию). Хук на матчер clear инжектит обновленный манифест с новой меткой active.

profile.local.json лежит в .gitignore - каждый разработчик настраивает себе сам.

Чтобы вообще не иметь активного профиля по умолчанию (и каждый раз получать предложение от агента под задачу) - удалить файл или поставить "active": null.

Команды управления загрузкой в чате (без /clear)

В рамках одного чата состояние профиля можно менять подачей естественно-языковых команд. Эти команды живут в state текущего чата до /clear / /compact / закрытия сессии - profile.local.json они не трогают.

Команда Что делает
«загрузи профиль X» / «переключи на профиль X» Read всех файлов из profiles[X].files. Активным в state становится X
«добавь файл Y» / «подгрузи Y» Read одного файла, добавление к текущему набору
«переключи на core only» / «забудь профиль» В state помечается, что профиля больше нет; уже зачитанные файлы остаются в истории чата (Read необратим), но агент перестает на них опираться
«какие правила сейчас активны» Список: auto-core (всегда), активный профиль, дополнительно подгруженные файлы

Для постоянного переключения после такой команды агент напоминает: «отредактируй .claude/profile.local.json и сделай /clear». Сам файл хук на лету не правит - это требует ручного действия.

Что происходит на /compact и /resume

  • /compact - платформа сжимает историю чата. Хук срабатывает заново на матчер compact, инжектит свежий манифест. Если в сжатой истории детали зачитанных файлов потерялись - агент делает Re-Read; если сохранились - пропускает.
  • claude --resume (CLI) - хук срабатывает на матчер resume, инжектит каталог. Если по контексту видно, что файлы уже Read'нуты до /exit и не были сжаты - повторный Read не нужен.
  • /clear - полная очистка истории, хук срабатывает на матчер clear. Здесь Re-Read нужен всегда (история пустая).

Как добавить новый профиль

  1. Открыть .claude/profiles.json, добавить запись:

    "my_profile": {
  "_description": "Краткое описание под какие задачи. Это видит агент в манифесте каталога.",
  "files": [
    ".claude/lib/foo.md",
    ".claude/lib/bar.md"
  ]
}

  2. Если в составе ссылается на новые файлы - создать их в .claude/lib/ (для общих правил) или .claude/ (для индексов вроде skills_instructions.md).

  3. По желанию - добавить ключевые слова в эвристику ранжирования в .claude/rules/user_rules.md.

  4. Локально переключиться: .claude/profile.local.json → {"active": "my_profile"} → /clear.

Закомичивать стоит изменения profiles.json, файлы в lib/, обновление user_rules.md и эту документацию. profile.local.json оставлять локальным.

Под капотом: что важно знать

  • Хук - Windows-only. Скрипт написан на PowerShell 5.1 и предполагает наличие powershell.exe в PATH. На macOS/Linux Claude Code просто не запустит команду из settings.json - хук тихо отвалится (никакого additionalContext не приедет, агент получит обычный старт без манифеста профилей и будет вынужден разбираться с правилами вручную). Если репозиторий уйдет на не-Windows платформу, нужен либо bash-двойник скрипта + платформенная развилка в settings.json, либо переписать хук на Python (есть в Claude Code как опция).
  • PowerShell 5.1 и BOM. Хук пишет stdout строго UTF-8 без BOM (через [Console]::OutputEncoding) и читает входные JSON-файлы через [System.IO.File]::ReadAllText с явным UTF8Encoding($false). Стандартные Out-File/Set-Content -Encoding UTF8 в WinPS добавляют BOM и ломают как JSON-контракт хука, так и кириллицу в profiles.json.
  • Лимит на размер additionalContext. Платформа режет вставку на ~10000 символов. Хук заранее переключается на компактный формат каталога, если полный манифест превышает 9000 символов.
  • Settings watcher VSCode. Расширение Claude Code отслеживает только те директории, где settings.json существовал на момент старта. Если только что добавили .claude/settings.json в репо - нужен полный рестарт VSCode, простого /clear или открытия новой вкладки чата недостаточно.
  • Sub-agents не наследуют контекст профиля. Каждый дочерний агент стартует со своим минимальным контекстом и обязан сам Read'ать нужные ему правила. Поэтому в .claude/agents/*.md есть секция «Required reading before task» с явным списком файлов.
  • Read необратим в рамках сессии. Команда «забудь профиль» убирает опору на файлы, но токены уже потрачены. Поэтому ставка на правильное определение профиля - сначала, не по ходу.

Куда смотреть, если что-то пошло не так

Симптом Куда копать
Хук не срабатывает (нет манифеста в первом ответе) .claude/settings.json - корректность блока hooks.SessionStart. Полный рестарт VSCode после изменений в settings.json
profiles.json не парсится / кириллица в крякозябрах Проверить кодировку файла (UTF-8 без BOM); пересохранить через [System.IO.File]::WriteAllText
Агент предлагает не те профили Эвристика в user_rules.md - добавить/уточнить ключевые слова
Активный профиль игнорируется Имя в profile.local.json должно совпадать с ключом в profiles.json (case-sensitive)
После /compact агент «забыл» правила Норма: ждать первого ответа, агент сам решит, нужен ли Re-Read; либо явно сказать «перечитай профиль»

Связанные документы