gennady 0.6.0 → 0.7.0

package/dist/ai/docs/ai-promting.md

@@ -0,0 +1,572 @@
+<Module_ID id="PROMPTING_FOR_PROGRAMMING_2026" />
+
+# AI Prompting
+
+## Модуль 1. Дерево prompt-архитектуры для программирования
+
+- **Суть:** Для инженерных задач prompt лучше строить не как произвольный текст, а как стек управляющих слоев: краткий priming, цель, контекст, аксиомы, критерии качества, примеры, контракт ответа и проверка.
+- **Ресерч:** [Language Models are Few-Shot Learners](https://arxiv.org/abs/2005.14165), [Rethinking the Role of Demonstrations: What Makes In-Context Learning Work?](https://aclanthology.org/2022.emnlp-main.759), [What Makes Good In-Context Examples for GPT-3?](https://aclanthology.org/2022.deelio-1.10), [Chain-of-Thought Prompting Elicits Reasoning in Large Language Models](https://arxiv.org/abs/2201.11903), [Large Language Models Might Not Care What You Are Saying: Prompt Format Beats Descriptions](https://aclanthology.org/2025.findings-emnlp.3/).
+
+## Модуль 2. Belief State, аксиомы и критерии вознаграждения
+
+- **Суть:** Устойчивые правила проекта, acceptance criteria и rubric полезны как prompt-level замена неявным ожиданиям. Но их нельзя подавать как реальную инъекцию reward function внутрь модели.
+- **Ресерч:** [Constitutional AI: Harmlessness from AI Feedback](https://arxiv.org/abs/2212.08073), [Role play with large language models](https://www.nature.com/articles/s41586-023-06647-8), [Large Language Models Might Not Care What You Are Saying: Prompt Format Beats Descriptions](https://aclanthology.org/2025.findings-emnlp.3/).
+
+## Модуль 3. Golden Examples, anti-examples и retrieval
+
+- **Суть:** Сильный пример остается одним из самых надежных способов задать качество кода, формат reasoning и границы допустимого поведения. Пример должен быть репрезентативным, а не декоративным.
+- **Ресерч:** [Language Models are Few-Shot Learners](https://arxiv.org/abs/2005.14165), [What Makes Good In-Context Examples for GPT-3?](https://aclanthology.org/2022.deelio-1.10), [Rethinking the Role of Demonstrations: What Makes In-Context Learning Work?](https://aclanthology.org/2022.emnlp-main.759), [Many-Shot In-Context Learning](https://arxiv.org/abs/2404.11018).
+
+## Модуль 4. Verification Loops, self-feedback и coding tasks
+
+- **Суть:** Для программирования полезно не только сгенерировать решение, но и принудительно прогнать модель через цикл проверки: план, реализация, тесты, critique, исправление.
+- **Ресерч:** [Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.17651), [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366), [STaR: Self-Taught Reasoner Bootstrapping Reasoning With Reasoning](https://arxiv.org/abs/2203.14465).
+
+## Модуль 5. Длинный контекст, навигация и layout
+
+- **Суть:** На длинных coding-prompts важны порядок секций, явные границы между правилами и данными, а также близость критичных ограничений к месту применения.
+- **Ресерч:** [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172), [What Makes a Good Order of Examples in In-Context Learning](https://aclanthology.org/2024.findings-acl.884), [Large Language Models Might Not Care What You Are Saying: Prompt Format Beats Descriptions](https://aclanthology.org/2025.findings-emnlp.3/).
+
+---
+
+### Общая картина
+
+Для программиста prompt полезно понимать как временную архитектуру управления моделью. Он не заменяет обучение, но может временно:
+
+- сузить задачу;
+- закрепить локальные правила проекта;
+- задать критерии качества;
+- показать эталон;
+- организовать самопроверку;
+- связать решение с тестами и acceptance criteria.
+
+Самый полезный способ думать об этом такой: prompt не "переобучает" модель, а создает **inference-time scaffold** поверх уже имеющихся весов.
+
+Это важная граница fact-check:
+
+- **Да:** prompt может заметно менять поведение модели.
+- **Да:** prompt может имитировать некоторые паттерны из instruction tuning, preference training и self-critique.
+- **Нет:** prompt не превращается в настоящее SFT или RL.
+- **Нет:** нельзя честно писать, что мы прямо "внедрили reward function в веса" во время одного запроса.
+
+---
+
+<Module_ID id="MOD_PROMPT_01_TREE_2026" />
+
+# Модуль 1. Дерево prompt-архитектуры для программирования
+
+### Базовое дерево
+
+```text
+Prompt for Coding
+├── 1. Short Priming
+│   ├── Кто мы и в каком режиме работаем
+│   └── Какой тип задачи решаем
+├── 2. Goal
+│   ├── Что нужно сделать
+│   ├── Что считается готовым
+│   └── Что запрещено ломать
+├── 3. Context
+│   ├── Кодовая база / файлы / diff
+│   ├── Ограничения среды
+│   └── Зависимости и интерфейсы
+├── 4. Belief State / Axioms
+│   ├── Неподвижные правила проекта
+│   ├── Инварианты
+│   └── Приоритеты качества
+├── 5. Reward Criteria
+│   ├── Acceptance criteria
+│   ├── Проверки / тесты / сигналы успеха
+│   └── Что считается плохим решением
+├── 6. Golden Example
+│   ├── Эталонный кусок кода или ответа
+│   └── Образец reasoning или review-format
+├── 7. Counter-Example
+│   ├── Что делать нельзя
+│   └── Как выглядит плохой выход
+├── 8. Output Contract
+│   ├── Формат ответа
+│   ├── Структура findings / patch / report
+│   └── Степень детализации
+└── 9. Verification Loop
+    ├── План
+    ├── Реализация
+    ├── Проверка
+    └── Исправление
+```
+
+### 1. Short Priming
+
+Короткий priming нужен не для магии, а чтобы сразу задать рабочий режим. Для coding-task это обычно 1-3 строки, а не полстраницы role-play.
+
+#### Пример
+
+```text
+Ты работаешь как инженерный агент по TypeScript-коду.
+Фокус: корректность, поведенческие регрессии, контракт API и тестируемость.
+Не подменяй задачу пересказом кода.
+```
+
+### 2. Goal
+
+Goal должен отвечать на три вопроса:
+
+- что изменить;
+- какой результат нужен;
+- по каким признакам задача считается закрытой.
+
+#### Пример
+
+```text
+Задача: исправить генерацию review-summary так, чтобы пустой diff не приводил к ложному finding.
+Готово, если: пустой diff дает пустой список findings; существующие сценарии не ломаются.
+```
+
+### 3. Context
+
+Контекст должен включать только то, что реально нужно для решения:
+
+- файлы;
+- API-контракты;
+- тесты;
+- инварианты;
+- ограничения среды.
+
+### 4. Belief State / Axioms
+
+Это блок стабильных правил, который задает локальную "конституцию" задачи:
+
+- не ломать публичный API;
+- не удалять тесты ради прохождения;
+- предпочитать минимальный патч;
+- логировать причину изменения;
+- считать backward compatibility приоритетом.
+
+### 5. Reward Criteria
+
+Это внешний proxy для качества. Он объясняет модели, какой выход выглядит как "успех", а какой как "провал".
+
+Для coding-task здесь полезны:
+
+- acceptance criteria;
+- expected tests;
+- failure modes;
+- rubric review-quality.
+
+### 6. Golden Example
+
+Golden example показывает не абстрактную цель, а конкретный сильный образец. Для программиста это особенно ценно, потому что можно задать:
+
+- стиль patch;
+- формат review finding;
+- структуру explanation;
+- тип JSDoc / type-contract;
+- формат commit message или changelog.
+
+### 7. Counter-Example
+
+Контрпример полезен, если у модели есть типовой плохой паттерн:
+
+- болтливый ответ вместо patch;
+- псевдо-review без реального риска;
+- нарушение schema;
+- удаление тестов;
+- переписывание половины модуля без необходимости.
+
+### 8. Output Contract
+
+Нужно явно задать, что именно вернуть:
+
+- patch;
+- findings;
+- JSON;
+- plan;
+- test matrix;
+- краткий инженерный отчет.
+
+### 9. Verification Loop
+
+Для code-task один проход часто слабее, чем цепочка:
+
+- сначала план;
+- потом изменение;
+- потом проверка;
+- потом краткое исправление после проверки.
+
+---
+
+### Научное подтверждение и Fact-Checking
+
+#### Прямо подтверждается:
+
+- Демонстрации, формат и организация prompt реально влияют на поведение модели: [Brown et al., 2020](https://arxiv.org/abs/2005.14165), [Min et al., 2022](https://aclanthology.org/2022.emnlp-main.759), [Tang et al., 2025](https://aclanthology.org/2025.findings-emnlp.3/).
+- Качество примеров критично для ICL: [Liu et al., 2022](https://aclanthology.org/2022.deelio-1.10).
+- Пошаговые reasoning scaffolds полезны на сложных задачах: [Wei et al., 2022](https://arxiv.org/abs/2201.11903).
+
+#### Косвенно подтверждается:
+
+- Prompt, организованный как стек слоев, обычно работает лучше, чем одна длинная свободная инструкция.
+- Для coding-task acceptance criteria и tests действуют как сильный направляющий сигнал.
+
+#### Не подтверждено / требует аккуратности:
+
+- Что существует одна каноническая prompt-структура для всех языков, моделей и задач.
+- Что длинный priming сам по себе усиливает качество.
+- Что tree-структура prompt автоматически лучше любого другого layout.
+
+---
+
+<Module_ID id="MOD_PROMPT_02_BELIEF_STATE_2026" />
+
+## Модуль 2. Belief State, аксиомы и критерии вознаграждения
+
+### Суть метода
+
+Самая полезная мысль из старого `ai-protocol` не в XML и не в псевдофизике attention, а в другом: модели полезно явно сказать, **какие правила здесь неподвижны** и **что считается хорошим результатом**.
+
+В документе для программиста это удобно разделить на два блока:
+
+1. `Belief State / Axioms` — что в этой задаче считается фундаментом.
+2. `Reward Criteria` — что именно увеличивает ценность ответа.
+
+### 1. Belief State / Axioms
+
+Это не "виртуальная архитектура сознания", а просто стабильный policy-block.
+
+#### Примеры аксиом для coding-task
+
+```text
+A1. Не ломай публичный контракт без явного запроса.
+A2. Не удаляй тесты ради прохождения.
+A3. Предпочитай минимальный патч перед широким рефакторингом.
+A4. Если причина бага не доказана, не утверждай ее как факт.
+A5. При конфликте между стилем и корректностью выигрывает корректность.
+```
+
+### 2. Reward Criteria
+
+Это слой про критерии успеха. Он особенно полезен для генерации кода, review и refactoring.
+
+#### Примеры reward criteria
+
+```text
+Положительный результат:
+- код проходит тесты;
+- патч минимален;
+- причина изменения объяснима;
+- edge cases покрыты.
+
+Негативный результат:
+- ломается backward compatibility;
+- исчезают проверки;
+- ответ уходит в пересказ вместо изменения;
+- решение не связано с acceptance criteria.
+```
+
+### 3. Что здесь реально подтверждается
+
+#### Прямо подтверждается:
+
+- Constitutional AI показывает, что набор принципов и self-critique/rule-based revision может быть использован как внешний источник управления поведением модели: [Bai et al., 2022](https://arxiv.org/abs/2212.08073).
+- Persona/rule framing действительно меняет выход модели: [Shanahan et al., 2023](https://www.nature.com/articles/s41586-023-06647-8).
+- Формат и rubric-like structure могут влиять на результат сильнее, чем длинные словесные описания: [Tang et al., 2025](https://aclanthology.org/2025.findings-emnlp.3/).
+
+#### Косвенно подтверждается:
+
+- Явные acceptance criteria и rubric работают как prompt-level proxy для preference optimization.
+- Аксиомы полезны как способ стабилизировать локальные инварианты проекта.
+
+#### Не подтверждено / требует аккуратности:
+
+- Что prompt буквально внедряет reward function в веса модели.
+- Что аксиомы в prompt запускают тот же механизм, что PPO/GRPO/RLAIF во время обучения.
+- Что достаточно один раз написать `следуй аксиомам`, и модель будет строго их соблюдать в любом длинном контексте.
+
+### 4. Эвристическая интерпретация LLM
+
+Это не научное доказательство, а рабочая модель интерпретации.
+
+Belief State полезен как способ уменьшить неопределенность локальной среды. Reward Criteria полезны как способ сделать видимым, какой ответ здесь статистически "выигрывает". Это похоже на имитацию элементов alignment-пайплайна, но только на уровне inference scaffolding, а не реального обучения.
+
+### 5. Практическая ценность для программиста
+
+- Если проект чувствителен к инвариантам, аксиомы лучше писать отдельно от task.
+- Acceptance criteria и tests нужно ставить не в конец как комментарий, а в центральную часть prompt.
+- Если важна минимальность патча, это надо объявлять явно.
+- Если важен review-mode, нужно задать, что именно считать finding, а что нет.
+
+---
+
+<Module_ID id="MOD_PROMPT_03_GOLDEN_EXAMPLES_2026" />
+
+## Модуль 3. Golden Examples, anti-examples и retrieval
+
+### Суть метода
+
+Golden example нужен тогда, когда модель должна не просто понять задачу, а воспроизвести конкретный качественный паттерн:
+
+- стиль решения;
+- глубину reasoning;
+- структуру code review;
+- способ оформления тестов;
+- формат миграции или changelog.
+
+### 1. Когда golden example действительно нужен
+
+#### Полезен:
+
+- для review findings;
+- для schema-bound output;
+- для JSDoc / contract style;
+- для тестов и BDD-сценариев;
+- для сложного доменного формата ответа.
+
+#### Необязателен:
+
+- для простой одноходовой правки, где задача и acceptance criteria и так прозрачны.
+
+### 2. Как должен выглядеть сильный пример
+
+Сильный пример должен быть:
+
+- релевантным реальной задаче;
+- достаточно коротким;
+- без лишнего декоративного reasoning;
+- качественным именно по тем критериям, которые ты хочешь закрепить.
+
+### 3. Anti-example
+
+Иногда полезно добавить один плохой пример и коротко пояснить, почему он плохой.
+
+#### Пример
+
+```text
+Плохо:
+- "Код выглядит нормально, серьезных проблем нет"
+
+Почему плохо:
+- нет проверки поведения;
+- нет ссылок на риск;
+- нет конкретного finding.
+```
+
+### 4. Retrieval examples
+
+Если examples много, сильнее не вставлять все подряд, а выбирать наиболее близкие к текущей задаче. Это особенно важно в codebase, где один хороший пример из нужного домена полезнее десяти случайных.
+
+### 5. Научное подтверждение и Fact-Checking
+
+#### Прямо подтверждается:
+
+- Выбор и качество in-context examples критично влияют на performance: [Brown et al., 2020](https://arxiv.org/abs/2005.14165), [Liu et al., 2022](https://aclanthology.org/2022.deelio-1.10).
+- Демонстрации работают не только через labels, но и через формат, распределение входов и образец последовательности: [Min et al., 2022](https://aclanthology.org/2022.emnlp-main.759).
+- Many-shot может давать дополнительный выигрыш, если примеры качественные и не перегружают контекст: [Agarwal et al., 2024](https://arxiv.org/abs/2404.11018).
+
+#### Косвенно подтверждается:
+
+- Golden example для coding-task особенно полезен там, где задача требует не просто факта, а правильного способа решения.
+- Negative examples полезны как инженерная практика, хотя их база слабее, чем у standard ICL.
+
+#### Не подтверждено / требует аккуратности:
+
+- Что больше примеров всегда лучше.
+- Что любой пример с подробным reasoning улучшает кодогенерацию.
+- Что anti-examples универсально полезны для всех моделей и задач.
+
+### 6. Практическая ценность для программиста
+
+- Для code review лучше один эталонный finding, чем пять общих советов.
+- Для codegen лучше один репрезентативный patch, чем длинный role-play.
+- Для тестов лучше образец test-case и expected assertion pattern.
+- Примеры должны быть похожи на текущую задачу, а не просто красивыми.
+
+---
+
+<Module_ID id="MOD_PROMPT_04_VERIFICATION_2026" />
+
+## Модуль 4. Verification Loops, self-feedback и coding tasks
+
+### Суть метода
+
+В программировании часто важен не первый ответ, а способность модели проверить себя. Поэтому prompt имеет смысл строить не как `скажи ответ`, а как `пройди цикл`.
+
+### 1. Базовый verification loop
+
+```text
+Шаг 1. Сформулируй краткий план.
+Шаг 2. Сделай изменение.
+Шаг 3. Сопоставь результат с acceptance criteria.
+Шаг 4. Проверь риски регрессии.
+Шаг 5. Если есть конфликт с критериями, исправь решение.
+```
+
+### 2. Для каких coding-task это особенно полезно
+
+#### Генерация кода
+
+- сначала интерфейс;
+- потом реализация;
+- потом тесты;
+- потом проверка edge cases.
+
+#### Code review
+
+- сначала выделить возможные риски;
+- потом отфильтровать ложноположительные;
+- потом оставить только findings.
+
+#### Bugfix
+
+- сначала сформулировать гипотезу бага;
+- потом предложить минимальный patch;
+- потом проверить, что patch покрывает симптом и не ломает соседнее поведение.
+
+### 3. Научное подтверждение и Fact-Checking
+
+#### Прямо подтверждается:
+
+- Iterative self-feedback может улучшать результат без нового fine-tuning: [Self-Refine](https://arxiv.org/abs/2303.17651).
+- Verbal reinforcement и reflective memory могут заметно усиливать агентное поведение, включая coding tasks: [Reflexion](https://arxiv.org/abs/2303.11366).
+- Bootstrap reasoning traces полезны как inference-time scaffold: [STaR](https://arxiv.org/abs/2203.14465).
+
+#### Косвенно подтверждается:
+
+- Для программирования acceptance checks и tests — наиболее естественная форма внешнего feedback signal.
+- Review pass после generation pass часто полезнее, чем одна более длинная генерация.
+
+#### Не подтверждено / требует аккуратности:
+
+- Что self-critique всегда улучшает результат.
+- Что модель надежно оценивает собственный output без внешних checks.
+- Что внутренний critique-pass эквивалентен настоящему unit test или compiler feedback.
+
+### 4. Практическая ценность для программиста
+
+- Если есть компилятор, линтер или тесты, лучше использовать их как внешний feedback.
+- Если внешней проверки нет, нужен хотя бы forced critique-pass.
+- Review-loop особенно полезен для больших patch и risky refactoring.
+- Самый сильный loop обычно: `plan -> patch -> test/check -> refine`.
+
+### 5. Опасности
+
+- **Self-bias:** модель склонна любить собственный первый ответ.
+- **Loop inflation:** слишком длинная самопроверка без новых сигналов превращается в шум.
+- **Fake verification:** модель пишет, что все проверила, но фактического внешнего check не было.
+
+---
+
+<Module_ID id="MOD_PROMPT_05_LAYOUT_2026" />
+
+## Модуль 5. Длинный контекст, навигация и layout
+
+### Суть метода
+
+Формат важен, но он вторичен относительно структуры. Для программиста главный вопрос не `XML или Markdown?`, а `может ли модель быстро понять, где задача, где правила, где примеры и где контракт ответа`.
+
+### 1. Что действительно важно
+
+- разделять task, context, axioms, examples и output contract;
+- не смешивать код, правила и поясняющий текст в один поток;
+- держать критичные ограничения близко к месту генерации;
+- не перегружать prompt нерелевантным контекстом.
+
+### 2. Формат как вторичный выбор
+
+#### Markdown
+
+Хорош для большинства everyday engineering tasks, если структура простая.
+
+#### XML
+
+Полезен для длинных, вложенных и многодокументных prompts.
+
+#### JSON
+
+Хорош для machine-readable contracts, state data и schema-bound output.
+
+#### YAML
+
+Годится для компактных конфигов, но не стоит объявлять его запрещенным или непригодным как класс.
+
+### 3. Научное подтверждение и Fact-Checking
+
+#### Прямо подтверждается:
+
+- Формат prompt может заметно влиять на результат: [Tang et al., 2025](https://aclanthology.org/2025.findings-emnlp.3/).
+- На длинном контексте модель использует информацию неравномерно, особенно из середины: [Lost in the Middle](https://arxiv.org/abs/2307.03172).
+- Порядок и организация примеров тоже важны: [Lu et al., 2024](https://aclanthology.org/2024.findings-acl.884).
+
+#### Косвенно подтверждается:
+
+- XML и другие явно структурированные layouts полезны как навигационные якоря.
+- Markdown часто достаточен, если prompt короткий и хорошо разделен.
+
+#### Не подтверждено / требует аккуратности:
+
+- Что существует один научно лучший формат prompt engineering.
+- Что JSON или YAML плохи именно из-за доказанной проблемы positional encoding.
+- Что формат важнее самой архитектуры задачи.
+
+---
+
+## Практический шаблон для программиста
+
+```text
+[Short Priming]
+Ты работаешь как инженерный агент по {стек/роль}.
+Фокус: {корректность | тесты | review | минимальный patch}.
+
+[Goal]
+Нужно: {что сделать}.
+Готово, если: {acceptance criteria}.
+
+[Context]
+Файлы: {paths}
+Ограничения: {api, compatibility, environment}
+
+[Belief State / Axioms]
+- {инвариант 1}
+- {инвариант 2}
+- {инвариант 3}
+
+[Reward Criteria]
+Хорошо:
+- {signal 1}
+- {signal 2}
+Плохо:
+- {failure mode 1}
+- {failure mode 2}
+
+[Golden Example]
+{1 сильный пример}
+
+[Counter-Example]
+{1 плохой пример, если нужен}
+
+[Output Contract]
+Верни: {patch | findings | plan | json}
+
+[Verification Loop]
+Сначала {plan/check}, потом {implementation}, потом {verification/refine}.
+```
+
+---
+
+## Практический вывод
+
+Для programming-пrompting полезнее всего такой порядок приоритета:
+
+1. Сначала цель и acceptance criteria.
+2. Потом локальные инварианты проекта.
+3. Потом примеры качества.
+4. Потом контракт ответа.
+5. Потом verification loop.
+6. И только после этого выбор конкретного layout.
+
+Главная ценность старого экспериментального протокола после fact-check сохранилась в ослабленном и более честном виде:
+
+- да, модели полезно явно задавать аксиомы;
+- да, модели полезно показывать критерии успеха;
+- да, golden examples и self-feedback работают;
+- да, это можно использовать в coding-prompts;
+- нет, это не нужно объяснять через псевдофизику attention или прямую инъекцию reward function в веса модели.