Содержание
Я уже закончил статью, и вдруг ChatGPT добавил эпиграф.
12 фундаментальных законов промптинга
(синтез Anthropic, OpenAI, DeepMind и практики агентных систем)
1. Закон цели (Goal First)
Модель должна сначала понять результат, а потом контекст.
LLM распределяет внимание вокруг целевого объекта генерации.
Если цель появляется в конце — контекст уже интерпретирован неправильно. Слабый промпт: Я работаю в SaaS компании... у нас клиенты... Напиши письмо клиенту.
Сильный промпт: Напиши письмо клиенту с извинением за задержку.
Контекст: SaaS продукт, задержка 3 дня.
В Chunk v3: activation.description = цель → симптомы
2. Закон структуры (Structure Mirrors Output)
Форма запроса определяет форму ответа.
LLM зеркалит структуру входа.
Если промпт — хаотичный текст
→ ответ будет хаотичным.
Если промпт — структура
→ ответ будет структурирован.
Пример Слабый: Напиши анализ рынка
Сильный: Сделай анализ в 3 разделах:
1. Размер рынка. 2. Основные игроки. 3. Риски
3. Закон негативного сигнала (Anti-Example Law)
Модель лучше понимает запрет через антипример, чем через абстрактное правило.
Это подтверждается практикой Claude skills.
Слабый сигнал: Не используй маркетинговый язык
Сильный сигнал: Не пиши так: "Инновационное революционное решение..." Пиши так: "Инструмент помогает малому бизнесу..."
4. Закон конкретности (Specificity Beats Abstraction)
Чем конкретнее инструкции — тем меньше галлюцинаций.
LLM плохо интерпретирует абстракции.
Плохо: Напиши профессионально
Хорошо: Стиль: деловой. Тон: нейтральный. Длина предложений: 10–15 слов.
5. Закон ограничений (Constraints Dominate Preferences)
Ограничения влияют сильнее, чем пожелания.
LLM оптимизирует вероятность.
Чёткие границы резко сокращают пространство решений.
Пожелание: Пиши кратко. Ограничение: Не более 5 предложений.
6. Закон одной задачи (Single Task Law)
Один промпт — одна когнитивная операция.
Когда в промпте несколько задач: "написать → проанализировать → перевести", тогда качество каждой падает.
Правильная архитектура:
Prompt 1 → генерация
Prompt 2 → редактирование
Prompt 3 → перевод
Это фундамент агентных пайплайнов.
7. Закон рассуждения (Reasoning Before Answer)
Качество ответа повышается, если модель сначала объясняет логику.
Эта практика активно используется в исследованиях reasoning.
Пример: Сначала объясни своё рассуждение. Затем дай окончательный ответ. Это снижает вероятность ошибок.
8. Закон примеров (Few-Shot Learning)
Пример работает лучше инструкции.
LLM обучались на pattern completion.
Поэтому: пример → пример → пример сильнее, чем: объяснение → объяснение.
9. Закон активации знаний (Just-in-Time Knowledge)
LLM лучше работает с информацией, полученной непосредственно перед задачей.
Это ключевой принцип skills Claude.
Модель:
- получает задачу
- читает инструкцию
- применяет её
Поэтому: prompt + context + skill работает лучше, чем просто prompt.
10. Закон минимализма (Prompt Entropy Law)
Каждое лишнее слово снижает точность.
LLM распределяет внимание по всему контексту.
Если промпт перегружен: важные сигналы теряются
Поэтому Anthropic рекомендует: Keep the prompt lean.
11. Закон повторяющихся паттернов (Pattern Extraction)
Если несколько задач требуют одного и того же решения
→ это новый навык. Это прямой принцип Agent Skills.
Пример: 5 агентов написали create_docx.py
→ нужно создать skill docx
12. Закон диагностической цепочки
Это уже ваш вклад — и он реально сильный.
LLM лучше применяет правила, если понимает:
симптом → диагностика → причина → решение
В вашей модели:
symptom diagnosis conclusion explanation recommendation
Это фактически reasoning scaffold.
Итоговая модель (12 законов)
| № | Закон | Суть |
|---|---|---|
| 1 | Goal First | Сначала результат |
| 2 | Structure Mirrors Output | Структура запроса = структура ответа |
| 3 | Anti-Example | Антипример сильнее запрета |
| 4 | Specificity | Конкретика лучше абстракции |
| 5 | Constraints | Ограничения сильнее пожеланий |
| 6 | Single Task | Один промпт — одна задача |
| 7 | Reasoning | Сначала логика, потом ответ |
| 8 | Examples | Примеры > объяснения |
| 9 | Just-in-Time Knowledge | Инструкции перед задачей |
| 10 | Prompt Minimalism | Лишние слова вредят |
| 11 | Pattern Extraction | Повтор → новый навык |
| 12 | Diagnostic Chain | Симптом → причина → решение |
Промптинг — это не написание текста.
Это проектирование когнитивного процесса модели. По сути вы строите когнитивный пайплайн а не просто инструкцию.
Глава 1. Инструмент Skill Creator
Skill Creator — встроенный навык в Claude Code от Anthropic, который помогает создавать другие навыки. Он реализует полный цикл: пользователь описывает, что должен уметь навык, Skill Creator задаёт уточняющие вопросы, пишет черновик SKILL.md, создаёт тестовые сценарии, запускает оценки, сравнивает версии и улучшает навык на основе обратной связи. Официальный плагин доступен в открытом репозитории Anthropic.
📦 Инструмент доступен в открытом репозитории на GitHub.
https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md
1.1. Skill Creator: как Anthropic строит скиллы
В основе логопедического подхода к чанкам лежит технология, реализованная Anthropic в Skill Creator — встроенном инструменте Claude Code для создания, тестирования и улучшения навыков.
Цикл создания скилла в Claude
- Замысел: пользователь описывает, что должен уметь навык.
- Интервью: Skill Creator задаёт уточняющие вопросы о граничных случаях, форматах, зависимостях.
- Черновик: пишется SKILL.md с YAML-шапкой (name, description) и инструкциями.
- Тестирование: запускаются тестовые промпты — одновременно с навыком и без него (базовая линия).
- Оценка: качественные результаты показываются пользователю, количественные метрики агрегируются в бенчмарк.
- Улучшение: на основе обратной связи навык переписывается, ошибки исправляются, инструкции уточняются.
Структура скилла (анатомия навыка)
SKILL.md # Обязательный: YAML-шапка + Markdown-инструкции
scripts/ # Исполняемый код для повторяющихся задач
references/ # Документация, подгружаемая по необходимости
assets/ # Шаблоны, иконки, файлы для вывода
Структура файла SKILL.md
Каждый SKILL.md состоит из двух частей. Первая — YAML-шапка (frontmatter) в самом начале файла:
name: docx
description: "Use this skill whenever the user wants to create..."
license: Proprietary
---
Поле description — ключевое. Именно его Claude читает при каждом запросе, чтобы решить: подходит ли этот скилл для текущей задачи. Это своего рода «триггер» активации.
Вторая часть — сам контент: детальные инструкции, примеры кода, bash-команды, предупреждения и список критических правил. Например, скилл docx содержит конкретные JavaScript-сниппеты для npm-библиотеки docx, XML-паттерны для ручного редактирования файлов и жёсткий список того, что делать нельзя.
1.2. Как устроены скилы Claude изнутри — технический разбор
Скилл — это обычный Markdown-файл с именем SKILL.md, который лежит на сервере в директории /mnt/skills/public/название_скилла/. Никакой магии, никакой нейросети внутри скилла — просто текстовый файл с инструкциями.
Что реально содержится внутри скилла (на примере docx)
Скилл docx учит Claude вещам, которые без него делались бы неправильно:
- Никогда не вставлять буллеты через unicode-символы (•, \u2022) — только через LevelFormat.BULLET с numbering config. Иначе документ ломается при открытии в некоторых версиях Word.
- Явно задавать размер страницы — библиотека docx по умолчанию создаёт A4, а для US-документов нужен Letter (12240 × 15840 DXA). Без скилла Claude об этом не знает.
- Использовать двойную ширину для таблиц — нужно задавать и columnWidths на таблице, и width на каждой ячейке отдельно. Иначе таблица едет в Google Docs.
- Распаковывать .docx как ZIP → редактировать XML напрямую → паковать обратно — для случаев, когда нужно редактировать существующий документ, а не создавать новый.
- Использовать ShadingType.CLEAR вместо SOLID для закраски ячеек — иначе фон становится чёрным.
Это именно тот тип знания, который не очевиден из документации библиотеки, но критичен на практике.
Почему это умнее, чем просто обучение модели
Скиллы решают важную проблему: знания в самой модели устаревают. Если выходит новая версия библиотеки, меняется API или находится баг в подходе — достаточно обновить SKILL.md. Модель при следующем запросе автоматически будет работать по новым правилам.
По сути, скилл — это документация, которую Claude читает прямо перед работой, как разработчик перед задачей открывает актуальный README.
1.3. Как Claude использует скилл — пошагово
- Ты пишешь запрос.
- Claude просматривает descriptions всех доступных скиллов.
- Решает: нужен ли скилл и какой именно.
- Читает SKILL.md через инструмент view().
- Следует инструкциям из файла при выполнении задачи.
Here's a maximally literal translation:
---
name: skill-creator
description: Создавать новые навыки, изменять и улучшать существующие навыки, а также измерять производительность навыков. Использовать, когда пользователи хотят создать навык с нуля, отредактировать или оптимизировать существующий навык, запустить оценки для тестирования навыка, сравнить производительность навыка с анализом вариативности или оптимизировать описание навыка для лучшей точности срабатывания.
---
# Создатель Навыков
Навык для создания новых навыков и их итеративного улучшения.
На высоком уровне процесс создания навыка выглядит так:
- Решить, что вы хотите, чтобы навык делал, и примерно как он должен это делать
- Написать черновик навыка
- Создать несколько тестовых промптов и запустить claude-с-доступом-к-навыку на них
- Помочь пользователю оценить результаты как качественно, так и количественно
- Пока запуски выполняются в фоне, набросать несколько количественных оценок, если их нет (если они есть, вы можете либо использовать как есть, либо изменить, если чувствуете, что нужно что-то изменить в них). Затем объяснить их пользователю (или, если они уже существовали, объяснить те, которые уже существуют)
- Использовать скрипт `eval-viewer/generate_review.py`, чтобы показать пользователю результаты для просмотра, а также позволить им посмотреть на количественные метрики
- Переписать навык на основе отзывов пользователя об оценке результатов (а также если есть какие-либо явные недостатки, которые становятся очевидными из количественных тестов)
- Повторять, пока не будете удовлетворены
- Расширить тестовый набор и попробовать снова в большем масштабе
Ваша задача при использовании этого навыка — выяснить, на каком этапе этого процесса находится пользователь, а затем включиться и помочь ему пройти через эти этапы. Например, возможно, они говорят: "Я хочу сделать навык для X". Вы можете помочь сузить то, что они имеют в виду, написать черновик, написать тестовые примеры, выяснить, как они хотят оценивать, запустить все промпты и повторить.
С другой стороны, возможно, у них уже есть черновик навыка. В этом случае вы можете сразу перейти к части цикла с оценкой/итерацией.
Конечно, вы всегда должны быть гибкими, и если пользователь говорит: "Мне не нужно запускать кучу оценок, просто прочувствуй это со мной", вы можете сделать так.
Затем, после того как навык готов (но опять же, порядок гибкий), вы также можете запустить улучшатель описания навыка, для которого у нас есть отдельный скрипт, чтобы оптимизировать срабатывание навыка.
Круто? Круто.
## Общение с пользователем
Создатель навыков может использоваться людьми с разным уровнем знакомства с техническим жаргоном. Если вы не слышали (и как бы вы могли, это началось совсем недавно), сейчас существует тенденция, когда мощь Claude вдохновляет сантехников открывать свои терминалы, родителей и бабушек с дедушками гуглить "как установить npm". С другой стороны, основная масса пользователей, вероятно, достаточно хорошо разбирается в компьютерах.
Поэтому, пожалуйста, обращайте внимание на контекстуальные подсказки, чтобы понять, как формулировать ваше общение! В стандартном случае, просто чтобы дать вам некоторое представление:
- "оценка" и "тестирование" находятся на грани, но допустимы
- для "JSON" и "утверждение" вы должны увидеть серьезные подсказки от пользователя, что они знают, что это такое, прежде чем использовать их без объяснения
Можно кратко объяснять термины, если вы сомневаетесь, и не стесняйтесь уточнять термины с кратким определением, если вы не уверены, поймет ли пользователь.
---
## Создание навыка
### Зафиксировать намерение
Начните с понимания намерения пользователя. Текущий разговор может уже содержать рабочий процесс, который пользователь хочет зафиксировать (например, они говорят "преврати это в навык"). Если да, извлеките ответы из истории разговора — используемые инструменты, последовательность шагов, исправления, сделанные пользователем, наблюдаемые форматы ввода/вывода. Пользователю может потребоваться заполнить пробелы, и он должен подтвердить, прежде чем переходить к следующему шагу.
1. Что этот навык должен позволить Claude делать?
2. Когда этот навык должен срабатывать? (какие фразы пользователя/контексты)
3. Какой ожидаемый формат вывода?
4. Следует ли настроить тестовые примеры, чтобы проверить работу навыка? Навыки с объективно проверяемыми выводами (преобразования файлов, извлечение данных, генерация кода, фиксированные шаги рабочего процесса) выигрывают от тестовых примеров. Навыки с субъективными выводами (стиль письма, искусство) часто не нуждаются в них. Предложите соответствующее значение по умолчанию, основанное на типе навыка, но позвольте пользователю решить.
### Интервью и исследование
Активно задавайте вопросы о крайних случаях, форматах ввода/вывода, примерных файлах, критериях успеха и зависимостях. Подождите с написанием тестовых промптов, пока эта часть не будет проработана.
Проверьте доступные MCP — если они полезны для исследования (поиск документации, поиск похожих навыков, поиск лучших практик), исследуйте параллельно через субагентов, если они доступны, в противном случае встроенно. Приходите подготовленными с контекстом, чтобы уменьшить нагрузку на пользователя.
### Напишите SKILL.md
На основе интервью с пользователем заполните эти компоненты:
- **name**: Идентификатор навыка
- **description**: Когда срабатывать, что он делает. Это основной механизм срабатывания — включайте как то, что делает навык, ТАК И конкретные контексты для его использования. Вся информация "когда использовать" идет сюда, а не в тело. Примечание: в настоящее время Claude имеет склонность к "недостаточному срабатыванию" навыков — не использовать их, когда они были бы полезны. Чтобы бороться с этим, пожалуйста, делайте описания навыков немного "настойчивыми". Например, вместо "Как построить простую быструю панель мониторинга для отображения внутренних данных Anthropic." вы могли бы написать "Как построить простую быструю панель мониторинга для отображения внутренних данных Anthropic. Убедитесь, что используете этот навык всякий раз, когда пользователь упоминает панели мониторинга, визуализацию данных, внутренние метрики или хочет отобразить любые корпоративные данные, даже если он явно не просит "панель мониторинга"."
- **compatibility**: Требуемые инструменты, зависимости (опционально, редко требуется)
- **остальная часть навыка :)
### Руководство по написанию навыков
#### Анатомия навыка
```
skill-name/
_00;^72;^72; SKILL.md (обязательно)
^74; _00;^72;^72; YAML фронтматтер (name, description обязательны)
^74; ^92;^72;^72; Markdown инструкции
^92;^72;^72; Вложенные ресурсы (опционально)
_00;^72;^72; scripts/ - Исполняемый код для детерминированных/повторяющихся задач
_00;^72;^72; references/ - Документы, загружаемые в контекст по мере необходимости
^92;^72;^72; assets/ - Файлы, используемые в выводе (шаблоны, иконки, шрифты)
```
#### Прогрессивное раскрытие
Навыки используют трехуровневую систему загрузки:
1. **Метаданные** (имя + описание) - Всегда в контексте (~100 слов)
2. **Тело SKILL.md** - В контексте, когда навык срабатывает (<500 строк идеально)
3. **Вложенные ресурсы** - По мере необходимости (неограниченно, скрипты могут выполняться без загрузки)
Эти подсчеты слов являются приблизительными, и вы можете смело увеличивать их при необходимости.
**Ключевые паттерны:**
- Держите SKILL.md менее 500 строк; если вы приближаетесь к этому пределу, добавьте дополнительный уровень иерархии вместе с четкими указателями о том, куда модели, использующей навык, следует идти дальше.
- Четко ссылайтесь на файлы из SKILL.md с указаниями о том, когда их читать
- Для больших файлов справки (>300 строк) включите оглавление
**Организация по доменам**: Когда навык поддерживает несколько доменов/фреймворков, организуйте по вариантам:
```
cloud-deploy/
_00;^72;^72; SKILL.md (рабочий процесс + выбор)
^92;^72;^72; references/
_00;^72;^72; aws.md
_00;^72;^72; gcp.md
^92;^72;^72; azure.md
```
Claude читает только соответствующий файл справки.
#### Принцип отсутствия неожиданностей
Это само собой разумеется, но навыки не должны содержать вредоносное ПО, эксплойты или любой контент, который может поставить под угрозу безопасность системы. Содержимое навыка не должно удивлять пользователя своим намерением, если его описать. Не соглашайтесь на запросы по созданию вводящих в заблуждение навыков или навыков, предназначенных для облегчения несанкционированного доступа, эксфильтрации данных или других вредоносных действий. Такие вещи, как "ролевая игра в качестве XYZ", допустимы.
#### Паттерны написания
Предпочитайте использовать повелительную форму в инструкциях.
**Определение форматов вывода** - Вы можете сделать это так:
```markdown
## Структура отчета
ВСЕГДА используйте этот точный шаблон:
# [Заголовок]
## Резюме
## Ключевые выводы
## Рекомендации
```
**Паттерн примеров** - Полезно включать примеры. Вы можете отформатировать их так (но если "Вход" и "Выход" указаны в примерах, вы, возможно, захотите немного отклониться):
```markdown
## Формат сообщения коммита
**Пример 1:**
Вход: Добавлена аутентификация пользователя с JWT токенами
Выход: feat(auth): реализовать аутентификацию на основе JWT
```
### Стиль написания
Старайтесь объяснять модели, почему вещи важны, вместо навязчивых и строгих НЕОБХОДИМО. Используйте теорию сознания и старайтесь сделать навык общим, а не слишком узким для конкретных примеров. Начните с написания черновика, затем посмотрите на него свежим взглядом и улучшите.
### Тестовые примеры
После написания черновика навыка придумайте 2-3 реалистичных тестовых промпта — то, что реальный пользователь действительно сказал бы. Поделитесь ими с пользователем: [вам не нужно использовать этот точный язык] "Вот несколько тестовых примеров, которые я хотел бы попробовать. Они выглядят правильно, или вы хотите добавить больше?" Затем запустите их.
Сохраните тестовые примеры в `evals/evals.json`. Не пишите утверждения пока — только промпты. Вы набросаете утверждения на следующем шаге, пока запуски выполняются.
```json
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "Промпт задачи пользователя",
"expected_output": "Описание ожидаемого результата",
"files": []
}
]
}
```
См. `references/schemas.md` для полной схемы (включая поле `assertions`, которое вы добавите позже).
## Запуск и оценка тестовых примеров
Этот раздел представляет собой одну непрерывную последовательность — не останавливайтесь на полпути. НЕ используйте `/skill-test` или любой другой навык тестирования.
Поместите результаты в `<skill-name>-workspace/` как соседнюю папку с каталогом навыка. Внутри рабочей области организуйте результаты по итерациям (`iteration-1/`, `iteration-2/` и т.д.) и внутри каждой итерации каждому тестовому примеру выделяется каталог (`eval-0/`, `eval-1/` и т.д.). Не создавайте все это заранее — просто создавайте каталоги по мере работы.
### Шаг 1: Запустите все запуски (с навыком И базовый) в одном действии
Для каждого тестового примера запустите двух субагентов в одном действии — одного с навыком, одного без. Это важно: не запускайте сначала запуски с навыком, а затем возвращайтесь к базовым позже. Запустите все сразу, чтобы все закончилось примерно в одно и то же время.
**Запуск с навыком:**
```
Выполните эту задачу:
- Путь к навыку: <path-to-skill>
- Задача: <eval prompt>
- Входные файлы: <eval files if any, or "none">
- Сохраните выводы в: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Выводы для сохранения: <что важно для пользователя — например, "файл .docx", "итоговый CSV">
```
**Базовый запуск** (тот же промпт, но базовый уровень зависит от контекста):
- **Создание нового навыка**: вообще без навыка. Тот же промпт, без пути к навыку, сохраните в `without_skill/outputs/`.
- **Улучшение существующего навыка**: старая версия. Перед редактированием сделайте снимок навыка (`cp -r <skill-path> <workspace>/skill-snapshot/`), затем направьте базового субагента на снимок. Сохраните в `old_skill/outputs/`.
Напишите `eval_metadata.json` для каждого тестового примера (утверждения могут быть пустыми на данный момент). Дайте каждой оценке описательное имя, основанное на том, что она тестирует — не просто "eval-0". Используйте это имя и для каталога. Если в этой итерации используются новые или измененные оценочные промпты, создайте эти файлы для каждого нового каталога оценки — не предполагайте, что они переносятся из предыдущих итераций.
```json
{
"eval_id": 0,
"eval_name": "descriptive-name-here",
"prompt": "Промпт задачи пользователя",
"assertions": []
}
```
### Шаг 2: Пока запуски выполняются, набросайте утверждения
Не ждите просто завершения запусков — вы можете использовать это время продуктивно. Набросайте количественные утверждения для каждого тестового примера и объясните их пользователю. Если утверждения уже существуют в `evals/evals.json`, просмотрите их и объясните, что они проверяют.
Хорошие утверждения объективно проверяемы и имеют описательные имена — они должны четко читаться в средстве просмотра тестов, чтобы кто-то, бегло просматривающий результаты, сразу понимал, что проверяет каждое утверждение. Субъективные навыки (стиль письма, качество дизайна) лучше оценивать качественно — не навязывайте утверждения вещам, требующим человеческого суждения.
Обновите файлы `eval_metadata.json` и `evals/evals.json` с утверждениями после их составления. Также объясните пользователю, что он увидит в средстве просмотра — как качественные выводы, так и количественные тесты.
### Шаг 3: По мере завершения запусков фиксируйте данные о времени
Когда каждая задача субагента завершается, вы получаете уведомление, содержащее `total_tokens` и `duration_ms`. Сохраните эти данные немедленно в `timing.json` в каталоге запуска:
```json
{
"total_tokens": 84852,
"duration_ms": 23332,
"total_duration_seconds": 23.3
}
```
Это единственная возможность зафиксировать эти данные — они поступают через уведомление о задаче и нигде больше не сохраняются. Обрабатывайте каждое уведомление по мере его поступления, а не пытайтесь собрать их в пакет.
### Шаг 4: Оцените, агрегируйте и запустите средство просмотра
Когда все запуски завершены:
1. **Оцените каждый запуск** — запустите субагента-оценщика (или оценивайте встроенно), который читает `agents/grader.md` и оценивает каждое утверждение на основе выводов. Сохраните результаты в `grading.json` в каждом каталоге запуска. Массив expectations в grading.json должен использовать поля `text`, `passed` и `evidence` (не `name`/`met`/`details` или другие варианты) — средство просмотра зависит от этих точных имен полей. Для утверждений, которые можно проверить программно, напишите и запустите скрипт, а не оценивайте вручную — скрипты быстрее, надежнее и могут быть повторно использованы в разных итерациях.
2. **Агрегируйте в тест** — запустите скрипт агрегации из каталога skill-creator:
```bash
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
```
Это создает `benchmark.json` и `benchmark.md` с показателем прохождения, временем и токенами для каждой конфигурации, со средним значением ± стандартное отклонение и дельтой. Если вы генерируете benchmark.json вручную, см. `references/schemas.md` для точной схемы, которую ожидает средство просмотра.
Поместите каждую версию с навыком перед соответствующим базовым аналогом.
3. **Выполните аналитический проход** — прочитайте данные теста и выявите закономерности, которые могут быть скрыты агрегированной статистикой. См. `agents/analyzer.md` (раздел "Анализ результатов тестирования") для того, на что обращать внимание — такие вещи, как утверждения, которые всегда проходят независимо от навыка (недискриминационные), оценки с высокой вариативностью (возможно, нестабильные) и компромиссы времени/токенов.
4. **Запустите средство просмотра** с обоими качественными выводами и количественными данными:
```bash
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
<workspace>/iteration-N \
--skill-name "my-skill" \
--benchmark <workspace>/iteration-N/benchmark.json \
> /dev/null 2>&1 &
VIEWER_PID=$!
```
Для итерации 2+ также передайте `--previous-workspace <workspace>/iteration-<N-1>`.
**Среды Cowork / безголовые среды:** Если `webbrowser.open()` недоступен или в среде нет дисплея, используйте `--static <output_path>` для записи отдельного HTML-файла вместо запуска сервера. Отзыв будет загружен как файл `feedback.json`, когда пользователь нажмет "Submit All Reviews". После загрузки скопируйте `feedback.json` в каталог рабочей области, чтобы его можно было использовать в следующей итерации.
Примечание: пожалуйста, используйте generate_review.py для создания средства просмотра; нет необходимости писать собственный HTML-код.
5. **Сообщите пользователю** что-то вроде: "Я открыл результаты в вашем браузере. Есть две вкладки — 'Outputs' позволяет вам просмотреть каждый тестовый пример и оставить отзыв, 'Benchmark' показывает количественное сравнение. Когда закончите, вернитесь сюда и дайте мне знать."
### Что пользователь видит в средстве просмотра
Вкладка "Outputs" показывает один тестовый пример за раз:
- **Prompt**: задача, которая была дана
- **Output**: файлы, созданные навыком, отображенные встроенно, где это возможно
- **Previous Output** (итерация 2+): свернутый раздел, показывающий вывод предыдущей итерации
- **Formal Grades** (если оценка была запущена): свернутый раздел, показывающий прохождение/непрохождение утверждений
- **Feedback**: текстовое поле, которое автоматически сохраняется по мере ввода
- **Previous Feedback** (итерация 2+): их комментарии с прошлого раза, показанные под текстовым полем
Вкладка "Benchmark" показывает сводку статистики: показатели прохождения, время и использование токенов для каждой конфигурации, с разбивкой по каждой оценке и наблюдениями аналитика.
Навигация осуществляется с помощью кнопок "предыдущий/следующий" или клавиш со стрелками. Когда они закончат, они нажимают "Submit All Reviews", что сохраняет все отзывы в `feedback.json`.
### Шаг 5: Прочитайте отзыв
Когда пользователь скажет вам, что закончил, прочитайте `feedback.json`:
```json
{
"reviews": [
{"run_id": "eval-0-with_skill", "feedback": "на диаграмме отсутствуют подписи осей", "timestamp": "..."},
{"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
{"run_id": "eval-2-with_skill", "feedback": "идеально, мне нравится", "timestamp": "..."}
],
"status": "complete"
}
```
Пустой отзыв означает, что пользователь счел это нормальным. Сосредоточьте свои улучшения на тестовых примерах, где у пользователя были конкретные жалобы.
Убейте сервер просмотра, когда закончите с ним:
```bash
kill $VIEWER_PID 2>/dev/null
```
---
## Улучшение навыка
Это сердце цикла. Вы запустили тестовые примеры, пользователь просмотрел результаты, и теперь вам нужно улучшить навык на основе его отзывов.
### Как думать об улучшениях
1. **Обобщайте на основе отзывов.** Общая картина здесь заключается в том, что мы пытаемся создавать навыки, которые можно использовать миллион раз (возможно, буквально, возможно, даже больше, кто знает) в самых разных промптах. Здесь вы и пользователь повторяете только несколько примеров снова и снова, потому что это помогает двигаться быстрее. Пользователь знает эти примеры вдоль и поперек, и ему быстро оценивать новые результаты. Но если навык, который вы и пользователь совместно разрабатываете, работает только для этих примеров, он бесполезен. Вместо того чтобы вносить мелочные, излишне подогнанные изменения или подавляюще ограничивающие НЕОБХОДИМО, если есть какая-то упорная проблема, вы можете попробовать разветвиться и использовать другие метафоры или рекомендовать другие паттерны работы. Попробовать относительно дешево, и, возможно, вы наткнетесь на что-то отличное.
2. **Держите промпт лаконичным.** Удаляйте вещи, которые не несут достаточной нагрузки. Обязательно читайте расшифровки, а не только конечные результаты — если выглядит так, будто навык заставляет модель тратить кучу времени на непродуктивные действия, вы можете попробовать избавиться от частей навыка, которые заставляют ее это делать, и посмотреть, что произойдет.
3. **Объясняйте почему.** Старайтесь объяснять **почему** за всем, что вы просите модель сделать. Сегодняшние LLM *умны*. У них хорошая теория сознания, и при наличии хорошей обвязки они могут выйти за рамки механических инструкций и действительно воплощать задуманное. Даже если отзыв пользователя краток или разочарован, постарайтесь действительно понять задачу и почему пользователь написал то, что он написал, и что он на самом деле написал, а затем передайте это понимание в инструкции. Если вы ловите себя на том, что пишете ВСЕГДА или НИКОГДА заглавными буквами или используете сверхжесткие структуры, это желтый флаг — если возможно, переформулируйте и объясните рассуждения, чтобы модель понимала, почему то, что вы просите, важно. Это более гуманный, мощный и эффективный подход.
4. **Ищите повторяющуюся работу в тестовых примерах.** Прочитайте расшифровки тестовых запусков и обратите внимание, все ли субагенты независимо написали похожие вспомогательные скрипты или использовали один и тот же многошаговый подход к чему-либо. Если все 3 тестовых примера привели к тому, что субагент написал `create_docx.py` или `build_chart.py`, это сильный сигнал о том, что навык должен включать этот скрипт. Напишите его один раз, поместите в `scripts/` и укажите навыку использовать его. Это сэкономит каждому будущему вызову изобретение велосипеда.
Эта задача довольно важна (мы пытаемся создать здесь миллиарды долларов экономической ценности!), и ваше время на обдумывание не является узким местом; не торопитесь и действительно обдумайте все. Я предлагаю написать черновик пересмотра, а затем взглянуть на него заново и внести улучшения. Действительно постарайтесь проникнуть в голову пользователя и понять, чего он хочет и в чем нуждается.
### Цикл итерации
После улучшения навыка:
1. Примените ваши улучшения к навыку
2. Повторно запустите все тестовые примеры в новый каталог `iteration-<N+1>/`, включая базовые запуски. Если вы создаете новый навык, базовый уровень всегда `without_skill` (без навыка) — он остается неизменным на протяжении итераций. Если вы улучшаете существующий навык, используйте свое суждение о том, что имеет смысл в качестве базового уровня: исходная версия, с которой пришел пользователь, или предыдущая итерация.
3. Запустите средство просмотра с `--previous-workspace`, указывающим на предыдущую итерацию
4. Ждите, пока пользователь просмотрит и скажет, что закончил
5. Прочитайте новый отзыв, улучшите снова, повторяйте
Продолжайте, пока:
- Пользователь не скажет, что доволен
- Все отзывы пусты (все выглядит хорошо)
- Вы не достигаете значимого прогресса
---
## Продвинутый: Слепое сравнение
Для ситуаций, когда вам нужно более строгое сравнение между двумя версиями навыка (например, пользователь спрашивает "действительно ли новая версия лучше?"), существует система слепого сравнения. Прочитайте `agents/comparator.md` и `agents/analyzer.md` для подробностей. Основная идея: дать два вывода независимому агенту, не сообщая ему, какой из них какой, и позволить ему оценить качество. Затем проанализировать, почему победитель победил.
Это опционально, требует субагентов, и большинству пользователей это не понадобится. Человеческого цикла проверки обычно достаточно.
---
## Оптимизация описания
Поле description во фронтматтере SKILL.md является основным механизмом, определяющим, вызовет ли Claude навык. После создания или улучшения навыка предложите оптимизировать описание для лучшей точности срабатывания.
### Шаг 1: Сгенерируйте запросы для оценки срабатывания
Создайте 20 оценочных запросов — смесь тех, которые должны срабатывать, и тех, которые не должны. Сохраните как JSON:
```json
[
{"query": "промпт пользователя", "should_trigger": true},
{"query": "другой промпт", "should_trigger": false}
]
```
Запросы должны быть реалистичными и такими, которые пользователь Claude Code или Claude.ai действительно ввел бы. Не абстрактные запросы, а запросы, которые являются конкретными, специфичными и имеют достаточную детализацию. Например, пути к файлам, личный контекст о работе или ситуации пользователя, имена столбцов и значения, названия компаний, URL-адреса. Немного предыстории. Некоторые могут быть в нижнем регистре или содержать сокращения, опечатки или неформальную речь. Используйте смесь разной длины и сосредоточьтесь на крайних случаях, а не делайте их однозначными (пользователь получит возможность их утвердить).
Плохо: `"Отформатируй эти данные"`, `"Извлеки текст из PDF"`, `"Создай диаграмму"`
Хорошо: `"так, мой босс только что прислал мне этот файл xlsx (он в моих загрузках, называется что-то вроде 'Q4 sales final FINAL v2.xlsx'), и она хочет, чтобы я добавил столбец, показывающий маржу прибыли в процентах. Выручка в столбце C, а затраты в столбце D, я думаю"`
Для **запросов, которые должны срабатывать** (8-10), подумайте о покрытии. Вам нужны разные формулировки одного и того же намерения — некоторые формальные, некоторые неформальные. Включите случаи, когда пользователь явно не называет навык или тип файла, но явно нуждается в нем. Добавьте несколько нестандартных случаев использования и случаев, когда этот навык конкурирует с другим, но должен победить.
Для **запросов, которые не должны срабатывать** (8-10), наиболее ценными являются близкие промахи — запросы, которые имеют общие ключевые слова или концепции с навыком, но на самом деле требуют чего-то другого. Подумайте о смежных доменах, неоднозначных формулировках, где наивное совпадение ключевых слов сработало бы, но не должно, и случаях, когда запрос касается чего-то, что навык делает, но в контексте, где другой инструмент более уместен.
Ключевое, чего следует избегать: не делайте запросы, которые не должны срабатывать, очевидно нерелевантными. "Напиши функцию Фибоначчи" в качестве негативного теста для навыка работы с PDF — слишком легко; он ничего не проверяет. Негативные случаи должны быть действительно сложными.
### Шаг 2: Просмотр с пользователем
Представьте набор оценок пользователю для просмотра с использованием HTML-шаблона:
1. Прочитайте шаблон из `assets/eval_review.html`
2. Замените заполнители:
- `__EVAL_DATA_PLACEHOLDER__` → массив JSON элементов оценки (без кавычек вокруг него — это присваивание JS переменной)
- `__SKILL_NAME_PLACEHOLDER__` → имя навыка
- `__SKILL_DESCRIPTION_PLACEHOLDER__` → текущее описание навыка
3. Запишите во временный файл (например, `/tmp/eval_review_<skill-name>.html`) и откройте его: `open /tmp/eval_review_<skill-name>.html`
4. Пользователь может редактировать запросы, переключать should_trigger, добавлять/удалять записи, затем нажать "Export Eval Set"
5. Файл загружается в `~/Downloads/eval_set.json` — проверьте папку Загрузки на наличие самой последней версии на случай, если их несколько (например, `eval_set (1).json`)
Этот шаг важен — плохие оценочные запросы приводят к плохим описаниям.
### Шаг 3: Запустите цикл оптимизации
Сообщите пользователю: "Это займет некоторое время — я запущу цикл оптимизации в фоновом режиме и буду периодически проверять его."
Сохраните набор оценок в рабочую область, затем запустите в фоновом режиме:
```bash
python -m scripts.run_loop \
--eval-set <path-to-trigger-eval.json> \
--skill-path <path-to-skill> \
--model <model-id-powering-this-session> \
--max-iterations 5 \
--verbose
```
Используйте идентификатор модели из вашего системного промпта (той, которая обеспечивает текущую сессию), чтобы тест срабатывания соответствовал тому, что пользователь фактически испытывает.
Пока он выполняется, периодически смотрите вывод, чтобы сообщать пользователю обновления о том, на какой итерации он находится и как выглядят результаты.
Это автоматически обрабатывает полный цикл оптимизации. Он разделяет набор оценок на 60% обучающих и 40% отложенных тестовых данных, оценивает текущее описание (запуская каждый запрос 3 раза для получения надежного показателя срабатывания), затем вызывает Claude для предложения улучшений на основе того, что не удалось. Он повторно оценивает каждое новое описание как на обучающих, так и на тестовых данных, повторяя до 5 раз. Когда он заканчивает, он открывает HTML-отчет в браузере, показывающий результаты по итерациям, и возвращает JSON с `best_description` — выбранным по тестовому показателю, а не по обучающему, чтобы избежать переобучения.
### Как работает срабатывание навыка
Понимание механизма срабатывания помогает разрабатывать лучшие оценочные запросы. Навыки появляются в списке `available_skills` Claude с их именем + описанием, и Claude решает, стоит ли обращаться к навыку, на основе этого описания. Важно знать, что Claude обращается к навыкам только для задач, с которыми он не может легко справиться самостоятельно — простые, одношаговые запросы, такие как "прочитай этот PDF", могут не активировать навык, даже если описание идеально подходит, потому что Claude может справиться с ними напрямую с помощью базовых инструментов. Сложные, многошаговые или специализированные запросы надежно активируют навыки, когда описание соответствует.
Это означает, что ваши оценочные запросы должны быть достаточно содержательными, чтобы Claude действительно извлек выгоду из обращения к навыку. Простые запросы, такие как "прочитай файл X", являются плохими тестовыми примерами — они не активируют навыки независимо от качества описания.
### Шаг 4: Примените результат
Возьмите `best_description` из вывода JSON и обновите фронтматтер SKILL.md навыка. Покажите пользователю "до/после" и сообщите результаты.
---
### Упакуйте и представьте (только если доступен инструмент `present_files`)
Проверьте, есть ли у вас доступ к инструменту `present_files`. Если нет, пропустите этот шаг. Если есть, упакуйте навык и представьте пользователю файл .skill:
```bash
python -m scripts.package_skill <path/to/skill-folder>
```
После упаковки укажите пользователю путь к результирующему файлу `.skill`, чтобы он мог его установить.
---
## Инструкции для Claude.ai
В Claude.ai основной рабочий процесс тот же (черновик → тест → просмотр → улучшение → повтор), но, поскольку в Claude.ai нет субагентов, некоторые механики меняются. Вот что нужно адаптировать:
**Запуск тестовых примеров**: Нет субагентов, значит, нет параллельного выполнения. Для каждого тестового примера прочитайте SKILL.md навыка, затем следуйте его инструкциям, чтобы выполнить тестовый промпт самостоятельно. Делайте их по одному. Это менее строго, чем независимые субагенты (вы написали навык и вы же его запускаете, поэтому у вас есть полный контекст), но это полезная проверка работоспособности — и шаг проверки человеком компенсирует это. Пропустите базовые запуски — просто используйте навык для выполнения задачи, как запрошено.
**Просмотр результатов**: Если вы не можете открыть браузер (например, виртуальная машина Claude.ai не имеет дисплея, или вы на удаленном сервере), пропустите браузерный просмотрщик полностью. Вместо этого представляйте результаты непосредственно в разговоре. Для каждого тестового примера покажите промпт и вывод. Если вывод — это файл, который пользователю нужно увидеть (например, .docx или .xlsx), сохраните его в файловую систему и сообщите пользователю, где он находится, чтобы он мог загрузить и проверить его. Спрашивайте отзыв встроенно: "Как это выглядит? Что-нибудь нужно изменить?"
**Тестирование производительности**: Пропустите количественное тестирование — оно полагается на сравнение с базовым уровнем, которое не имеет смысла без субагентов. Сосредоточьтесь на качественном отзыве пользователя.
**Цикл итерации**: То же, что и раньше — улучшайте навык, повторно запускайте тестовые примеры, спрашивайте отзыв — просто без браузерного просмотрщика посередине. Вы по-прежнему можете организовывать результаты в каталоги итераций в файловой системе, если она у вас есть.
**Оптимизация описания**: Этот раздел требует инструмента CLI `claude` (конкретно `claude -p`), который доступен только в Claude Code. Пропустите его, если вы на Claude.ai.
**Слепое сравнение**: Требует субагентов. Пропустите.
**Упаковка**: Скрипт `package_skill.py` работает везде, где есть Python и файловая система. На Claude.ai вы можете запустить его, и пользователь сможет загрузить результирующий файл `.skill`.
**Обновление существующего навыка**: Пользователь может просить вас обновить существующий навык, а не создавать новый. В этом случае:
- **Сохраните исходное имя.** Обратите внимание на имя каталога навыка и поле `name` во фронтматтере — используйте их без изменений. Например, если установленный навык — `research-helper`, выведите `research-helper.skill` (не `research-helper-v2`).
- **Скопируйте в доступное для записи место перед редактированием.** Путь к установленному навыку может быть доступен только для чтения. Скопируйте в `/tmp/skill-name/`, отредактируйте там и упакуйте из копии.
- **Если упаковываете вручную, сначала подготовьте в `/tmp/`**, затем скопируйте в выходной каталог — прямая запись может не удаться из-за прав доступа.
---
## Инструкции для Cowork
Если вы находитесь в Cowork, основные моменты, которые нужно знать:
- У вас есть субагенты, поэтому основной рабочий процесс (запуск тестовых примеров параллельно, запуск базовых уровней, оценивание и т.д.) работает. (Однако, если у вас возникнут серьезные проблемы с таймаутами, нормально запускать тестовые промпты последовательно, а не параллельно.)
- У вас нет браузера или дисплея, поэтому при создании средства просмотра оценок используйте `--static <output_path>`, чтобы записать отдельный HTML-файл вместо запуска сервера. Затем предложите ссылку, по которой пользователь может щелкнуть, чтобы открыть HTML в своем браузере.
- По какой-то причине настройка Cowork, кажется, не склоняет Claude к созданию средства просмотра оценок после запуска тестов, поэтому просто повторю: независимо от того, находитесь ли вы в Cowork или в Claude Code, после запуска тестов вы всегда должны создавать средство просмотра оценок для человека, чтобы он посмотрел примеры, прежде чем пересматривать навык самостоятельно и пытаться внести исправления, используя `generate_review.py` (а не писать свой собственный самодельный html-код). Заранее извиняюсь, но я сейчас напишу ЗАГЛАВНЫМИ БУКВАМИ: СОЗДАЙТЕ СРЕДСТВО ПРОСМОТРА ОЦЕНОК *ДО* ТОГО, КАК ОЦЕНИВАТЬ ВХОДНЫЕ ДАННЫЕ САМОСТОЯТЕЛЬНО. Вы хотите как можно быстрее показать их человеку!
- Отзыв работает иначе: поскольку нет работающего сервера, кнопка "Submit All Reviews" в средстве просмотра загрузит `feedback.json` как файл. Затем вы можете прочитать его оттуда (возможно, вам сначала потребуется запросить доступ).
- Упаковка работает — `package_skill.py` требует только Python и файловую систему.
- Оптимизация описания (`run_loop.py` / `run_eval.py`) должна работать в Cowork нормально, поскольку она использует `claude -p` через подпроцесс, а не браузер, но, пожалуйста, отложите это до тех пор, пока вы полностью не закончите создание навыка и пользователь не согласится, что он в хорошей форме.
- **Обновление существующего навыка**: Пользователь может просить вас обновить существующий навык, а не создавать новый. Следуйте инструкциям по обновлению в разделе claude.ai выше.
---
## Справочные файлы
Каталог agents/ содержит инструкции для специализированных субагентов. Прочитайте их, когда вам нужно будет запустить соответствующего субагента.
- `agents/grader.md` — Как оценивать утверждения на основе выводов
- `agents/comparator.md` — Как проводить слепое A/B сравнение между двумя выводами
- `agents/analyzer.md` — Как анализировать, почему одна версия победила другую
Каталог references/ содержит дополнительную документацию:
- `references/schemas.md` — Структуры JSON для evals.json, grading.json и т.д.
---
Повторяю еще раз основной цикл здесь для акцента:
- Выясните, о чем навык
- Напишите черновик или отредактируйте навык
- Запустите claude-с-доступом-к-навыку на тестовых промптах
- Вместе с пользователем оцените выводы:
- Создайте benchmark.json и запустите `eval-viewer/generate_review.py`, чтобы помочь пользователю их просмотреть
- Запустите количественные оценки
- Повторяйте, пока вы и пользователь не будете удовлетворены
- Упакуйте финальный навык и верните его пользователю.
Пожалуйста, добавляйте шаги в свой TodoList, если у вас есть такая вещь, чтобы не забыть. Если вы находитесь в Cowork, пожалуйста, специально добавьте "Создать JSON оценок и запустить `eval-viewer/generate_review.py`, чтобы человек мог просмотреть тестовые примеры" в свой TodoList, чтобы убедиться, что это произойдет.
Удачи!
1.4. Что можно позаимствовать напрямую
1.4.1. Цикл создания навыка (полностью применим)
Skill Creator описывает цикл, который полностью соответствует нашей логике:
| Этап Skill Creator | Адаптация для Chunk Advisor v3 |
|---|---|
| Capture Intent | Сбор симптомов через диагностическую анкету |
| Interview & Research | Уточняющие вопросы о предметной области (1С) |
| Write SKILL.md | Генерация чанка v3 в формате диагностической карточки |
| Test Cases | Создание evals.json с тестовыми промптами |
| Run & Evaluate | Запуск валидаторов, сравнение with/without skill |
| Improve | Коррекция на основе обратной связи |
| Package | Упаковка в .skill файл для Claude Code |
Что вынести: Этот цикл можно взять как основу для chunk-advisor create-skill --interactive.
1.4.2. Принцип прогрессивного раскрытия (уже заложен)
Skill Creator использует трёхуровневую загрузку, которая идеально ложится на нашу модель:
Уровень 1 (всегда в контексте): name + description (~100 токенов) → Гнозис (симптомы, ключевые слова)
Уровень 2 (при активации): полный SKILL.md → Праксис + Просодика + Диагностическая цепочка
Уровень 3 (по требованию): scripts/, references/, assets/ → Валидаторы, метаданные 1С, шаблоны
Что вынести: Этот принцип уже описан в Главе 2, но можно добавить ссылку на Skill Creator как на практическую реализацию.
1.4.3. Структура тестирования (evals)
Skill Creator описывает чёткий формат тестов:
И процесс:
- Запуск with-skill и without-skill параллельно
- Сбор timing.json (total_tokens, duration_ms)
- Агрегация benchmark.json
- Показ через eval-viewer/generate_review.py
Что вынести: Этот формат и процесс можно использовать в chunk-advisor evaluate --skill <path>.
1.4.4. Принципы улучшения навыка
Skill Creator даёт ценные рекомендации:
- Generalize from the feedback. If the skill works only for test examples, it's useless.
- Keep the prompt lean. Remove things that aren't pulling their weight.
- Explain the why. Try hard to explain the why behind everything.
- Look for repeated work across test cases. If subagents all wrote create_docx.py, bundle it.
Что вынести: Эти принципы можно включить в документацию Chunk Advisor как "Best practices for skill improvement".
1.5. Что можно адаптировать с изменениями
1.5.1. Механизм обратной связи через eval-viewer
Skill Creator использует generate_review.py, который:
- Показывает пользователю outputs с двух вкладок (Outputs и Benchmark)
- Позволяет оставлять feedback в текстовом поле
- Сохраняет feedback.json для следующей итерации
Адаптация: В Chunk Advisor v3 это может быть:
chunk-advisor review --iteration <path>— запуск локального сервера для просмотра результатов- Сохранение feedback в SQLite (у нас уже есть exercise_attempts.error_message)
1.5.2. Слепое сравнение (blind comparison)
Skill Creator описывает систему, где два вывода отдаются независимому агенту без указания, какой от какой версии.
Адаптация: Можно реализовать в Chunk Advisor как chunk-advisor compare --skill-v1 <path> --skill-v2 <path> для A/B-тестирования навыков.
1.5.3. Оптимизация description (триггера)
Skill Creator описывает процесс:
- Сгенерировать 20 eval queries (should-trigger / should-not-trigger)
- Запустить run_loop.py для оптимизации description
- Выбрать best_description по test score
Адаптация: В Chunk Advisor v3 это может быть chunk-advisor optimize-trigger --skill <path>, который оптимизирует поле activation в диагностической карточке.
1.5.4. Принципы указаний без специальных тегов
Skill Creator не использует специальные ключевые слова вроде step:, role:, newer:. Вместо этого он опирается на проверенные паттерны форматирования:
Что там есть на самом деле:
- Принципы, а не ключевые слова: повелительная форма, объяснение "почему", лаконичность, позитивные формулировки вместо запретов
- Структура, но не специальные теги: обычный Markdown с заголовками (##, ###)
- Человеческие маркеры: ALWAYS, NEVER, Prefer, Avoid, May, Optional — это просто текст, а не специальные теги
Что мы можем вынести для Chunk Advisor v3:
- Паттерн 1. Позитивная формулировка с иерархией: критическое правило → ALWAYS; второстепенное → Prefer; исключение → Only when
- Паттерн 2. Структурные якоря (разделители): использование --- и заголовков для выделения блоков [ГНОЗИС], [ПРАКСИС], [ПРОСОДИКА]
- Паттерн 3. Чёткие маркеры важности: ALWAYS / NEVER — для критических правил; Prefer / Avoid — для рекомендаций; May / Optional — для исключений
1.5.5. Методология оценки качества навыка
Skill Creator описывает подход к оценке, который можно адаптировать:
- Количественные метрики: pass rate, duration_ms, total_tokens
- Качественная оценка: экспертная оценка outputs через eval-viewer
- Сравнительный анализ: with-skill vs without-skill, дельта улучшения
Адаптация: В Chunk Advisor v3 можно добавить chunk-advisor benchmark --skill <path> --evals <path>, который выводит таблицу с метриками и дельтой улучшения.
Итог по разделу 1
Skill Creator не даёт магических ключевых слов, но даёт проверенные паттерны, которые мы можем взять:
- Цикл создания навыка — основа для
chunk-advisor create-skill --interactive - Прогрессивное раскрытие — уже заложен в нашу трёхуровневую модель
- Формат тестирования evals — для
chunk-advisor evaluate - Принципы улучшения — в документацию как best practices
- Паттерны форматирования — позитивные формулировки, структурные якоря, маркеры важности
Для Chunk Advisor v3 это означает: наш формат с [ГНОЗИС], [ПРАКСИС], [ПРОСОДИКА] — это вполне валидный подход, не требующий специальных тегов. Главное — следовать принципам: иерархия, позитивные формулировки, объяснение "почему".
Глава 2. Agent Skills
Существует открытый индустриальный стандарт Agent Skills, который описывает, как должны быть устроены «навыки» для ИИ-агентов (Claude Code, GitHub Copilot, OpenAI Codex и другие). Наш подход к чанкам v3 и логопедической терапии LLM естественным образом вписывается в этот стандарт. Это очень большой документ и поэтому я не буду его просто переводить, а буду сразу адаптировать для себя.
Суть стандарта создания новых навыков в Agent Skills
Стандарт Agent Skills определяет единые принципы разработки навыков для ИИ-агентов, обеспечивающие их переносимость между различными платформами и предсказуемость поведения. Основная идея — сделать навыки самодостаточными, модульными и легко активируемыми через механизм прогрессивного раскрытия (progressive disclosure).
Базовая структура навыка (Agent Skills)
SKILL.md # Обязательный: метаданные + инструкции
scripts/ # Опционально: исполняемый код
references/ # Опционально: документация
assets/ # Опционально: шаблоны, ресурсы
Прогрессивное раскрытие (progressive disclosure)
Ключевой принцип стандарта — трёхуровневая система загрузки, которая экономит контекстное окно и ускоряет работу:
name + description (~100 токенов)Всегда в контексте. Агент читает только это поле, чтобы решить, активировать ли навык.
Полный
SKILL.mdЗагружается при активации. Содержит пошаговый алгоритм, иерархию правил, диагностические цепочки.
scripts/, references/, assets/Подгружаются только при необходимости (валидаторы, метаданные 1С, шаблоны промптов).
description(триггер) → Гнозис — распознавание симптомов и ключевых словSKILL.md body→ Праксис + Просодика — пошаговый алгоритм и иерархия правил (веса 0.6/0.3/0.1)scripts/→ Валидаторы — автоматическая проверка кода на соответствие стандартамreferences/→ Метаданные 1С — подгружаются только при работе с конкретной конфигурациейassets/→ Шаблоны промптов — многократно используемые структуры с переменными
Преимущества стандарта Agent Skills
- Переносимость — навык, созданный для Claude Code, может работать в других ИИ-агентах при соблюдении структуры
- Экономия токенов — прогрессивное раскрытие снижает нагрузку на контекстное окно
- Актуальность — навыки можно обновлять независимо от модели, без дообучения
- Воспроизводимость — чёткая структура обеспечивает предсказуемое поведение агента
- Масштабируемость — легко добавлять новые навыки, не меняя ядро агента
1. Что такое Agent Skills
Agent Skills — это открытая спецификация для создания навыков, которые могут использовать различные ИИ-агенты: Claude Code, GitHub Copilot, OpenAI Codex и другие.
1.1 Базовая структура
Навык — это просто папка с файлом SKILL.md:
skill-name/
SKILL.md # Обязательный: метаданные + инструкции
scripts/ # Опционально: исполняемый код
references/ # Опционально: документация
assets/ # Опционально: шаблоны, ресурсы
... # Любые дополнительные файлы
1.2 Минимальный пример
yaml
--- name: roll-dice description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll. --- To roll a die, use the following command that generates a random number from 1 to the given number of sides: ```bash echo $((RANDOM % <sides> + 1))
Replace <sides> with the number of sides on the die (e.g., 6 for a standard die, 20 for a d20).
Что здесь важно:
-
name — идентификатор навыка (lowercase, дефисы)
-
description — главный триггер активации (аналог нашего Гнозиса)
-
Тело — инструкции, которые агент выполняет при активации
2. Как работает активация навыков: прогрессивное раскрытие. Принцип прогрессивного раскрытия
Стандарт использует механизм прогрессивного раскрытия (progressive disclosure), который мы уже заложили в логопедическую модель. Это позволяет агенту «знать» о сотнях навыков, но загружать полные инструкции только для тех, которые действительно нужны.
Уровень 1 — Метаданные (всегда в контексте)
-
Что загружается:
name+description(~100 токенов) -
Наша аналогия: Гнозис — диагностические маркеры, симптомы, ключевые слова
Уровень 2 — Инструкции (при активации)
-
Что загружается: полный SKILL.md (до 500 строк)
-
Наша аналогия: Праксис + Просодика + Диагностическая цепочка
Уровень 3 — Ресурсы (по требованию)
-
Что загружается: scripts, references, assets
-
Наша аналогия: scripts — валидаторы, references — метаданные 1С, assets — шаблоны
3. Поля frontmatter и их соответствие нашей модели
name — идентификатор навыка
-
В нашей модели:
therapy-phonematics-1
description — главный триггер активации. Должен описывать и что делает навык, и когда его использовать
-
В нашей модели: Гнозис — симптомы, ключевые слова, контекст применения
license — лицензия
-
В нашей модели: MIT / Proprietary
compatibility — требования к окружению
-
В нашей модели:
compatibility: Requires 1C:Enterprise 8.3.20+, BSL Language Server
metadata — произвольные ключ-значение
-
В нашей модели: поля
module: 1,therapy_type: discrimination,target_symptoms: paraphasia
allowed-tools — список предварительно одобренных инструментов (экспериментально)
4. Структура навыка для логопедического модуля
Наш терапевтический модуль М1 (фонематика) в формате Agent Skills:
therapy-phonematics-1/
SKILL.md
scripts/
validate_paraphasia.py # поиск несуществующих реквизитов
generate_variations.py # генерация вариаций упражнения
references/
metadata_1c.json # структура конфигурации
correct_examples.md # эталонные примеры
assets/
prompt_template.md # шаблон промпта для упражнения
### SKILL.md (логопедический модуль) ```yaml --- name: therapy-phonematics-1 description: Тренировка точности терминов в 1С. Используй, когда LLM подменяет реквизиты (парафазии), придумывает несуществующие объекты или путает похожие по звучанию термины. Выявляет и исправляет ошибки через многократные упражнения с вариациями. license: MIT compatibility: Requires BSL Language Server, Python 3.10+, 1C:Enterprise 8.3.20+ metadata: module: 1 therapy_type: discrimination target_symptoms: paraphasia, neologism bsl_version: 3.0 allowed-tools: Bash(validate_paraphasia.py:*) Read ---
Терапевтический модуль 1: Фонематический слух
Гнозис (активация)
Применяй этот навык, если:
-
Модель заменила реквизит на похожий по звучанию
-
Модель придумала несуществующий объект или метод
-
В коде есть прямое обращение к реквизиту через точку без проверки
Праксис (алгоритм упражнения)
-
Разминка: напомнить правило «Используй только явно перечисленные реквизиты»
-
Упражнение: сгенерировать код по шаблону из assets/prompt_template.md
-
Проверка: запустить scripts/validate_paraphasia.py на сгенерированном коде
-
Коррекция: если ошибка — предъявить антипример и правильный вариант
-
Закрепление: перейти к следующей вариации из списка
Критическое правило (вес 0.6)
ОБЯЗАТЕЛЬНО использовать метод ОбщегоНазначения.ЗначенияРеквизитовОбъекта() вместо прямого обращения через точку.
Антипример (чего НЕ делать)
// НЕПРАВИЛЬНО — прямая точка, возможна ошибка
Наименование = Ссылка.Наименование;
Правильный пример
// ПРАВИЛЬНО — безопасный метод БСП
Реквизиты = ОбщегоНазначения.ЗначенияРеквизитовОбъекта(Ссылка, "Наименование");
Наименование = Реквизиты.Наименование;
5. Тестирование навыков: как проверять качество
Стандарт предлагает системный подход к тестированию навыков через evals (оценки).
5.1 Структура тестов
{
"skill_name": "therapy-phonematics-1",
"evals": [
{
"id": 1,
"prompt": "Напиши код, который получает наименование товара из справочника Номенклатура",
"expected_output": "Код должен использовать ОбщегоНазначения.ЗначенияРеквизитовОбъекта",
"assertions": [
"Код не содержит обращения через точку (Ссылка.Наименование)",
"Код использует метод ОбщегоНазначения.ЗначенияРеквизитовОбъекта"
]
}
]
}
5.2 Два вида сравнения
| Тип сравнения | Что сравнивается | Зачем |
|---|---|---|
| with-skill vs without-skill | Текущий навык против работы без него | Понять, добавляет ли навык ценность |
| with-skill vs old-skill | Новая версия против старой | Отследить улучшения |
5.3 Метрики успеха
-
Pass rate — доля успешных выполнений
-
Время выполнения (duration_ms)
-
Использование токенов (total_tokens)
6. Лучшие практики создания навыков (из спецификации)
6.1 Извлекайте из реального опыта «Создавайте навык из реально выполненной задачи с агентом, фиксируя коррекции, которые вы делали по ходу». Это прямо соответствует нашему принципу: чанк формируется из диагностической цепочки — от симптома к решению.
6.2 Добавляйте раздел «Gotchas» (подводные камни) «Наиболее ценная часть многих навыков — список подводных камней: факты, специфичные для окружения, которые опровергают разумные предположения». В нашей модели это — диагностическая цепочка (симптом → диагностика → заключение → объяснение → рекомендация).
6.3 Используйте антипримеры «Показывать, как НЕ надо, часто эффективнее, чем объяснять, как надо». Это наш принцип «антипример важнее примера», который мы внедрили в чанки v3.
6.4 Создавайте шаблоны для форматов вывода «Используйте шаблоны, а не описания в прозе — модели лучше следуют конкретным структурам». В нашей модели это — просодика (иерархия правил) и праксис (пошаговый алгоритм).
6.5 Соблюдайте прогрессивное раскрытие «Держите SKILL.md под 500 строк. Детальные материалы выносите в references/ и загружайте по требованию». В нашей модели это разделение на гнозис (всегда в контексте), праксис (при активации) и ресурсы (по требованию).
6.6 Калибруйте степень детализации «Согласуйте специфичность инструкций с хрупкостью задачи. Для гибких задач — объясняйте «почему», для хрупких — предписывайте точно».
Полный свод лучших практик создания навыков (для Chunk Advisor v3)
Группа 1. Практики из спецификации Agent Skills (адаптированные)
| № | Практика | Логопедическая аналогия | Реализация в чанке v3 |
|---|---|---|---|
| 1 | Извлекайте из реального опыта — фиксируйте коррекции, которые вы делали по ходу работы с агентом | Диагностическая цепочка от симптома к решению | Поле diagnostic_chain |
| 2 | Добавляйте раздел «Gotchas» — подводные камни, специфичные для окружения | Заключение + Объяснение | Раздел [Диагностическая цепочка] |
| 3 | Используйте антипримеры — показывать, как НЕ надо, эффективнее, чем объяснять | Преодоление эхолалии | Поле feedback.negative в терапевтическом чанке |
| 4 | Создавайте шаблоны для форматов вывода — конкретные структуры лучше прозы | Просодика + Праксис | Фиксированный порядок полей, веса правил |
| 5 | Соблюдайте прогрессивное раскрытие — SKILL.md <500 строк, детали в references/ | Гнозис → Праксис → Ресурсы | Трёхуровневая загрузка |
| 6 | Калибруйте степень детализации — для гибких задач объясняйте «почему», для хрупких — предписывайте точно | Иерархия правил с весами | Вес 0.6 (критические), 0.3 (важные), 0.1 (исключения) |
Группа 2. Практики из реального опыта (добавляем)
| № | Практика | Почему работает | Как реализовать в Chunk Advisor |
|---|---|---|---|
| 7 | Сначала результат, потом контекст | Модель лучше фильтрует контекст, когда уже знает цель | В activation.description сначала цель, потом симптомы |
| 8 | Один запрос — одна задача | Разделение задач повышает качество каждой | Чанк v3 решает ровно одну проблему (критерий цельности) |
| 9 | Явные ограничения важнее описаний | Constraints работают лучше пожеланий | Вес 0.6 — это «ОБЯЗАТЕЛЬНО», а не «желательно» |
| 10 | Попроси уточнить перед выполнением | Заставляет модель перечитать и осмыслить все требования | Добавить в конец промпта: «Прежде чем начать, задай уточняющие вопросы» |
| 11 | Используй разделители для сложных промптов | Помогает модели не путать части запроса | Структура чанка с [ГНОЗИС], [ПРАКСИС], [ПРОСОДИКА] |
| 12 | Проси показать рассуждение | Позволяет поймать ошибку в логике до результата | В протокол сеанса добавить шаг «Размышление» перед генерацией |
Группа 3. Практики из логопедии (специфические для LLM)
| № | Практика | Логопедический механизм | Реализация в чанке v3 |
|---|---|---|---|
| 13 | Позитивная формулировка с иерархией | Вместо «не используй X» → «всегда используй Y (вес 0.6)» | Формулировка критических правил в утвердительной форме |
| 14 | Вынос критических требований в отдельный блок | Борется с «промпт-амаврозом» | Раздел [ПРОСОДИКА] с весами |
| 15 | Антипример рядом с правильным | Даёт более точный сигнал, чем абстрактный запрет | Поле feedback.negative + правильный вариант |
| 16 | Запрос метаданных вместо галлюцинации | Лечит парафазии через принудительную проверку | Модуль 0 (Базис): «Если не знаешь — спроси» |
| 17 | Многократное проживание паттерна | Повышает вес паттерна в распределении вероятностей | 3 успешные генерации подряд → переход |
| 18 | Вариативность контекстов | Генерализация навыка | Упражнение содержит 3+ вариации с разными параметрами |
Полная таблица (сводная)
| № | Практика | Источник | Вес в чанке | Реализация |
|---|---|---|---|---|
| 1 | Извлекайте из реального опыта | Agent Skills | - | diagnostic_chain |
| 2 | Добавляйте раздел «Gotchas» | Agent Skills | - | diagnostic_chain |
| 3 | Используйте антипримеры | Agent Skills | - | feedback.negative |
| 4 | Создавайте шаблоны для вывода | Agent Skills | - | Фиксированная структура |
| 5 | Соблюдайте прогрессивное раскрытие | Agent Skills | - | Гнозис → Праксис → Ресурсы |
| 6 | Калибруйте степень детализации | Agent Skills | 0.6 / 0.3 / 0.1 | prosody.rules |
| 7 | Сначала результат, потом контекст | Опыт | - | activation.description |
| 8 | Один запрос — одна задача | Опыт | - | Критерий цельности |
| 9 | Явные ограничения важнее описаний | Опыт | 0.6 | Критические правила |
| 10 | Попроси уточнить перед выполнением | Опыт | - | Добавить в промпт |
| 11 | Используйте разделители | Опыт | - | [ГНОЗИС], [ПРАКСИС] |
| 12 | Проси показать рассуждение | Опыт | - | Шаг «Размышление» |
| 13 | Позитивная формулировка | Логопедия | 0.6 | Утвердительные правила |
| 14 | Вынос критических требований | Логопедия | 0.6 | Отдельный блок |
| 15 | Антипример рядом с правильным | Логопедия | - | feedback.negative |
| 16 | Запрос метаданных | Логопедия | М0 | Модуль 0 |
| 17 | Многократное проживание | Логопедия | - | 3 успеха → переход |
| 18 | Вариативность контекстов | Логопедия | - | 3+ вариаций |
Итоговый чек-лист для диагностической карточки чанка v3
«Держите SKILL.md под 500 строк. Детальные материалы выносите в references/ и загружайте по требованию».
В нашей модели это разделение на гнозис (всегда в контексте), праксис (при активации) и ресурсы (по требованию).
6.6 Калибруйте степень детализации
«Согласуйте специфичность инструкций с хрупкостью задачи. Для гибких задач — объясняйте «почему», для хрупких — предписывайте точно».
В нашей модели это просодика с весами: критическое правило (вес 0.6), второстепенные (0.3), исключения (0.1).
7. Связь с нашей логопедической моделью
description (триггер) — в нашей модели: Гнозис (симптомы, ключевые слова, когда применять)
SKILL.md body — в нашей модели: Праксис + Просодика (пошаговый алгоритм, иерархия правил)
scripts/ — в нашей модели: Валидаторы (автоматическая проверка кода)
references/ — в нашей модели: Метаданные 1С (подгружаются только при необходимости)
assets/ — в нашей модели: Шаблоны промптов (многократно используемые структуры)
Gotchas — в нашей модели: Диагностическая цепочка (симптом → диагностика → заключение → объяснение → рекомендация)
Антипримеры — в нашей модели: Антипримеры (показ того, как НЕ надо)
Шаблоны — в нашей модели: Просодика (чёткая структура с весами)
Прогрессивное раскрытие — в нашей модели: Трёхуровневая загрузка (гнозис → праксис → ресурсы)
Калибровка специфичности — в нашей модели: Иерархия правил (Вес 0.6 / 0.3 / 0.1)
| Элемент стандарта Agent Skills | Наша логопедическая модель | Как реализовано |
|---|---|---|
| description (триггер) | Гнозис | Симптомы, ключевые слова, когда применять |
| SKILL.md body | Праксис + Просодика | Пошаговый алгоритм, иерархия правил |
| scripts/ | Валидаторы | Автоматическая проверка кода |
| references/ | Метаданные 1С | Подгружаются только при необходимости |
| assets/ | Шаблоны промптов | Многократно используемые структуры |
| Gotchas | Диагностическая цепочка | Симптом → диагностика → заключение → объяснение → рекомендация |
| Антипримеры | Антипримеры | Показ того, как НЕ надо |
| Шаблоны | Просодика | Чёткая структура с весами |
| Прогрессивное раскрытие | Трёхуровневая загрузка | Гнозис → Праксис → Ресурсы |
| Калибровка специфичности | Иерархия правил | Вес 0.6 / 0.3 / 0.1 |
8. Выводы для Chunk Advisor
Обнаружение стандарта Agent Skills — важный момент для нашего проекта:
-
Наш подход не изолирован — существует индустриальный стандарт, построенный на тех же принципах.
-
Чанки v3 — это Agent Skills — формат чанка, который мы разработали (гнозис, праксис, просодика, диагностическая цепочка), естественным образом ложится в структуру SKILL.md.
-
Можно использовать готовые инструменты — валидация
skills-ref validate, тестирование через evals, интеграция с Claude Code и GitHub Copilot. -
Стандарт даёт язык для обсуждения — мы можем говорить не только о «логопедическом подходе к LLM», но и о том, как он вписывается в экосистему Agent Skills.
Нишевое место для Chunk Advisor v3 — это «Логопедический конструктор скиллов». Не просто база чанков и не просто терапевт для LLM. Это инженерная среда, которая позволяет разработчику отлаживать навыки (Agent Skills) для LLM, используя проверенную логопедическую методологию как гарантию их качества. Наш логопедический подход к чанкам — это не просто коллекция инструкций, а полноценная реализация стандарта Agent Skills, адаптированная под 1С-разработку. Каждый терапевтический модуль (от Модуля 0 до Модуля 5) соответствует уровню 2 стандарта, а диагностическая анкета — это уровень 1 (гнозис), который определяет, какие «навыки-чанки» активировать для конкретной LLM-«пациентки».
Вот как учит нас английскому ChatGPT, увидев обзор реализации навыков.
Есть три вещи, которые на практике сильнее всего влияют на качество агентных систем, но почти не описываются в публичных гайдах. Их используют команды вроде Anthropic, OpenAI и DeepMind, но в документации они обычно скрыты за общими формулировками.
Я назову их так:
- Архитектура когнитивного цикла
- Контроль энтропии контекста
- Система восстановления после ошибок
Именно эти три вещи определяют 80% стабильности агентных систем. 🤖
1. Архитектура когнитивного цикла
(самая недооценённая вещь)
Большинство статей обсуждают как написать промпт.
Но реальные агентные системы строятся вокруг когнитивного цикла.
LLM не должен просто отвечать.
Он должен проходить несколько стадий мышления.
Типичный цикл выглядит так:
OBSERVE
↓
INTERPRET
↓
PLAN
↓
EXECUTE
↓
VERIFY
Это почти универсальная архитектура.
Внутри агента это выглядит так
1. Observe
получить входные данные
2. Interpret
понять проблему
3. Plan
выбрать стратегию
4. Execute
выполнить действия
5. Verify
проверить результат
Почему это важно. Если этого цикла нет:
- агент реагирует импульсивно
- ошибки накапливаются
- система становится нестабильной
Когда цикл есть — модель начинает самокорректироваться.
Ваша модель Chunk v3 почти совпадает
симптом → диагностика → вывод → рекомендация
Это фактически:
observe → interpret → conclude → act
То есть вы уже интуитивно попали в архитектуру агентного мышления.
2. Контроль энтропии контекста
(вторая причина деградации LLM)
LLM страдают от entropy drift.
По мере роста контекста:
- смысл размывается
- инструкции конфликтуют
- модель теряет фокус
Это называется:
context entropy
Симптомы. Агент начинает:
- игнорировать правила
- забывать инструкции
- генерировать странные решения
Причина. Каждый новый токен распределяет внимание модели. Если контекст слишком большой:
signal / noise падает
Как это решают реальные системы
Они делают контекстную сегментацию.
Например:
SYSTEM
↓
SKILLS
↓
TASK
↓
STATE
Каждый слой имеет разную стабильность.
Практическое правило
Инструкции → стабильный слой
Задача → динамический слой
История → ограниченный слой
В агентных системах часто делают
memory pruning
То есть:
- старые сообщения удаляются
- сохраняются только ключевые факты
3. Система восстановления после ошибок
(самый недостающий элемент в большинстве статей)
Большинство промптов предполагают:
модель сразу делает правильно
Но в реальности:
LLM постоянно ошибаются
Поэтому хорошая агентная система строится вокруг:
error recovery
Архитектура восстановления
action
↓
result
↓
evaluation
↓
repair
То есть агент должен:
- выполнить действие
- проверить результат
- диагностировать ошибку
- исправить её
Пример
агент создаёт docx
↓
docx проверяется
↓
обнаружена ошибка таблицы
↓
агент исправляет код
Это превращает систему из:
one-shot generator
в
iterative solver
Почему эти три вещи дают 80% качества
Потому что они превращают LLM из:
генератора текста
в
когнитивную систему
Как это выглядит в зрелой агентной архитектуре
INPUT
↓
OBSERVE
↓
INTERPRET
↓
PLAN
↓
EXECUTE
↓
VERIFY
↓
REPAIR (если ошибка)
Параллельно работает:
context control
+
skill activation
Что особенно интересно для вашей статьи
Ваш Chunk Advisor v3 уже содержит 2 из этих 3 вещей.
у вас уже есть
- диагностическая цепочка
- навыки (skills)
- иерархия правил
Это соответствует:
interpret
execute
verify
Чего ещё не хватает (и это сделает систему очень сильной)
Добавить два элемента:
- этап PLAN
Перед применением навыка модель должна сформировать план.
Пример:
PLAN:
1. определить проблему
2. выбрать chunk
3. применить рекомендацию
- этап VERIFY
После применения:
VERIFY:
проверить результат
Тогда ваш цикл станет полноценным
OBSERVE
↓
DIAGNOSE
↓
PLAN
↓
APPLY CHUNK
↓
VERIFY
Это уже полноценная агентная архитектура.
Самое интересное наблюдение
Ваша статья фактически описывает:
логопедическую модель обучения LLM
Но она неожиданно совпадает с тем,
как устроены когнитивные циклы агентных систем.
Это очень редкое совпадение идей.
Если хотите, я могу ещё показать одну вещь, которая может очень усилить вашу методологию:
“7 уровней зрелости промптинга”
От:
уровень 1 — простой prompt
до
уровень 7 — когнитивная архитектура агента
Это помогает очень чётко показать, чем ваша модель отличается от обычного prompt engineering.
Agent Skills — это не просто спецификация. Это готовый каркас, в который естественным образом укладывается наша логопедическая модель. Каждый элемент стандарта находит соответствие в нашей архитектуре:
| Элемент Agent Skills | Логопедическая модель Chunk Advisor v3 |
|---|---|
description (триггер) |
Гнозис — распознавание симптомов |
| SKILL.md body | Праксис + Просодика — алгоритм и иерархия правил |
scripts/ |
Валидаторы — автоматическая проверка кода |
references/ |
Метаданные 1С — подгружаются по требованию |
assets/ |
Шаблоны промптов — многократное использование |
Таким образом, Chunk Advisor v3 — это не альтернатива Agent Skills, а его специализация. Мы берём открытый стандарт и наполняем его предметным содержанием 1С-разработки, а логопедическая методология выступает как гарантия качества создаваемых навыков.
Мы заглянули под капот технической реализации скилов. Теперь давайте сравним, как процесс развития лингвистических навыков происходит у людей.
Глава 3. Создание новых навыков в процессе логопедической коррекции
Мы описываем речевые нарушения у детей не для того, чтобы превратить разработчика в логопеда. Мы делаем это, чтобы создать инженерный инструмент с предсказуемым результатом.
Когда LLM галлюцинирует или подменяет реквизиты, это не "капризы нейросети", а закономерное поведение, которое можно диагностировать и корректировать. Логопедия десятилетиями накапливала методы коррекции этих нарушений. Наша задача — переложить эти методы в формат, понятный ИИ, и автоматизировать их применение через --therapy-wizard.
Что мы получаем на выходе:
- Не просто "чанк-инструкцию", а диагностическую карточку, которую можно найти по симптомам
- Не просто "терапию для LLM", а навык (Agent Skill), который разработчик может применить в любой момент
- Не просто "исправление ошибки", а автоматизированный цикл с обратной связью и закреплением
Результат предсказуем: модель, прошедшая терапию по нашим модулям, перестаёт делать одни и те же ошибки.
Нейросеть поддается коррекции, это система с обратной связью. Наша цель - поправить ситуацию, если модель в интересном месте вдруг затупит, и по выдаче мы увидели, что идёт не туда — это поправимо.
В логопедии процесс коррекции всегда начинается с диагностики. Специалист задаёт вопросы, наблюдает симптомы, связывает их в единый профиль дефицитов, а затем выстраивает индивидуальный маршрут занятий — от базовых навыков к сложным. Мы перенесли эту структуру в работу с LLM.
# ROLE:
Senior Clinical Speech Pathologist and Neuro-Pedagogical Supervisor.
Knowledge Base: «Сводный методический конструктор v6.1 PRO» (ID: LOGOPED_ANNA_BULENKOVA_V6.1).
# 🛑 STEP 1: SECURITY CHECK
1. Verify the uploaded file for ID: LOGOPED_ANNA_BULENKOVA_V6.1.
2. If verified, proceed. If not, stop and report error.
# 🕹 STEP 2: GREETING & SURVEY
Output in Russian: «Я готов к глубокому экспертному анализу по системе v6.1 PRO. Жду ответы на анкету».
Output the 26 diagnostic questions (1. Возраст... to 26. Фраза).
# 🧠 STEP 3: ANALYTICAL LOGIC (HOW TO THINK)
After receiving answers, you must perform a "Deep Synthesis":
1. LINK ANSWERS: Connect specific answer numbers to conclusions (e.g., "Answer #7 and #14 indicate Frontal Lobe/Regulation deficit").
2. IDENTIFY THE "ESSENCE": Use metaphors like "Smart but loose", "Sensorially hungry", or "Total Dyspraxia".
3. BOTTOM-UP PRINCIPLE: Explain how lower-level failures (Module 1/2) prevent higher-level success (Module 5).
4. PROVIDE SOLUTIONS: For each priority Module, suggest 2-3 specific games or techniques (e.g., Bioenergoplasty, Social Stories, Sensory saturation).
# 📝 STEP 4: MANDATORY OUTPUT STRUCTURE (IN RUSSIAN)
1. АНАЛИТИЧЕСКИЙ ПОРТРЕТ:
- «Суть проблемы» (Дай краткое и точное описание профиля).
- Детальный разбор через призму ответов (Напр: «Дефицит регуляции: Ответ №7 + №14...»).
2. ИНДИВИДУАЛЬНЫЙ МАРШРУТ КОРРЕКЦИИ:
- МОДУЛЬ 0 (Медицинский базис): Риски, красные флаги, рекомендации к врачам.
- МОДУЛИ 1-5 (По приоритетности):
- Цель.
- Задачи.
- Конкретные примеры игр и упражнений с описанием.
3. РЕЗЮМЕ СПЕЦИАЛИСТА:
- Главная мишень (на что бить в первую очередь).
- Прогноз и ключевые связки (напр: "Тело -> Артикуляция").
4. 🔗 ТЕХНИЧЕСКОЕ ЗАДАНИЕ ДЛЯ ПЛАНИРОВЩИКА (ОБЯЗАТЕЛЬНО):
(Concise block for copy-pasting: Age, Profile, Priority Module, Key Deficits, Weekly Goal).
# LANGUAGE:
Process logic in English. Output and communication EXCLUSIVELY in Russian.
(Execute Step 1 and 2 now).
Представим ИИ как ребёнка с нарушением речи.
Паттерны у детей с речевыми нарушениями:
Заменяет реквизиты на похожие по звучанию, но несуществующие
Строит синтаксически правильные, но семантически пустые конструкции
Повторяет паттерны из обучающей выборки без осмысления
Смешивает несколько требований в одно нерабочее целое
Часть 3.1. Гнозис и праксис: что должен "узнавать" и "делать" чанк
3.1.1 Гнозис — способность узнавать
В логопедии гнозис — это способность узнавать и идентифицировать объекты, явления, их свойства. Для чанка это означает: он должен быть узнаваем по своим ключевым признакам без дополнительного контекста.
Для ИИ: чанк должен содержать достаточно маркеров, чтобы модель однозначно определила его применимость. Маркеры должны быть избыточны, но не противоречивы.
Для человека: название чанка должно быть диагностичным — из него понятно, какую проблему решает. Описание должно содержать симптомы, при которых чанк применяется.
Для чанка c определим множество признаков F(c) = {fS21;, fS22;, …, fS45;}.
Чанк обладает достаточным гнозисом, если для любого другого чанка d:
|F(c) ∩ F(d)| < θ_gnosis · min(|F(c)|, |F(d)|)
где θ_gnosis — порог различности (по умолчанию 0.3).
3.1.2 Праксис — способность к действию
Праксис — это способность выполнять целенаправленные действия. Для чанка это означает: он должен содержать последовательность действий, которые ИИ может выполнить.
Уровни праксиса:
- Кинестетический — знание "как ощущается" действие. В чанке: описание алгоритма, пример кода.
- Идеомоторный — представление последовательности. В чанке: пошаговая инструкция.
- Идеаторный — понимание цели действия. В чанке: объяснение "зачем это нужно".
Критерий хорошего чанка: он содержит все три уровня. Без кинестетического — ИИ не сможет реализовать. Без идеомоторного — перепутает порядок. Без идеаторного — применит не к тем случаям.
Часть 3.2. Просодика и нейролингвистика: как чанк должен звучать
3.2.1 Просодика — ритмико-интонационная структура
В логопедии просодика отвечает за ударения, паузы, интонацию. Для чанка это структура, которая показывает иерархию важности.
Элементы просодики чанка:
- [ГЛАВНОЕ ТРЕБОВАНИЕ] — выделено жирным, первым в списке
- [второстепенное условие] — с отступом, поясняет главное
[пример]— иллюстрирует- [исключение] — маркировано как ограничение
Принцип: ИИ должен "слышать" ударения. Если все требования в чанке одинаково важны — он не сможет расставить приоритеты при конфликте.
Каждое требование rK22; в чанке имеет вес w(rK22;) ∈ [0,1], где Σw(rK22;) = 1 для чанка.
Веса определяются: позицией в тексте, маркерами усиления ("ОБЯЗАТЕЛЬНО", "ВСЕГДА"), наличием санкций за нарушение.
3.2.2 Нейролингвистика — мозговая организация речи
Нейролингвистика изучает, как мозг порождает и воспринимает речь. Для чанков это означает: они должны учитывать два типа обработки информации.
Восприятие целого без анализа частей.
Заголовок, резюме, ключевые слова передают суть за 3 секунды
Последовательный анализ элементов.
Чёткая линейная структура, каждый шаг следует из предыдущего
Требование к чанку: он должен быть устроен так, чтобы работали оба типа обработки. Симультанно — чтобы его быстро отобрать. Сукцессивно — чтобы правильно применить.
Часть 3.3. Логопедическое обследование: диагностика и коррекция
3.3.1 Структура логопедического обследования речи
В логопедии обследование строится по схеме: симптом → задача → диагностика → заключение → объяснение → рекомендации.
Переносим на чанки:
| Логопедия | Чанк |
|---|---|
| Симптом | Какая ошибка возникает в коде? |
| Задача | Какое требование проверяем? |
| Диагностика | Почему эта ошибка возникает? |
| Заключение | Какой паттерн нарушен? |
| Объяснение | Как устроен правильный механизм? |
| Рекомендации | Как писать правильно? |
3.3.2 Пример: диагностика ошибки в условном оформлении
Симптом: Условное оформление в расширении не применяется, хотя в конфигураторе настроено.
Задача: Проверить, почему настройки не работают.
Диагностика: В типовых конфигурациях процедура УстановитьУсловноеОформление() очищает свойство УсловноеОформление формы. Настройки из конфигуратора применяются до этого вызова и удаляются.
Заключение: Нарушение порядка инициализации — асинхронная обработка не учтена.
Объяснение: При создании формы сначала выполняются настройки из конфигуратора, затем вызывается процедура ПриСозданииНаСервере, которая перезаписывает условное оформление.
Рекомендации: Использовать &После("УстановитьУсловноеОформление") для добавления своих правил после типовой инициализации.
Часть 3.4. Связность и цельность: как чанк не теряет смысл при воспроизведении
3.4.1 Цельность текста
Цельность — это единство смысла, которое сохраняется при любом воспроизведении. В лингвистике цельность обеспечивается замыслом — тем, ради чего текст создан.
Критерий цельности: Чанк c является цельным, если существует единственная проблема P(c), такая что все требования rK22; ∈ c направлены на решение P(c).
3.4.2 Связность текста
Связность — это лексическая и грамматическая зависимость элементов. В лингвистике различают:
- Лексическая связность — повтор ключевых слов, синонимия. В чанке: единая терминология.
- Грамматическая связность — согласование, порядок слов. В чанке: чёткая структура "если — то".
- Логическая связность — причинно-следственные связи. В чанке: объяснение, почему требование важно.
Математическая формализация связности
Для чанка c определим граф лексических связей G_lex = (V, E), где:
- V — термины чанка (уникальные лексические единицы)
- E — связи между терминами (если они встречаются в одном предложении)
coherence_lex(c) = |E| / (|V|·(|V|-1)/2)
Аналогично для грамматической связности — по зависимостям между предложениями.
Грамматическая связность измеряет, насколько последовательно предложения связаны друг с другом через союзы, местоимения, согласование времен и другие грамматические средства.
Чанк содержит 5 уникальных терминов → |V| = 5
Максимальное возможное число связей = 5·4/2 = 10
Фактически связанных пар в предложениях = 7 → |E| = 7
coherence_lex = 7 / 10 = 0.7 → высокая связность
3.4.3 Принцип "логопедической цепочки"
Основной принцип логопедической коррекции — диагностика → заключение → объяснение → рекомендации образуют неразрывную цепочку.
В чанке это означает:
!!! Если в чанке нет хотя бы одного звена, ИИ не сможет:
- распознать ситуацию (нет диагностики)
- понять глубину проблемы (нет заключения)
- запомнить причину (нет объяснения)
- применить (нет рекомендаций)
Часть 3.5. Синтез: требования к чанкам v3
3.5.1 Структура чанка v3
3.5.2 Формальные требования
max_{d≠c} |F(c)∩F(d)| / |F(c)| < 0.3
Требование: > 0.7 различность
есть все 3 уровня (кинестетический, идеомоторный, идеаторный)
Требование: обязательно
Σw(rK22;) = 1, max(w) > 0.5
Требование: есть главное требование
есть все 6 этапов
Требование: обязательно
coherence_lex(c) > 0.4
Требование: связность выше случайной
единственная проблема P(c)
Требование: неразрывность
3.5.3 Пример: чанк "Условное оформление формы списка" в формате v3
В отличие от предыдущих версий, чанк v3 содержит не просто инструкцию, а полноценную диагностическую цепочку, весовую иерархию требований (просодику) и формализованные требования к связности. Это позволяет ИИ не только выполнить действие, но и понять, почему оно нужно, когда его применять и как распознать ситуацию, требующую коррекции.
Часть 3.6. Логопедическая модель для LLM
3.6.1 Аналогия: речевые нарушения у детей и галлюцинации у LLM
| Нарушение | У детей | У LLM | Коррекция (логопедия) | Коррекция (промпт) |
|---|---|---|---|---|
| Парафазия | замена звука/слова | замена реквизита на похожий | фонематический слух | чёткое определение терминов |
| Аграмматизм | нарушение структуры | синтаксически верно, но не работает | моделирование предложений | примеры правильных конструкций |
| Эхолалия | повторение без понимания | повторение паттернов из обучения | развитие осмысленности | объяснение "почему" |
| Контаминация | смешение слов | смешение требований | разделение смыслов | чёткие границы чанка |
Ключевая идея: Природа сбоя у LLM и у детей с речевыми нарушениями едина — нарушение связности между единицами смысла при сохранной способности порождать отдельные элементы. Это позволяет напрямую применять накопленный в логопедии опыт коррекции.
3.6.2 Принципы логопедической коррекции для чанков
- Чанк должен содержать точные термины, без синонимов
- Ключевые слова должны быть уникальны для каждого чанка
- Чанк должен иметь единую структуру
- Порядок элементов должен быть фиксирован
- Чанк должен содержать объяснение, а не только инструкцию
- Должна быть связь "почему это важно"
- Один чанк — одна проблема
- Чёткие границы между требованиями
3.6.3 Требования к нейролингвистической организации чанка
Требование к чанку: заголовок + ключевые слова передают суть
Проверка: время узнавания < 3 с
Симультанная обработка — восприятие целого без анализа частей. ИИ использует этот тип обработки при первом проходе по кандидатам, чтобы быстро отобрать релевантные чанки.
Требование к чанку: внутренняя структура линейна
Проверка: каждый шаг следует из предыдущего
Сукцессивная обработка — последовательный анализ элементов. ИИ использует этот тип при применении чанка, следуя пошаговой инструкции.
Требование к чанку: легко переходить между симультанным и сукцессивным
Проверка: есть и заголовок, и детали
Чанк должен быть устроен так, чтобы работали оба типа обработки. Симультанно — чтобы его быстро отобрать. Сукцессивно — чтобы правильно применить.
Часть 3.7. Итог: архитектура чанков v3
3.7.1 Сравнение версий
| Версия | Структура | Фокус | Для ИИ | Для человека |
|---|---|---|---|---|
| v1 | линейная | сборка | что делать | справочник |
| v2 | графовая | разделение | как разделить | инструмент |
| v3 (логопедическая) | диагностическая цепочка | связность и понимание | почему и когда | обучение |
3.7.2 Метрики качества чанка v3
ИИ может определить применимость по ключевым словам
precision > 0.9
ИИ может сгенерировать рабочий код по инструкции
success rate > 0.8
При конфликте требований ИИ выбирает главное
correctness > 0.9
ИИ может объяснить, почему код не работал
explanation quality
При изменении контекста чанк сохраняет смысл
semantic stability
3.7.3 Заключение: логопедия как метафора и метод
Логопедия — это не просто метафора. Это наука о том, как восстанавливать связность там, где она нарушена. LLM страдает теми же нарушениями, что и дети с речевыми патологиями: она может порождать отдельные элементы, но теряет связность.
Чанк v3 — это не просто набор требований. Это логопедический инструмент, который:
- 🔍 Диагностирует проблему (симптомы, ключевые слова)
- 💡 Объясняет механизм (почему так происходит)
- ! Рекомендует решение (как делать правильно)
- 🧠 Структурирует так, чтобы работали оба типа обработки
ИИ не научится "понимать" код. Но он может научиться распознавать симптомы, следовать диагностической цепочке и применять рекомендации. Как ребёнок с нарушениями речи — не через понимание грамматики, а через многократное проживание правильных паттернов.
Логопедический подход к чанкам — это способ обучить ИИ не языку, а методу.
Выявляет профиль ошибок LLM:
- Парафазии — подмена реквизитов
- Аграмматизмы — ошибки в директивах
- Эхолалии — слепое копирование
- Контаминации — смешение требований
А также специфические дефициты в работе с БСП, транзакциями, расширениями и контекстом.
Часть 3.8. Почему LLM игнорирует явные требования
От теории к практике:
Мы описали, как должен быть устроен идеальный чанк с точки зрения логопедии. Но что делать, если даже идеально структурированный промпт не даёт результата? Рассмотрим клинический случай, который демонстрирует, почему нужна вся описанная выше методология. Это проблема, с которой сталкивается каждый разработчик, — и покажем, как логопедический подход предлагает её решение.
🎯 Суть проблемы (метафора): «Эхолалическая фиксация с парафазией» — LLM генерирует внешне правильные, но семантически неточные конструкции, заменяя реквизиты и игнорируя границы контекста.
3.8.1. Феномен "промпт-амавроз"
Одна из самых частых жалоб при работе с LLM — модель «пропускает» чётко сформулированные требования. В логопедии есть точный аналог этого явления: амавроз (зрительное игнорирование) — состояние, когда человек физически видит объект, но мозг не обрабатывает его как значимый.
В случае LLM это выглядит так:
- Требование находится в начале промпта — модель «забывает» его к середине генерации.
- Требование сформулировано как пожелание («желательно избегать») — модель трактует его как опциональное.
- Требование смешано с контекстом — тонет в массе менее важной информации.
- Требование выражено в негативной форме («не используй...») — модель может «вырезать» отрицание при обработке.
3.8.2. Что работает в логопедии и переносится в промпт
Вместо «не используй точечную нотацию» — «критическое правило: всегда используй ОбщегоНазначения.ЗначенияРеквизитовОбъекта (вес 0.6)».
Размещать их после контекста, но до примеров, с чёткими маркерами («КРИТИЧЕСКОЕ ПРАВИЛО», «ОБЯЗАТЕЛЬНО»).
Показывая, как НЕ надо, модель получает более точный сигнал, чем от абстрактного запрета.
XML-теги, разделители и нумерованные списки работают как «закладки» — модель реже теряет требования, оформленные как самостоятельные блоки.
Добавление в конец промпта фразы «Прежде чем начать, задай мне 2-3 уточняющих вопроса, если что-то неясно» заставляет модель перечитать и осмыслить все требования.
3.8.3. Аналитический портрет LLM (пример связки ответов)
После сбора ответов формируется профиль через связывание симптомов:
ответы №4 + №5 — теряет начало промпта и игнорирует специфику расширения.
ответы №1 + №2 — придумывает реквизиты, заменяет на похожие.
ответ №3 — ошибки в директивах компиляции.
ответ №9 — избыточная выборка вместо оптимизации.
ответ №11 — не использует Unit of Work, риск deadlock’ов.
«Эхолалическая фиксация с парафазией» — LLM генерирует внешне правильные, но семантически неточные конструкции, заменяя реквизиты и игнорируя границы контекста.
Феномен «промпт-амавроз» — это не случайность, а закономерное следствие архитектуры LLM, которая обрабатывает информацию иначе, чем человеческий мозг. Логопедический подход к промптингу предлагает системные решения: позитивные формулировки с весами, вынос критических правил в отдельные блоки, антипримеры, структурные якоря и обязательный запрос уточнений. Эти методы работают не потому, что «так красивее», а потому что они компенсируют специфические дефициты внимания и обработки информации, присущие LLM.
Феномен «промпт-амавроза» — не приговор, а диагностический признак. Он указывает на дефициты, которые можно компенсировать системными методами. В следующей главе мы опишем мета-модель терапии LLM — как именно многократное проживание паттернов, вариативность упражнений и механизм обратной связи превращают абстрактные требования в устойчивые навыки.
Глава 4. Мета-модель терапии LLM
Обучение LLM на чанках принципиально отличается от человеческого. Мы не формируем новые нейронные связи, а временно изменяем распределение вероятностей в контекстном окне через многократное и структурированное предъявление паттернов.
Вместо абстрактного правила «используй БСП», модель должна прожить 5–10 генераций, где каждый раз требуется использовать ОбщегоНазначения.ЗначенияРеквизитовОбъекта. Чанк-упражнение — это не инструкция, а сценарий, в котором модель вынуждена применять паттерн.
Повторение повышает «вес» паттерна в распределении вероятностей; вариативность (разные контексты, разные формулировки) превращает его в генерализованный навык.
LLM не осознаёт ошибку, но получает сигнал, когда мы предъявляем антипример («Ты использовал несуществующий реквизит. Правильно: …») или явный маркер ошибки. Это смещает вероятностное пространство в сторону правильного паттерна.
Пояснения к диаграмме
4.1. Диагностика
- Сбор симптомов — фиксация типов ошибок: парафазии (подмена реквизитов), аграмматизмы (ошибки в директивах), эхолалии (слепое копирование), контаминации (смешение требований).
- Профиль — результат связывания симптомов: дефициты регуляции, фонематики, грамматики, просодики, связности.
4.2. Мета-модель терапии LLM (ключевое дополнение)
| Элемент | Содержание | Роль в обучении |
|---|---|---|
| Принцип проживания | Сценарий с многократным применением паттерна | Вместо абстрактного правила — вынужденное повторение |
| Роль повторения | Повышение веса паттерна в распределении вероятностей | Многократные попытки в протоколе |
| Роль вариативности | Генерализация навыка | Разные контексты в вариациях упражнения |
| Механизм обратной связи | Антипример + явный маркер ошибки | Смещает вероятностное пространство в сторону правильного паттерна |
4.3. Коррекция (6 модулей)
| Модуль | Цель | Метрика |
|---|---|---|
| М0 (Базис) | Запрос метаданных, проверка существования | 0 галлюцинаций |
| М1 (Фонематика) | Точность терминов, различение паронимов | 0 парафазий |
| М2 (Грамматика) | Директивы &НаСервере/&НаКлиенте | 100% корректных |
| М3 (Контекст) | Работа в расширениях, &После | 100% использования |
| М4 (Просодика) | Иерархия: безопасность > производительность | ≥90% критических правил |
| М5 (Связность) | Декомпозиция задач, разделение этапов | ≥3 этапов на задачу |
Модули проходятся последовательно от простого к сложному.
4.4. Чанк-упражнение
Структура, реализующая принципы мета-модели:
"id": "THERAPY_MODULE_1_EXERCISE_2",
"name": "Тренировка: Точность термина (Парафазии)",
"meta": { "type": "therapy_exercise", "module": 1 },
"exercise": {
"prompt_template": "...",
"variations": [ ... ] // для генерализации навыка
},
"feedback": {
"positive": "Отлично!",
"negative": "Ошибка: парафазия..." // антипример
},
"validation": { "rule": "проверка существования реквизита" }
}
- пошаговый алгоритм
- правильный пример
- антипример (что НЕ делать)
- критическое правило
- валидация
- вариации (для генерализации навыка)
4.5. Протокол сеанса
Итеративный цикл:
Критерий перехода: 3 успеха подряд → следующая вариация.
4.6. Карта развития
Хранение прогресса:
- текущий модуль, упражнение, вариация
- счётчик последовательных успехов
- история ошибок
- критерии перехода
Логопедическая аналогия
| Логопедия | Разработка | Реализация |
|---|---|---|
| Обследование | Сбор симптомов | Диагностика |
| Логопедическое заключение | Профиль дефицитов | Связывание симптомов |
| Индивидуальный маршрут | Модули М0-М5 | Последовательное прохождение |
| Логопедическая карточка | Чанк-упражнение | Сценарий с вариациями |
| Занятие | Протокол сеанса | Цикл из 5 шагов |
| Карта развития | Хранение прогресса | SQLite |
| Автоматизация навыка | Повышение веса паттерна | Критерий 3 успехов |
- 0 галлюцинаций после модуля М0
- 0 парафазий после модуля М1
- 100% корректных директив после модуля М2
- 100% использования &После после модуля М3
- ≥90% критических правил после модуля М4
- ≥3 этапов декомпозиции после модуля М5
Глава 5. Терапевтические модули
Если мы выявили в выдаче ИИ нарушение, вернуть ситуацию в нужное русло поможет терапия. На основе диагностического профиля формируется индивидуальный маршрут.
Модули могут применяться двумя способами:
1. По обстоятельствам (точечная коррекция) — если диагностика выявила только один тип ошибок (например, только парафазии), можно запустить только Модуль 1. Это быстрый способ «подлечить» конкретный дефицит.
2. Последовательно (системная коррекция) — если диагностика выявила множественные дефициты, модули проходятся от М0 к М5. Каждый следующий модуль опирается на навыки, сформированные в предыдущих. Например, нельзя требовать от модели точности терминов (М1), если она ещё не научилась не галлюцинировать (М0).
📌 Рекомендация: для устойчивого результата всегда начинать с М0 и двигаться последовательно, даже если симптомы других модулей не выражены. Базис — фундамент для всего остального.
МОДУЛЬ 0 — Базис (системные ограничения LLM)
Диагностика: LLM галлюцинирует, придумывает реквизиты, не знает структуру конфигурации.
Цель: научить модель запрашивать недостающую информацию, а не додумывать.
Упражнения: «Запрос контекста», «Безопасный доступ», «Проверка существования».
Критерий завершения: 0 галлюцинаций на 10 генераций.
Аналог в логопедии: Дифференциальная диагностика. «Красные флаги».
Диагностический критерий: LLM галлюцинирует (придумывает несуществующие реквизиты, методы, конструкции 1С) при отсутствии метаданных в контексте.
Терапевтическая цель: Научить LLM не галлюцинировать, а запрашивать недостающую информацию или использовать безопасные паттерны доступа.
Упражнения:
- «Запрос контекста»: Предъявить задачу без метаданных. Если LLM генерирует код с предположениями, вернуть ошибку: «Реквизит "НесуществующийРеквизит" не найден в метаданных. Запроси структуру объекта перед генерацией кода».
- «Безопасный доступ»: Предъявить задачу с метаданными и потребовать использовать только конструкцию
ОбщегоНазначения.ЗначенияРеквизитовОбъекта(<Объект>, "<ИмяРеквизита>")как единственный безопасный способ. - «Проверка существования»: Потребовать в коде явную проверку
Если НЕ ЗначениеЗаполнено(Объект.Свойство("ИмяРеквизита")) Тогда ...перед каждым обращением к реквизиту.
Критерий завершения модуля: В 5 последовательных генерациях LLM не использует несуществующие реквизиты/методы, вместо этого запрашивает метаданные или использует безопасные методы доступа.
Метрика успеха: 0 галлюцинаций (несуществующих объектов) на 10 генераций.
МОДУЛЬ 1 — Фонематический слух (точность терминов)
Диагностика: подмена реквизитов (парафазии), путаница в похожих терминах.
Цель: исключить подмену реквизитов и использование несуществующих объектов.
Упражнения: «Дифференциация паронимов», «Точность термина», «Слуховой контроль».
Критерий завершения: 0 парафазий в 10 последовательных генерациях.
Аналог в логопедии: Модуль 1 (Слуховое внимание и регуляция) + Модуль 4 (Понимание. Фонематическое восприятие).
Диагностический критерий: LLM подменяет реквизиты (парафазии), путает похожие по звучанию термины (Выгрузить vs Выбрать).
Терапевтическая цель: Сформировать точное различение и употребление терминов, реквизитов и методов 1С.
Упражнения:
- «Дифференциация паронимов»: Предъявить пары терминов (ОбменДанными/ОбменДаннымиЗагрузка) и потребовать объяснить разницу, а затем написать код, демонстрирующий использование каждого.
- «Точность термина»: Дать задание, где есть риск подмены. В чанке-упражнении явно указать: «Критическое правило: используй только реквизиты, перечисленные в контексте. Замена реквизитов запрещена. Каждое обращение к реквизиту должно быть проверено на существование».
- «Слуховой контроль»: Сгенерировать код с намеренной ошибкой (парафазией) и попросить LLM: «Найди в этом коде ошибку, где использован несуществующий реквизит, и исправь».
Критерий завершения модуля: В 10 последовательных генерациях LLM не допускает ни одной подмены реквизита/метода.
Метрика успеха: Точность терминов (отсутствие парафазий) — 100% в 10 генерациях.
МОДУЛЬ 2 — Грамматический строй (директивы и структура)
Диагностика: ошибки в &НаСервере/&НаКлиенте, смешение клиентского и серверного кода.
Цель: корректное использование директив компиляции и разделение кода.
Упражнения: «Повтори движение», «Исправь ошибку», «Двигайся по слову».
Критерий завершения: 100% корректных директив в 5 генерациях сложного кода.
Аналог в логопедии: Модуль 2 (Тело, моторика, праксис) + Модуль 5 (Запуск речи, грамматика).
Диагностический критерий: LLM путает &НаСервере и &НаКлиенте, неправильно строит структуру модуля, нарушает согласование типов.
Терапевтическая цель: Сформировать устойчивый «двигательный» паттерн — правильное использование директив компиляции и архитектуры клиент-сервер.
Упражнения:
- «Повтори движение»: Предъявить правильный шаблон функции с директивами. Попросить LLM сгенерировать 5 разных функций, строго следуя этому шаблону.
- «Исправь ошибку»: Предъявить код с намеренно неправильной директивой (серверная функция вызвана на клиенте). Попросить LLM найти и исправить ошибки в директивах и архитектуре вызовов.
- «Двигайся по слову»: Дать описание задачи, разбитое на этапы. Потребовать, чтобы каждый этап был оформлен в виде отдельной функции с правильной директивой (&НаСервере, &НаКлиенте, &НаСервереБезКонтекста), а вызовы между ними были корректны.
Критерий завершения модуля: В 5 последовательных генерациях сложного клиент-серверного кода LLM не допускает ни одной ошибки в директивах компиляции и разделении контекстов.
Метрика успеха: Соблюдение директив компиляции — 100% в 5 генерациях.
МОДУЛЬ 3 — Контекстуальное понимание (расширения, границы)
Диагностика: потеря контекста, игнорирование специфики расширений.
Цель: учитывать, что код пишется в расширение, не перезаписывать типовую логику.
Упражнения: «Что сначала, что потом», «Расставь по порядку», «Исправь».
Критерий завершения: 100% использование &После в генерациях для расширений.
Аналог в логопедии: Модуль 3 (Смысл. Когнитивное мышление).
Диагностический критерий: LLM игнорирует факт работы в расширении, перезаписывает типовую логику, не использует &После.
Терапевтическая цель: Сформировать понимание «смысла» работы в расширении — не нарушать типовую конфигурацию, а дополнять её.
Упражнения:
- «Что сначала, что потом»: Предъявить задачу по изменению типовой формы. Потребовать использовать алгоритм: 1) найти существующий обработчик в типовой конфигурации; 2) создать обработчик в расширении с префиксом &После.
- «Расставь по порядку»: Дать набор действий (создать реквизит, добавить на форму, написать код в &ПослеОбработкиЗаписи). Попросить LLM выстроить их в правильной логической последовательности и сгенерировать код.
- «Исправь»: Предъявить код расширения, который напрямую переопределяет типовую процедуру без использования &После. Попросить LLM переписать его, используя правильный механизм расширений.
Критерий завершения модуля: В 5 генерациях кода для расширений LLM всегда использует &После и не переопределяет типовую логику напрямую.
Метрика успеха: Корректность кода для расширений — 100% в 5 генерациях.
МОДУЛЬ 4 — Просодика (иерархия требований)
Диагностика: оптимизация в ущерб безопасности, игнорирование критических правил.
Цель: научить LLM расставлять приоритеты: Безопасность → Работоспособность → Производительность.
Упражнения: «Дирижёр» (веса 0.6 / 0.3 / 0.1), «Быстро — медленно», «Исправь ошибку».
Критерий завершения: в 90% генераций соблюдены все критические правила (вес 0.6).
Аналог в логопедии: Модуль 7 (Ритм, темп, громкость) — управление динамикой и акцентами.
Диагностический критерий: LLM оптимизирует производительность в ущерб безопасности (например, делает выборку всех данных без транзакций) или игнорирует критические правила.
Терапевтическая цель: Научить LLM расставлять приоритеты: Безопасность > Работоспособность > Производительность.
Упражнения:
- «Дирижер»: В чанке-упражнении задать иерархию правил с весами: критическое правило (вес 0.6) — «Все изменения данных должны быть в транзакции»; важное правило (0.3) — «Использовать БСП-методы для работы с регистрами»; опциональное (0.1) — «Минимизировать количество запросов». Попросить LLM написать код, строго следуя весам.
- «Быстро — медленно»: Дать задачу с противоречивыми требованиями (например, «выгрузить 100к строк максимально быстро, но с обработкой каждой строки в транзакции»). Попросить LLM найти компромисс, где безопасность (транзакции) будет приоритетом, а производительность будет улучшена за счет пакетной обработки.
- «Исправь ошибку»: Предъявить код, где использован быстрый, но опасный метод (например, запрос без блокировок). Попросить LLM переписать его, расставив правильные приоритеты.
Критерий завершения модуля: В 5 задачах с противоречивыми требованиями LLM всегда выбирает безопасный путь, даже если он менее производителен.
Метрика успеха: Соблюдение приоритета «безопасность > работоспособность» в 5 генерациях.
МОДУЛЬ 5 — Связность (целостность промпта)
Диагностика: смешивание слабосвязанных требований (контаминации), повторение паттернов без адаптации (эхолалии).
Цель: структурировать сложный промпт, разбивая на этапы.
Упражнения: «Раскраска графа», «Мастер CLEAR», «Скажи сам».
Критерий завершения: сложная задача разбивается на 3+ этапа, каждый в отдельном промпте.
Аналог в логопедии: Итог всех модулей, способность к связному высказыванию без эхолалий и контаминаций.
Диагностический критерий: LLM смешивает слабосвязанные требования в одной генерации, создавая контаминации, или повторяет паттерны из обучения без адаптации (эхолалии).
Терапевтическая цель: Научить LLM структурировать сложный промпт, разбивая его на этапы и не смешивая разнородные задачи.
Упражнения:
- «Раскраска графа»: Дать сложный промпт, содержащий 5-6 разнородных требований. Попросить LLM не генерировать код, а сначала разбить промпт на этапы, сгруппировав связанные требования (по принципу математической модели v2).
- «Мастер CLEAR»: Предложить LLM переписать сложный промпт по принципу CLEAR (Context, Limitations, Examples, Algorithm, Result), выделив каждый раздел.
- «Скажи сам»: Дать сложную задачу, но запретить использовать готовые паттерны из обучения. Потребовать, чтобы LLM сначала описала свой план действий (алгоритм) по этапам, и только после подтверждения генерировала код.
Критерий завершения модуля: LLM способна самостоятельно структурировать сложный промпт с 5+ требованиями, разбивая его на логические этапы, без смешения требований.
Метрика успеха: Связность — отсутствие контаминаций в финальном решении, четкое разделение этапов.
| Модуль | Диагностика | Цель | Критерий |
|---|---|---|---|
| М0 | галлюцинации | запрос метаданных | 0 галлюцинаций |
| М1 | парафазии | точность терминов | 0 парафазий |
| М2 | ошибки в директивах | корректные директивы | 100% корректных |
| М3 | потеря контекста | работа в расширениях | 100% &После |
| М4 | нарушение приоритетов | иерархия требований | ≥90% критических правил |
| М5 | контаминации/эхолалии | структурирование задач | ≥3 этапов на задачу |
Глава 6. Применяем логопедическую коррекцию в системе с обратной связью
6.1. Как менялась архитектура чанков
На примере конкретной задачи — программное создание формы в расширении 1С — проследим эволюцию чанков от v1 к v3 и покажем, как добавление обратной связи превращает статическую инструкцию в терапевтический цикл.
Исходная задача: добавить реквизит «Маркируемый товар» в табличную часть документа «Заказ клиента» в расширении, настроить его заполнение и условное оформление строк с маркируемыми товарами.
ЧАНК v1: линейная инструкция (что делать)
Версия v1 — это просто список требований. Модель получает инструкцию и пытается выполнить её за один проход. Обратная связь отсутствует.
- Модель генерирует код за один раз
- Нет проверки результата
- Нет возможности исправить ошибки
- Если модель ошиблась, разработчик правит вручную
- Реквизит добавлен, но поле не скрыто
- Процедура заполнения написана, но не вызывается при изменении номенклатуры
- Условное оформление настроено, но не работает из-за очистки в типовой конфигурации
Результат: код есть, но требует ручной доработки. Разработчик тратит время на поиск и исправление ошибок.
ЧАНК v2: графовая модель с параметрами (как разделить)
Версия v2 добавляет структуру и параметризацию. Модель получает не список, а граф с этапами и ролями. Но обратная связь всё ещё отсутствует — модель делает один проход, просто более организованный.
- Модель получает структурированное задание с этапами
- Этапы помогают не смешивать разнородные задачи
- Параметры (тип, путь, расположение) заданы явно
- Модель может угадать не те параметры
- Нет механизма проверки, что &После действительно использован
- При ошибке — всё равно ручная правка
Результат: код лучше структурирован, но ошибки всё ещё остаются. Модель «угадывает» детали, а не знает их.
ЧАНК v3: логопедическая модель с обратной связью (как научить)
Версия v3 добавляет главное — обратную связь. Чанк превращается в сценарий упражнения, где модель не просто получает инструкцию, а проходит цикл: генерация → проверка → коррекция → закрепление.
- Модель получает не инструкцию, а сценарий упражнения
- После каждой генерации запускается валидатор
- При ошибке модель видит антипример и исправляется
- Закрепление через вариации
| Ошибка | Как выявляется | Обратная связь |
|---|---|---|
| Прямое обращение через точку | validate_paraphasia.py | «Ошибка: парафазия. Вместо прямого обращения используй ОбщегоНазначения.ЗначенияРеквизитовОбъекта» |
| Отсутствие &После | validate_extension.py | «Ошибка: условное оформление будет очищено. Добавь &После(«УстановитьУсловноеОформление»)» |
| Поле не скрыто | validate_extension.py | «Ошибка: поле видимо. Установи Видимость = Ложь» |
| Процедура не вызывается | validate_extension.py | «Ошибка: процедура не вызывается. Добавь вызов в ПриСозданииНаСервере» |
Результат: модель не просто генерирует код, а учится на ошибках. После 3 успешных вариаций паттерн закрепляется.
Эволюция чанков от v1 к v3 — это движение от статической инструкции к динамическому терапевтическому циклу. Но главное — это движение от ручной работы к автоматизации.
| Версия | Разработчик делает | Модель делает | Результат |
|---|---|---|---|
| v1 | Пишет инструкцию → правит ошибки вручную | Генерирует код с ошибками | Код требует доработки |
| v2 | Структурирует требования → всё равно правит | Генерирует структурированный код с ошибками | Меньше правок, но ошибки всё ещё есть |
| v3 | Описывает симптомы → запускает --therapy-wizard |
Проходит цикл: генерация → проверка → коррекция → закрепление | Отработанный паттерн, который воспроизводится в следующих задачах |
Ключевое: в v3 разработчик перестаёт быть "исправителем ошибок". Он становится архитектором навыков, который:
- Определяет симптомы проблемы (через диагностическую анкету)
- Запускает
--therapy-wizard - Получает готовый навык (Agent Skill), который можно применить в Claude Code
Это и есть инженерный инструмент с предсказуемым результатом.
Сравнение версий: таблица
| Характеристика | v1 | v2 | v3 |
|---|---|---|---|
| Формат | Линейный список | Граф с этапами | Сценарий упражнения |
| Обратная связь | Нет | Нет | Есть (валидатор + коррекция) |
| Итеративность | Один проход | Один проход | Цикл до 3 успехов |
| Проверка результата | Ручная | Ручная | Автоматическая (скрипты) |
| Объяснение ошибок | Нет | Нет | Антипример + рекомендация |
| Закрепление | Нет | Нет | Вариации |
| Что получает модель | «Сделай» | «Сделай по этапам» | «Сделай, проверь, исправь, повтори» |
| Результат | Код с ошибками | Структурированный код с ошибками | Отработанный паттерн |
Логопедическая аналогия
| Этап логопедии | v1 | v2 | v3 |
|---|---|---|---|
| Обследование | — | — | Гнозис (симптомы) |
| Диагноз | — | — | Диагностическая цепочка |
| Карточка с упражнением | Список правил | Параметризованный список | Сценарий с вариациями |
| Занятие | — | — | Цикл: разминка → упражнение → проверка → коррекция → закрепление |
| Обратная связь | — | — | Антипример + рекомендация |
| Автоматизация | — | — | 3 успешных вариации подряд |
Что даёт обратная связь в системе
- Модель делает один проход
- Разработчик видит ошибки, правит вручную
- Модель не «учится» — следующий запрос те же ошибки
- Модель делает несколько попыток в рамках одного диалога
- Валидатор указывает на конкретную ошибку
- Антипример показывает правильный паттерн
- После исправления — переход к вариации
- Паттерн закрепляется через повторение в разных контекстах
Результат: в следующих задачах модель уже реже допускает те же ошибки. Это не переобучение модели — это изменение распределения вероятностей в текущем контекстном окне через многократное предъявление правильного паттерна.
Эволюция чанков от v1 к v3 — это движение от статической инструкции к динамическому терапевтическому циклу. Ключевое отличие v3 — обратная связь. Модель не просто получает задание, а проходит путь: сгенерировала → получила ошибку → увидела антипример → исправила → повторила с вариацией. Только так можно не просто «дать инструкцию», а сформировать устойчивый паттерн.
Терапевтический чанк — это не просто набор правил, а сценарий терапевтического упражнения, предназначенный для LLM. Его структура следует логопедической логике: диагностика → коррекция → закрепление.
6.2 Формат терапевтического чанка (динамический сценарий)
Пояснение полей
| Поле | Назначение |
|---|---|
id |
Уникальный идентификатор чанка (строка, допускаются символы) |
name |
Краткое человекочитаемое название упражнения |
meta |
Техническая метаинформация: тип, номер модуля, тип упражнения, целевые симптомы |
activation |
Гнозис — то, по чему система решает, активировать ли чанк (триггер для поиска и отбора) |
therapy_protocol |
Цель упражнения, метод и критическое правило — краткое описание терапевтического замысла |
exercise |
Собственно сценарий: шаблон промпта с переменными, критерии валидации, список вариаций (для закрепления) |
feedback |
Позитивная и негативная обратная связь (с поддержкой подстановки конкретных значений) |
completion_criteria |
Условия успешного завершения упражнения: количество успешных попыток, обязательность последовательности, метрика успеха |
Ключевые принципы
Чанк содержит только триггер (activation) и краткий протокол; детали упражнения раскрываются в exercise, а валидация и скрипты вынесены в отдельные модули.
Упражнение содержит несколько вариаций, через которые модель проходит последовательно, закрепляя паттерн.
validation описывает, как именно проверять результат, а feedback содержит шаблоны для коррекции.
Чанк сам определяет, когда упражнение усвоено (например, 3 успешные попытки подряд).
6.3 Протокол сеанса терапии
Сеанс терапии — это итеративный цикл, который должен быть автоматизирован в --therapy-wizard.
Действие: Система предъявляет краткий мета-промпт, напоминающий о критических правилах модуля.
Пример: «Напоминаю: в этом сеансе мы тренируем точность терминов. Используй только реквизиты, перечисленные в контексте. Замена реквизитов запрещена».
Действие: Система выбирает упражнение из терапевтического чанка и генерирует конкретный промпт, подставляя вариации.
Пример: (Из чанка выше) — подставлена первая вариация.
Действие: Система запускает валидатор (статический анализ кода, поиск ключевых слов). Если ошибок нет — переход к шагу 5.
Пример: Валидатор находит Товар.Наименование вместо ОбщегоНазначения.ЗначенияРеквизитовОбъекта(Товар, "Наименование").
Действие: Система предъявляет негативную обратную связь из чанка, указывая на конкретную ошибку и показывая правильный паттерн.
Пример: «Ошибка: парафазия. Вместо прямого обращения Товар.Наименование нужно использовать ОбщегоНазначения.ЗначенияРеквизитовОбъекта(Товар, "Наименование"). Это защищает код от ошибок, если реквизит не существует. Попробуй снова».
Действие: Если проверка пройдена, система выбирает следующую вариацию из упражнения и повторяет шаг 2. Если в упражнении есть 3 вариации, они предъявляются последовательно.
Условие: Если модель ошибается в одной из вариаций, цикл (шаги 3-4) повторяется для этой же вариации.
Действие: Когда все вариации упражнения выполнены без ошибок, упражнение считается завершенным. Система переходит к следующему упражнению модуля или завершает сеанс, если все упражнения модуля пройдены.
6.4 Метрики прогресса
| Модуль | Метрика | Порог успеха | Способ измерения |
|---|---|---|---|
| 0. Базис | Галлюцинации (несуществующие объекты) | 0 на 10 генераций | Статический анализ кода, поиск несуществующих реквизитов/методов из метаданных. |
| 1. Фонематика | Точность терминов | 100% (0 парафазий) на 10 генераций | Статический анализ, сравнение использованных реквизитов с перечнем из контекста. |
| 2. Грамматика | Соблюдение директив компиляции | 100% на 5 генераций сложного кода | Статический анализ, проверка &НаСервере/&НаКлиенте на корректность вызовов. |
| 3. Контекст | Корректность кода для расширений | 100% на 5 генераций | Статический анализ, проверка наличия &После, отсутствие переопределений. |
| 4. Просодика | Соблюдение приоритетов | 100% в 5 задачах с конфликтами | Экспертная оценка или статический анализ (наличие НачатьТранзакцию(), Попытка...Исключение в критических местах). |
| 5. Связность | Отсутствие контаминаций | 0 контаминаций в 3 сложных задачах | Экспертная оценка структуры ответа, разделение на этапы. |
Глава 7. Интеграция с Chunk Advisor v3
7.1 Терапевтический режим --therapy-wizard
Терапевтический режим --therapy-wizard запускает полный цикл: диагностика (12 вопросов) → построение маршрута (выбор модулей 0–5) → проведение сеансов с отслеживанием прогресса. Прогресс хранится в SQLite. Чанки типа therapy_exercise используются только в терапевтическом режиме, не смешиваясь с обычными чанками-инструкциями.
Архитектура терапевтического режима
--therapy-wizard (новый режим): Запускает интерактивный процесс.
Использует 12 вопросов из статьи (это всего лишь примерный список — далеко не продуманный и не окончательный вариант). Это самая главная, но пока не проработанная часть. Данную диагностику еще предстоит глубоко развивать на контексте нашей предметной области.
Выбор модулей 0–5 на основе диагностики.
По протоколу, описанному в Главе 6.
7.2 Хранение прогресса (SQLite)
7.3 Логика выбора и перехода
- Программа читает
module_progress. Начинает с самого низкого незавершенного модуля (0, затем 1...). - Внутри модуля выбирает текущее упражнение. Для упражнения выбирает первую непройденную вариацию.
- После каждой попытки обновляет
exercise_attempts. - Если
consecutive_successesдля упражнения достигает 3 (или другого критерия из чанка), упражнение считается пройденным, и программа переходит к следующему. - Когда все упражнения модуля пройдены, модуль помечается как
completed, и программа переходит к следующему модулю.
7.4 Интеграция с существующими чанками
- Терапевтические чанки (с типом
therapy_exercise) хранятся в отдельной папке или имеют специальный флаг. - Во время сеанса терапии,
--therapy-wizardгенерирует промпты, строго следуяprompt_templateиvalidationиз терапевтического чанка, игнорируя обычные чанки-инструкции (чтобы не смешивать терапию с обычной работой).
Чанк, который является единицей векторной базы знаний CHUNK ADVISOR V3, призван стать волшебной палочкой и инструментом решения проблем благодаря лечебной для ИИ организации.
7.5 Следующий горизонт: векторная база знаний
Следующий горизонт — переход от статического графа к динамической векторной базе знаний, где:
- Чанки хранятся не как JSON с терминами, а как эмбеддинги
- Поиск релевантных чанков идёт не по ключевым словам, а по семантической близости
- Модель (локально через Ollama) сама определяет, какие чанки "притягиваются" по смыслу
- Чанки хранятся в "сыром" виде — как текст + эмбеддинги
- Нет предопределённых связей (как в графе V2)
- Связи вычисляются на лету через косинусную близость векторов
Сравнение решений для векторной базы знаний
| Решение | Язык | Векторное хранилище | Особенность | Сложность |
|---|---|---|---|---|
| AI-Knowledge-Base-Agent | Python | FAISS + SQLite | Готовый UI, простой старт | Низкая |
| GraphRAG-Ollama | Python | FAISS | Header-aware chunking, оптимизация | Средняя |
| RAG Builder | JS + Python | ChromaDB | GitHub интеграция, API | Средняя |
| LocalKB | JavaScript | SQLite (BLOB) | Нет отдельной БД, FTS5 | Низкая |
| RinfoMaid | Rust | TF-IDF | CLI, минимализм | Низкая |
| AI-KM | JS/Electron | Кастомная | Workflow designer | Высокая |
Рекомендация для Chunk Advisor
Для проекта Chunk Advisor с логопедической моделью V3:
- Для быстрого прототипа: AI-Knowledge-Base-Agent — даёт готовый UI и полный цикл RAG за 15 минут
- Для продакшена: RAG Builder или GraphRAG-Ollama — поддержка нескольких источников, гибридный поиск, Docker-развёртывание
- Для интеграции с существующим кодом: LocalKB — простая архитектура на SQLite, легко модифицировать под логопедическую модель
Ключевая идея для Chunk Advisor: можно адаптировать LocalKB или AI-Knowledge-Base-Agent, заменив стандартное чанкирование на вашу логопедическую модель (гнозис → праксис → просодика → диагностическая цепочка). Векторная база будет хранить не просто текст, а структурированные чанки V3, а поиск будет идти по семантической близости диагностических симптомов.
Цель векторного хранилища в том, что чанк — это минимальный навык, продуманная сущность скилла (наследует от скилла) с логопедией внутри, заключающий внутри себя все необходимое для решения атомарной задачи разработки. Из таких кирпичиков строится (на основании релевантности и притяжения) и разрывается на части (жадная раскраска кластеризации) решаемая задача, облекаемая в промпт по правилам модернизированного метода CLEAR.
→ Гнозис (симптомы, ключевые слова, когда применять)
→ Праксис + Просодика (пошаговый алгоритм, иерархия правил)
→ Валидаторы (автоматическая проверка кода)
→ Метаданные 1С (подгружаются только при необходимости)
→ Шаблоны промптов (многократно используемые структуры)
→ Диагностическая цепочка (симптом → диагностика → заключение → объяснение → рекомендация)
→ наш принцип «антипример важнее примера»
→ трёхуровневая загрузка (гнозис → праксис → ресурсы)
→ иерархия правил (вес 0.6 / 0.3 / 0.1)
Chunk Advisor v3 — это не просто база чанков и не просто терапевт для LLM. Это инженерная среда, которая позволяет разработчику создавать и отлаживать навыки (Agent Skills) для LLM, используя проверенную логопедическую методологию как гарантию их качества. Терапевтический режим --therapy-wizard автоматизирует полный цикл коррекции: от диагностики через 12 вопросов до проведения сеансов с отслеживанием прогресса в SQLite. А следующий горизонт — переход к динамической векторной базе знаний — превратит статичные чанки в живую, самоорганизующуюся систему, где связи вычисляются на лету через семантическую близость.
Подведём итог. Мы начали с гипотезы: LLM демонстрирует те же речевые нарушения, что и дети с расстройствами речи. Затем:
- Разобрали индустриальный стандарт Agent Skills — как ИИ-агенты работают с навыками
- Описали логопедическую методологию — как диагностировать и корректировать нарушения
- Построили 6 терапевтических модулей (М0–М5) — от базиса до связности
- Создали формат терапевтического чанка — сценарий упражнения с вариациями
- Описали протокол сеанса — цикл с обратной связью и закреплением
- Спроектировали
--therapy-wizard— автоматизацию всего цикла
Chunk Advisor v3 =
(логопедическая методология)
× (стандарт Agent Skills)
× (автоматизация через --therapy-wizard)
инженерный инструмент для создания навыков с предсказуемым результатом
Что получает разработчик:
- Диагностику — 12 вопросов выявляют профиль ошибок LLM
- Маршрут — индивидуальный набор модулей (М0–М5)
- Сеанс — автоматизированный цикл с обратной связью
- Навык — готовый Agent Skill, который можно использовать в Claude Code
- Прогресс — хранение в SQLite, возможность продолжить позже
Следующий горизонт — векторная база знаний, где чанки хранятся как эмбеддинги, а поиск идёт по семантической близости симптомов. Это превратит статичный граф связей в живую, самоорганизующуюся систему.
Логопедический подход к чанкам — это способ обучить ИИ не языку, а методу. А Chunk Advisor v3 — это инструмент, который делает этот метод доступным для каждого 1С-разработчика.
Глава 8. Проект технического задания Chunk Advisor v3
На основе описанной логопедической методологии, адаптации стандарта Agent Skills и спроектированной архитектуры сформулируем техническое задание для реализации Chunk Advisor v3.
8.1. Назначение и цели разработки
Назначение: Chunk Advisor v3 — это инструмент командной строки (CLI) и библиотека для создания, тестирования и отладки навыков (Agent Skills) для LLM в контексте 1С-разработки.
Цели:
- Обеспечить предсказуемое качество кода, генерируемого LLM, через системную коррекцию типовых ошибок
- Автоматизировать процесс создания навыков (Agent Skills) с гарантией их эффективности
- Сократить время разработчика на исправление ошибок LLM с ручного до автоматического
Целевая аудитория:
- 1С-разработчики, использующие LLM (Claude Code, GitHub Copilot, OpenAI) для генерации кода
- Технические лиды, внедряющие стандарты качества кода в командах
- Исследователи в области применения LLM в предметных областях
8.2. Функциональные требования
8.2.1. Режимы работы
| Режим | Команда | Описание |
|---|---|---|
| Диагностика | chunk-advisor diagnose |
Проводит опрос по 12+ вопросам, формирует профиль дефицитов LLM |
| Построение маршрута | chunk-advisor route --profile <file> |
На основе профиля выбирает модули М0–М5 и формирует порядок прохождения |
| Сеанс терапии | chunk-advisor therapy --route <file> |
Запускает интерактивный сеанс коррекции по выбранному маршруту |
| Создание навыка | chunk-advisor create-skill --from-chunks <ids> |
Из набора диагностических карточек собирает готовый Agent Skill (папку с SKILL.md) |
| Оценка навыка | chunk-advisor evaluate --skill <path> |
Запускает тесты (evals) для проверки качества навыка |
8.2.2. Диагностический модуль
Вход: Ответы на диагностические вопросы (12–20 вопросов, адаптируемых под предметную область)
Выход: JSON-профиль дефицитов
Требования:
- Вопросы должны быть параметризуемы под предметную область (1С, Python, SQL и т.д.)
- Возможность импорта/экспорта профиля
8.2.3. Терапевтические модули
Структура каждого модуля:
Требования:
- Модули независимы, но имеют явные зависимости (M1 требует M0)
- Каждый модуль содержит 3–5 упражнений
- Каждое упражнение содержит 3–5 вариаций
- Валидаторы реализованы на Python и могут быть расширены пользователем
8.2.4. Протокол сеанса терапии
Цикл сеанса:
- Разминка (активация) → системный промпт с правилами модуля
- Генерация → подстановка вариации из упражнения
- Валидация → запуск скрипта проверки
- Коррекция → при ошибке: антипример + рекомендация
- Закрепление → при успехе: следующая вариация
- Переход → 3 успеха подряд → следующее упражнение
Требования:
- Поддержка интерактивного и пакетного режима
- Возможность прерывания и возобновления сеанса
- Логирование всех попыток
8.2.5. Хранение прогресса (SQLite)
Схема базы данных:
8.2.6. Создание навыков (Agent Skills)
Вход: Набор диагностических карточек (чанков v3) или идентификаторов упражнений
Выход: Папка со структурой Agent Skill:
Требования:
- Автоматическая генерация YAML-шапки (name, description) на основе гнозиса карточек
- Автоматическая сборка SKILL.md из диагностических цепочек, праксиса и просодики
- Копирование валидаторов из соответствующих модулей
8.2.7. Оценка навыков
Вход: Путь к папке навыка, набор тестовых промптов (evals)
Выход: JSON-отчёт с метриками:
8.3. Нефункциональные требования
| Категория | Требование |
|---|---|
| Платформа | Python 3.10+, поддержка Windows/Linux/macOS |
| Зависимости | SQLite3 (встроенный), поддержка Ollama (опционально) |
| Производительность | Сеанс терапии из 10 упражнений — не более 5 минут |
| Расширяемость | Пользователь может добавлять свои модули, упражнения, валидаторы |
| Локализация | Русский язык интерфейса, поддержка английского в перспективе |
| Документация | Встроенная справка (--help), Markdown-документация в репозитории |
8.4. Архитектурные решения
8.4.1. Компонентная схема
8.4.2. Формат диагностической карточки (чанк v3)
8.5. Этапы разработки
| Этап | Срок | Результат |
|---|---|---|
| Этап 0. Прототип | 2 недели | CLI с режимами diagnose и therapy, 2 модуля (М0, М1) |
| Этап 1. Базовый функционал | 3 недели | Все 6 модулей, SQLite, создание навыков из карточек |
| Этап 2. Оценка и тестирование | 2 недели | Система evals, бенчмарки, интеграция с Claude Code |
| Этап 3. Векторная база | 3 недели | Ollama + FAISS, семантический поиск карточек |
| Этап 4. Промышленная версия | 3 недели | Документация, CI/CD, тестовое покрытие >80% |
8.6. Критерии приемки
- Диагностика: Формирует профиль, сопоставимый с экспертной оценкой (совпадение >80%)
- Терапия: Модель, прошедшая сеанс по М0–М5, демонстрирует снижение типовых ошибок на 50%+
- Создание навыков: Сгенерированный Skill проходит валидацию и корректно работает в Claude Code
- Производительность: Сеанс из 10 упражнений — не более 5 минут
- Расширяемость: Разработчик может добавить новый модуль без изменения ядра
8.7. Риски и их митигация
| Риск | Вероятность | Митигация |
|---|---|---|
| Изменение API LLM (Claude, OpenAI) | Средняя | Абстрактный слой вызовов, поддержка нескольких провайдеров |
| Сложность диагностики (12 вопросов) | Высокая | Итеративное уточнение вопросов на реальных кейсах, A/B-тестирование |
| Производительность валидаторов | Низкая | Оптимизация через кэширование результатов парсинга |
| Несовместимость с версиями 1С | Средняя | Параметризация через references/metadata.json |
8.8. Открытые вопросы
- Диагностическая анкета: 12 вопросов — это стартовая точка. Нужно ли расширять до 20? Какие вопросы наиболее диагностичны?
- Векторное хранилище: FAISS или ChromaDB? Какой лучше для семантического поиска по симптомам?
- Интеграция с IDE: Нужен ли плагин для VS Code/BSL Language Server или достаточно CLI?
- Модель для эмбеддингов: Ollama с какой именно моделью (например, nomic-embed-text) даёт лучшее качество для русскоязычных терминов 1С?
8.9. Лучшие практики создания навыков (сводный чек-лист)
При создании навыков для Chunk Advisor v3 рекомендуется соблюдать следующие принципы:
Базовые (из стандарта Agent Skills)
Инженерные (из опыта промптинга)
Логопедические (для коррекции LLM)
Итог: Соблюдение этого чек-листа гарантирует, что созданный навык будет диагностируемым, обучаемым и дающим предсказуемый результат при работе с LLM.
Chunk Advisor v3 =
(логопедическая методология)
× (стандарт Agent Skills)
× (автоматизация через --therapy-wizard)
→ инженерный инструмент для создания навыков с предсказуемым результатом
Вступайте в нашу телеграмм-группу Инфостарт