agent-quality-kit 0.2.2

package/kit/docs/ai/ai-native-development.md

@@ -0,0 +1,371 @@
+---
+title: AI-native разработка — что из чужого опыта у нас есть, а чего нет
+description: Практики разработки с агентами из двух каналов, сверенные с тем, что уже настроено в этом репозитории: харнес, память в коде, планы, исполняемые спеки, control center, feedback loop.
+tags:
+  - topic/ai
+  - kind/playbook
+---
+
+# AI-native разработка — что из чужого опыта у нас есть, а чего нет
+
+> **Зачем этот документ отдельно.** Половина обоих каналов — про то, **как писать код с
+> агентами**, а не про продукт с LLM. Это касается нашего харнеса (`.claude/`, гейты, пайплайн
+> агентов), а не методологического контура. Держать это вперемешку с RAG вредно, поэтому
+> вынесено сюда.
+>
+> **Откуда файл.** Собран при сплошном чтении двух каналов по теме RAG (провенанс —
+> `../rag/sources/README.md`), поэтому изначально лежал в
+> `docs/rag/`. Переехал в `docs/ai` 2026-08-26 — по предмету, а не по происхождению.
+>
+> **Формат.** Каждая практика: что это, чем подтверждена, и **есть ли она у нас** — с честной
+> отметкой. Дублировать уже написанное в `docs/ai/agent-harness-playbook.md` я не стал; тут
+> только то, что там отсутствует или сформулировано иначе.
+
+---
+
+## §1. Сводка: где мы уже впереди, а где отстаём
+
+| Практика | У нас | Комментарий |
+|---|---|---|
+| Гейты в pre-commit, свой arch-lint | ✅ есть | `scripts/arch-lint.sh`, включая `no_silent_except` |
+| Правила и роли агентов | ✅ есть | `.claude/CLAUDE.md`, `.claude/rules/`, пайплайн Planner→…→Analyzer |
+| Plan-first, план в отдельном коммите | ✅ есть | железное правило, `specs/tasks/task-XXX.md` |
+| Централизованные логи | ✅ есть | Loki + Alloy |
+| Карта проекта в контексте | ✅ есть | `specs/memory/project-map.md` |
+| **Дерево `/docs` вместо одного большого файла правил** | 🔶 частично | у нас `docs/` есть, но не как **граф контекстов с ленивой загрузкой** |
+| **`AICODE-` память прямо в коде** | ❌ нет | дешёвая практика, у нас отсутствует |
+| **Исполняемые BDD-спеки** | ❌ нет | у нас тесты, но не спеки в формате Given-When-Then, привязанные к требованиям |
+| **Feedback loop с журналом экспериментов** | ❌ нет | у нас нет метрики, по которой агент мог бы улучшать сам себя в цикле |
+| **Cross-model review** | ❌ нет | ревью делает один и тот же класс модели |
+| **`agent`-режим приложения** | ❌ нет | приложение не оптимизировано под самопроверку агентом |
+| **Трассировка агентного цикла** | ❌ нет | логи есть, трейсов шагов агента нет |
+| **Бэкапы и error tracking** | ❌ нет | P0 в реестре работ; на фоне «автоматических LLM-взломщиков» это уже не абстракция |
+
+---
+
+## §2. Харнес: дерево `/docs` вместо одного толстого файла
+
+**Что делают.** Не один `AGENTS.MD`, а **ветвистая структура документов в `docs/`** — «граф
+контекстов с ленивой загрузкой», который агент сам поддерживает в порядке. Плюс `AGENTS.MD`
+раскиданы по папкам как локальные уточнения ([разбор](https://t.me/llm_under_hood/755),
+[ещё](https://t.me/llm_under_hood/763)).
+
+**Чем подтверждено.** Прямой замер: автор переключился на проект со старым форматом (один
+толстый `AGENTS.MD` + `README` + заглушка), и агент «внезапно начал тупить даже с High
+reasoning». Лечение: скормить выжимку из Engineering Harness → попросить прочитать весь код
+и доки → **десятиминутное интервью голосом** → 20 минут на интеграцию и ручную подчистку →
+качество работы вернулось к норме.
+
+**Две неявных фишки структуры**, которых не видно сразу:
+
+1. **Перетаскивание фич между проектами.** Фичу документируют в `/docs` исходного проекта, а
+   потом в целевом просят «вот фича из другого проекта, адаптируй так, чтобы доки оказались в
+   доках, код и конфиги обновились, а `make install && make deploy` выкатили новую конфигурацию».
+2. **Быстрый старт новых проектов.** Просят написать RFC, который заводит такой же пустой
+   проект с нуля, — и дальше новый проект поднимается одной командой.
+
+> **Наш случай.** У нас `docs/` большой и хорошо структурированный, но он написан **для людей**.
+> Точки входа для агента (что читать первым, куда идти дальше) в нём нет — есть только
+> `project-map.md`, который про код, а не про домен. Это дешёвая правка с заметным эффектом.
+
+---
+
+## §3. Память агента прямо в коде: `AICODE-`
+
+**Что делают** ([разбор](https://t.me/llm_under_hood/590)). Разрешают агенту оставлять
+однострочные комментарии с префиксом, который он же потом легко находит через grep, и
+**обязательно просят искать эти комментарии перед началом работы с файлом**:
+
+```text
+// AICODE-NOTE: сложный разбор OSC-последовательностей — это ядро логики оверлея логина
+// AICODE-TODO: вынести парсинг в отдельную функцию, когда появится второй формат
+// AICODE-ASK: что если последовательность разорвана между сообщениями?
+```
+
+- `AICODE-NOTE` — заметка для будущей сессии;
+- `AICODE-TODO` — задача себе на потом;
+- `AICODE-ASK` — вопрос человеку; человек отвечает и превращает в `NOTE`.
+
+**Зачем.** Долгосрочный слой памяти прямо в коде: агент задаёт вопросы по тексту и оставляет
+себе заметки, не раздувая контекст и не заводя отдельную систему.
+
+> **Нам это подходит с одной оговоркой.** У нас в правилах жёсткий запрет на `TODO` в финальном
+> коде (гейт в `arch-lint.sh`). Значит либо `AICODE-TODO` не используем, либо гейт учит
+> различать `TODO` и `AICODE-TODO`. Это решение владельца, не моё — правила `.claude/` вне
+> моего скоупа.
+
+---
+
+## §4. Планы: implementation plan, RFC, ExecSpec
+
+**Базовый процесс**, который у нас уже принят как «plan-first», но с деталями, которых у нас нет
+([разбор](https://t.me/llm_under_hood/582)):
+
+1. Ставим задачу и **первым делом просим детальный план реализации — не писать код, а подумать**.
+2. **План — единственный источник правды.** Его просматривают глазами; при необходимости
+   отправляют в другую сессию и просят проверить на логические нестыковки.
+3. Только после ревью план идёт на исполнение. Потом его можно выбросить или приложить к PR.
+
+**Ключевое преимущество, названное прямо:** «все изменения в одном документе, они пока ещё не
+размазаны по коду».
+
+**Запуск нескольких версий одной задачи.** Практика, которую стоит знать: всегда запускают
+2–4 версии, выбирают лучшую, остальные выбрасывают. «Время LLM не жалко. Это Спарта»
+([пост](https://t.me/llm_under_hood/678)). OpenAI даже сделала это штатной фичей (до 4 версий).
+
+**Забавная и практичная деталь про слово «план»** ([пост](https://t.me/llm_under_hood/725)):
+после того как OpenAI сделала режим планирования штатным, любое упоминание слова «план»
+переключает агента в режим, **запрещающий редактировать файлы**. Пришлось переименовать:
+
+```text
+ExecSpec: продумай, проанализируй и набросай спеку реализации фичи.
+Положи в `drafts/###-objective-description.md`, где номер инкрементируется от `001`.
+Обязательно переформулируй задачу и опиши шаги реализации. Приведи фрагменты кода, если нужно.
+```
+
+> **Тот же класс граблей возможен и у нас.** Наш `Skill(plan-template)` и слово «план» в
+> правилах — это то, что может однажды столкнуться с изменившимся поведением инструмента.
+> Держим в голове.
+
+---
+
+## §5. Исполняемые спеки вместо SDD — самая ценная идея раздела
+
+**Проблема, которую формулируют прямо** ([разбор](https://t.me/llm_under_hood/876)):
+
+> Spec-Driven Development даёт спеки, которые «потом будут лежать в кодовой базе мёртвым грузом
+> и источником галлюцинаций, ибо **нельзя никак проверить, что код всё ещё соответствует
+> спекам**. То есть у нас не спеки получаются, а просто одноразовые вайб-планы.»
+
+**Решение — вернуться к BDD, которому двадцать лет.** Формат `Given-When-Then`, придуманный
+ровно для той же проблемы: как синхронизировать разработчиков, продактов и тестировщиков так,
+чтобы требования не устаревали.
+
+Иерархия:
+
+```text
+(1) Описание требований
+(2) Набор читаемых сценариев под требования (сгруппированы по требованиям)
+(3) Код, который на лету парсит сценарии и прогоняет тест системы
+```
+
+Если код нарушает сценарий — падает билд. Если добавили требование — получился обычный TDD.
+Инструменты: [Gherkin](https://cucumber.io/docs/gherkin/), [Cucumber](https://cucumber.io/),
+[JBehave](https://jbehave.org/), [RSpec](https://rspec.info/),
+[Behave](https://behave.readthedocs.io/en/latest/).
+
+**Что даёт в эпоху агентов:** «агенты замечательно нарезают высокоуровневые требования в BDD
+сценарии и потом реализуют код. При этом сценарии остаются синхронизированными с требованиями,
+но превращаются в нормальный AI-Native Harness, который агент может запускать **хоть по сто раз
+за сессию**».
+
+Автор оговаривается, что сам Gherkin не любит (парсеры становятся источником проблем на росте)
+и предпочитает event-driven спеки; у него **тысяча спеков в секунду на одном ядре**, и «дольше
+секунды гонять все базовые бизнес-тесты — недопустимо»
+([пост](https://t.me/llm_under_hood/918)).
+
+> **⚡ Это прямо про нашу боль.** У нас есть `specs/tasks/task-XXX.md` с AC — но AC написаны
+> прозой и проверяются глазами человека на ревью. Ничто не мешает коду разъехаться с AC через
+> три задачи, и мы этого не увидим. Наш инвариант «реализованный план неизменяем» защищает
+> историю, но не соответствие.
+>
+> **Ближайший к нам аналог, который уже работает** — `report-golden` и сверка DirectPG: это
+> и есть исполняемые спеки, только для данных. То есть культура у нас есть, просто не
+> распространена на бизнес-правила.
+
+---
+
+## §6. Feedback loop и журнал экспериментов — агент улучшает себя по метрике
+
+**Протокол**, прописанный в `AGENTS.MD` ([разбор](https://t.me/llm_under_hood/727)):
+
+```text
+(1) Запускаем `make eval`, узнаём текущий score, записываем в `experiments/007-experiment.md`
+(2) Анализируем код, просматриваем журнал прошлых экспериментов,
+    дописываем в тот же файл план улучшения score
+(3) Реализуем и запускаем `make eval`. Стало лучше → коммитим с описанием
+(4) Стало хуже → откатываем код, НО СОХРАНЯЕМ описание эксперимента,
+    чтобы в будущем агент не повторял старых ошибок
+```
+
+Запускается в цикле:
+
+```bash
+PROMPT="запусти следующий эксперимент, который оптимизирует код генерации wav-файла"
+for ((i=0; i<=50; i+=1)); do
+  codex exec --sandbox danger-full-access "$PROMPT"
+done
+```
+
+**Насколько это работает — проверено экспериментом, который автор назвал сломом мозга**
+([разбор](https://t.me/llm_under_hood/730), [продолжение](https://t.me/llm_under_hood/731)).
+Дали набор из 235 тестов для движка формул Excel и попросили в цикле «прогони тесты, ужаснись,
+напиши минимальный патч, максимально повышающий точность». Git log получился такой:
+
+```text
+0.0% → 4.7% → 12.0% → 34.0% → 44.3% → 48.1% → 52.8% → 78.3% → 82.6%
+→ 84.3% → 87.2% → 89.4% → 95.7% → 98.3% → 100.0%
+```
+
+Автор ожидал «горы спагетти и захардкоженные ответы на тесты» — а получил обычный код с
+парсером формул, AST, интерпретатором и работой с графом зависимостей. Единственный косяк:
+всё сложил в один файл, пришлось просить разнести.
+
+> **Ключевое условие, без которого это не работает: должна быть метрика.** Не «сделай лучше»,
+> а `make eval` → число. У нас такая метрика есть ровно в одном месте — сверка отчётов 1С.
+> И именно там этот приём применим прямо сейчас: «повышай процент сходимости, откатывай, если
+> стало хуже, веди журнал».
+
+---
+
+## §7. Control Center — когда проектов больше одного
+
+**Паттерн** ([разбор](https://t.me/llm_under_hood/886)). По мере роста код перестаёт помещаться
+в одну репу: появляются сервисы, публичная документация, SDK, аналитика, интеграции. Заводится
+отдельный проект **control center**, в котором почти нет кода, но есть:
+
+- в `AGENTS.MD` — список соседних проектов с кратким описанием их ролей;
+- дерево `/docs` с той же архитектурой, что у всех остальных проектов;
+- описание деплойментов в исполняемом виде (у автора — NixOS): «как и в случае со спеками,
+  я предпочитаю **исполняемые описания — они никогда не врут**»;
+- набор мелких API и скриптов, помогающих агентам ориентироваться;
+- централизованная аналитика, логирование, телеметрия — единообразно для всех проектов;
+- папка с историческими записями: планы, RFC, история изменений серверов, **анализ
+  происшествий**, эксперименты.
+
+Причём control center у команды **не один**: для продуктовых задач — своя конфигурация, без
+деплоев, но с доступом к аналитике и продуктовым базам знаний.
+
+> **Нам это пока не нужно** — у нас один монорепозиторий. Но два элемента стоит забрать уже
+> сейчас: **исполняемое описание деплоя** (у нас частично есть в compose-файлах, но
+> `docker-compose.prod.bi.yml` подключается руками и в пайплайне не упомянут — это уже
+> записано как долг) и **папка с анализом происшествий**.
+
+---
+
+## §8. Режим `agent` у приложения
+
+Мелкая, но точная идея ([разбор](https://t.me/llm_under_hood/755)). Кроме `dev` и `prod`
+появляется третий режим — **`agent`**, в котором приложение оптимизировано под самопроверку
+агентом:
+
+- логов меньше;
+- **любая ошибка роняет приложение целиком** (агенту нужен чёткий сигнал, а не деградация);
+- логин отключён полностью, вместо него — параметр вида `-agent-login "reader@test"`;
+- приложение закрывается сразу после первого запроса (`-single-request`).
+
+Смысл: агент одной командой дёргает нужную страницу под нужной ролью и получает чистый ответ
+без мусора в контексте.
+
+> **Для нас особенно интересна часть про роль.** У нас проверка прав — слепая зона (записана
+> в карте слепоты). Возможность запустить приложение «как пользователь с ролью X» одной командой
+> — это и удобство для агента, и заготовка под тесты авторизации, которых нам не хватает.
+
+---
+
+## §9. Cross-model review и mutation testing
+
+**Cross-model review** — «обязательное ревью фичи моделью из другого семейства теперь личный
+стандарт, без которого неуютно. Не потому что не доверяю своему агенту, а потому что **чужой
+глаз ловит ровно то, что мой замылил**» ([разбор](https://t.me/neuraldeep/2245)).
+
+Практика подтверждается независимо: кто-то гоняет одного агента ревьюером после другого по
+2–5 итераций, кто-то не пускает код в git, пока его не посмотрели две модели из разных семейств
+([сводка](https://t.me/neuraldeep/2248)).
+
+Официальный плагин для связки существует:
+[cross-model workflow](https://github.com/shanraisshan/claude-code-best-practice/blob/main/development-workflows/cross-model-workflow/cross-model-workflow.md).
+
+**Mutation testing через LLM** — тема, которую стоит знать:
+[LLMorpheus](https://github.com/githubnext/llmorpheus) ·
+[разбор Meta ACH](https://engineering.fb.com/2025/09/30/security/llms-are-the-key-to-mutation-testing-and-better-compliance/).
+
+> **У нас есть `scripts/mutation-test.sh`** (advisory-профиль для DirectPG casts) — то есть
+> направление уже нащупано. Чего нет — cross-model review: и Reviewer, и Builder у нас одного
+> семейства. Это дешёвое улучшение с понятным механизмом действия.
+
+---
+
+## §10. Спор «харнесы умирают?» — и чем он кончился
+
+Полезно как отрезвление против переинжиниринга собственной обвязки
+([наброс](https://t.me/neuraldeep/2123), [итог обсуждения](https://t.me/neuraldeep/2130)).
+
+**Тезис:** модели стали умнее обвязок; «вся эта обвязка из миллиона спек превратилась в хрупкие
+лестницы из спичек, которые проще сжечь, чем поддерживать». Критическая масса минимума:
+`context7`, `web_search`, `playwright`, базовый `AGENTS.md`/`CLAUDE.md` — и всё.
+
+**Что ответило сообщество** (и с чем автор согласился):
+
+- **хайп спадает, технология остаётся** — так было с RAG, агентами, MCP, скиллами;
+- **современный харнес — не про тулинг, а про упакованный процесс**: у одного из участников
+  имплементация занимает 15–20% времени, ревью и рефакторинг — **50–60%**. Узкое горлышко —
+  не написать код, а проверить;
+- **три категории харнеса**: «экзоскелет, который двигает руками модели» — умирает; **память,
+  identity и recall между сессиями** — не умирает; **инструменты (shell, браузер, поиск)** —
+  точно не умирают;
+- **простой критерий**: харнес нужен, если экономит время на план, дебаг и присмотр. Если
+  ковыряешься в нём больше, чем экономишь, — что-то не так.
+
+**Итоговая формулировка:**
+
+> Умирает излишняя сложность поверх того, что модели уже умеют. Умирают саб-агенты для ревью,
+> когда хватает второй сессии. Умирают графовые оркестраторы из 50 нод, когда работает один
+> ReAct-цикл. **Не умирает упакованный процесс, память между сессиями и cross-model review
+> на объёмных задачах.**
+>
+> «Чем проще велосипед, тем лучше и надёжнее едет. Но если везёшь 150k строк кода с
+> брейк-ченджами — велосипед не подойдёт, нужен грузовик.»
+
+> **Как это читать применительно к нам.** У нас как раз «грузовик»: большой проект, много
+> доменов, требования аудита. Наш харнес не избыточен — он соразмерен. Но критерий «экономит
+> ли конкретный элемент время» стоит применять к каждому новому гейту, который мы хотим добавить.
+
+---
+
+## §11. Чем это кончается, если не следить: разбор 1069 коммитов
+
+Самый честный пост корпуса ([разбор](https://t.me/neuraldeep/2245)) — автор проанализировал
+git-историю своего же проекта за 90 дней:
+
+- **из 1069 коммитов 416 — это `fix`**. Не фича, не рефактор — стабилизация уже выкаченного;
+- **1436 блоков `except Exception`**, из которых только ~10% пробрасывают ошибку дальше;
+  остальные глушат её в лог или `return None`. Итог — три недели поиска источника 500-к;
+- **один route-файл на 6305 строк** — «не потому что так задумано, а потому что каждую новую
+  фичу дописывали туда же: агенту так ближе по контексту»;
+- **число моделей захардкожено в четырёх местах четырьмя разными значениями** (10/13/14/30),
+  потому что нет единого источника правды;
+- **пиковая скорость 44 коммита в день** — «это не человеческий темп ревью».
+
+**Диагноз автора** — и он важнее фактуры:
+
+> «Долг копится строго там, где я убрал себя из центра. А там, где я держу карту в голове и
+> пропускаю решения через себя, — стабилизируется. **AI SDLC — это усилитель. Он множит и
+> продуктивность, и когнитивный долг с одинаковым КПД.** В центре стоит инженер с картой —
+> множится продукт. В центре пусто — множится техдолг.»
+
+И ещё точнее, из более позднего поста ([разбор](https://t.me/neuraldeep/2283)):
+
+> «**Тест сверяет реализацию с замыслом, но не может проверить сам замысел.** А в агентной
+> разработке пропускается именно формирование идеи, смысла и замысла, а не написание кода.»
+
+> **Это буквально обоснование трёх наших железных правил** — plan-first, «реализованный план
+> неизменяем» и «отступление от ADR — вопрос владельцу». Мы записали их после собственных
+> инцидентов; здесь тот же вывод получен независимо и на другом масштабе.
+
+---
+
+## §12. Что я предлагаю забрать себе — по убыванию отношения пользы к цене
+
+| # | Практика | Цена | Что даёт |
+|---|---|---|---|
+| 1 | **Точка входа для агента в `docs/`** — короткий индекс «что читать первым, куда идти дальше» | часы | заметный рост качества ответов агента по домену; подтверждено чужим замером |
+| 2 | **`AICODE-NOTE` / `AICODE-ASK`** в коде (без `TODO`, чтобы не спорить с гейтом) | часы | память между сессиями, вопросы агента человеку по месту |
+| 3 | **Cross-model review** для крупных задач | настройка | ловит то, что замылил основной агент |
+| 4 | **Feedback loop по метрике сверки 1С** — журнал экспериментов, откат при ухудшении | дни | единственное место, где у нас уже есть числовая метрика |
+| 5 | **Режим `agent` у приложения** с логином по роли | дни | самопроверка агентом + заготовка под тесты прав |
+| 6 | **Исполняемые спеки (BDD) для бизнес-правил** | недели | AC перестают расходиться с кодом молча |
+| 7 | **Трассировка агентного цикла** (LangFuse или своё) | недели | сегодня мы не видим, что агент делал внутри шага |
+
+**Ничего из этого не делать, пока не закрыт P0** (бэкапы, error tracking) — это не улучшение
+разработки, а страховка от потери всего.

package/kit/docs/ai/ai-sdlc.md

@@ -0,0 +1,221 @@
+<!-- источник: audit_project/docs/ai/ai-sdlc.md -->
+# SDLC эпохи агентов — как мы разрабатываем, когда код пишет нейросеть
+
+> **Что это.** Наш процесс разработки, спроектированный заново под реальность «агент генерит код,
+> человек владеет пониманием». Не классический SDLC с приклеенным ИИ, а пересборка этапов вокруг
+> одной ставки — **проверяемости**. Дистиллят всего накопленного (плейбук, ADR 006, дип-ресёрч
+> 2026-07, корпус практиков, AIE World's Fair, Karpathy). Инструментальная часть — в
+> `agent-harness-playbook.md`; здесь — САМ ПРОЦЕСС и роли.
+
+---
+
+## 0. Почему классический SDLC ломается
+
+Три сдвига, из-за которых нельзя просто «добавить ИИ» в старый процесс:
+
+1. **Генерация стала дешёвой, понимание — дорогим.** Раньше узкое место — написать код; ревью
+   читало то, что человек и так медленно писал. Теперь код появляется быстрее, чем человек способен
+   его осмыслить → если оставить классическое ревью, оно либо станет фикцией, либо остановит поток
+   (review debt — очередь изменений, которые «в системе», но которых никто не понял).
+2. **Ревью строк умерло — родилось ревью намерений и гейтов.** Никто не будет читать 10 000 строк.
+   Их будут читать машины (линтеры, тесты, LLM-ревьюеры), а человек будет проверять ДРУГОЕ:
+   контракт, границы, инварианты, «то ли мы вообще строим».
+3. **Способность = модель × харнес** (Harness-Bench). Качество результата определяется не тем,
+   «насколько умна нейросеть», а средой: гейтами, обратной связью, границами. Значит процесс
+   строится вокруг среды, а не вокруг надежд на модель.
+
+## 1. Главная ставка: проверяемость
+
+Формула (Karpathy): *классический софт автоматизирует то, что можно специфицировать; LLM
+автоматизируют то, что можно **верифицировать***. Отсюда центральное правило нашего SDLC:
+
+> **Не начинаем строить то, для чего не спроектирована проверка.** Сначала «как мы узнаем, что
+> это работает», потом код. Функция без арбитра — не функция, а надежда.
+
+Три инструмента проверяемости — и их пределы (важно не путать):
+
+| Инструмент | Что делает | Чего НЕ делает |
+|---|---|---|
+| **Метрика** | термометр: показывает «39°» | не говорит, что делать; не лечит |
+| **Тест/гейт** | иммунитет: не пускает известный класс болезни | не ловит то, чего нет в контракте |
+| **Трейс/лог** | история болезни: как дошли до состояния | сам себя не читает |
+
+И честное ограничение: **нельзя покрыть тестом то, что не пришло в голову.** Это не тупик, а
+причина, почему в процессе есть отдельные этапы против «не пришло в голову» (см. §7).
+
+Практическое следствие ставки: вопрос «код хороший или плохой?» переформулируется. Вложенность 10,
+которую человек не разберёт, а нейросеть разберёт — приемлема **только если** (а) поведение
+зафиксировано внешним тестом, (б) сложность под гейтом (у нас C90 ≤ 10 — как раз чтобы такого не
+было), (в) человек понимает КОНТРАКТ этого куска, даже не понимая каждую строку. Понимание
+переезжает с уровня строк на уровень контрактов — но не исчезает.
+
+## 2. Кто участники процесса
+
+- **Человек (владелец)** — владеет «зачем», инвариантами, вкусом и финальным риском. Не читает
+  каждую строку; читает контракты, диффы спеки, объяснения, трейсы. Его нельзя заменить, потому что
+  **понимание не аутсорсится**.
+- **Агент-строитель** — генерит код/доки/тесты внутри жёстких гейтов; обязан объяснять сделанное
+  (comprehension-гейт).
+- **Агенты-критики** (свежий контекст / другая модель) — devils-advocate, gap-finder, LLM-ревьюеры:
+  атакуют планы и диффы без сикофантии к автору.
+- **Жёсткие гейты** (материал, который нельзя «пропустить»): pre-commit, CI, хуки, тесты, лимиты.
+  Единственный участник, который никогда не устаёт и не поддаётся уговорам.
+
+## 3. Пайплайн: 11 этапов
+
+Сводно (детали ниже):
+
+```
+0 Зачем → 1 Спека/контракт → 2 Предсказание → 3 План среза + «го»
+→ 4 Красный e2e-арбитр → 5 Стройка в петле → 6 Ревью-пирамида
+→ 7 Live-проверка «как пользователь» → 8 Мердж/деплой
+→ 9 Эксплуатация (инцидент → гейт) → 10 Еженедельный GC
+(+ 11 Петля обучения человека — идёт сквозь все этапы)
+```
+
+**Этап 0. «Зачем» (человек).** Вход: боль/идея. Выход: бизнес-ТЗ простыми словами. Агент помогает
+структурировать, devils-advocate атакует («какое допущение молчаливое?»). Анти-паттерн: начать со
+стека («возьмём Kafka»), а не с проверяемого исхода.
+
+**Этап 1. Спека и контракт первыми.** Выход: PRD-секции (назначение · глоссарий · внешнее API ·
+модель данных с max-вниманием — самая дорогая ошибка · sequence flows · внешние зависимости ·
+мониторинги-криты) + **Test Questions** — список проверок словами ДО кода. Контракт (API-схемы,
+форматы) — исполняемая цель, не проза. Анти-паттерн: «допишем спеку по ходу» — агент без спеки
+галлюцинирует требования уверенно.
+
+**Этап 2. Письменное предсказание (тренажёр суждения).** Перед срезом человек письменно отвечает:
+«что сломается первым? где узкое место? сколько выдержит?» После — сравнение с фактом. Это
+единственный известный способ наращивать инженерное суждение, не набирая код руками: разрыв
+предсказание↔реальность и есть учёба.
+
+**Этап 3. План среза + явное «го».** Вертикальный тонкий срез насквозь (walking skeleton), план в
+`spec/plans/NNN.md`, развилки — варианты + рекомендация. Код не пишется без принятого плана.
+Анти-паттерн: «заодно сделаю ещё» — scope creep агента.
+
+**Этап 4. Красный e2e-арбитр — до кода.** Приёмочный тест на ПОВЕДЕНИЕ (через внешний интерфейс:
+HTTP → ответ + состояние БД), сначала красный. Он **залочен от строителя** (test lock — агенты
+переписывают тесты под свой сломанный код: SpecBench, 30% прогонов). Арбитр = определение «готово»,
+не мнение.
+
+**Этап 5. Стройка в петле.** Агент строит; каждое изменение проходит сквозь жёсткое: авто-формат
+(хук) → arch-lint/ruff (pre-commit) → stop-gate. Правила петли: новые зависимости — отдельное
+решение с «ок» человека (slopsquatting); недоверенный контент — без секретов и write-прав; большой
+дифф (>~400 строк) — событие: разбить или объяснять частями. Повторный баг → не «постараюсь», а
+новый гейт. Многосессионное — через progress-файл, одна фича = одна сессия.
+
+**Этап 6. Ревью-пирамида (вместо чтения 10 000 строк).**
+```
+        ЧЕЛОВЕК: контракт, границы, инварианты, «то ли строим»,
+                 сократический аудит («почему так? что сломает?»)   ← минуты
+      LLM-РЕВЬЮЕРЫ: специализированные (security/perf/quality),
+        cross-model или свежая сессия; список «что НЕ флагать»       ← автоматом
+    МАШИННЫЕ ГЕЙТЫ: тесты, линтеры, лимиты, arch-lint, CI            ← секунды, всегда
+```
+Ключевое про LLM-ревьюеров: они — тоже система, и их **меряют**: golden-set диффов с подсаженными
+известными багами → recall / false-positive rate; каждый пропущенный в прод баг становится кейсом
+эвала ревьюера. Ревьюер без эвала — генератор шума. Человек в этой пирамиде делает то, что не может
+никто ниже: сверяет с намерением и несёт риск.
+
+**Этап 7. Live-проверка «как пользователь».** Агент сам прогоняет реальный стек (curl по реальному
+порту, не test client) → логи всех сторон → состояние БД → side-effects; человек делает
+sanity-проход глазами, НЕ отлов багов проводки. Мок-тесты структурно слепы на швах (прокси, env,
+рестарты) — этот этап их закрывает.
+
+**Этап 8. Мердж/деплой.** Зелёный CI — разрешение на мердж (branch protection), атомарный PR,
+Conventional Commit. «Фиксы дёшевы, ожидание дорого»: flaky — перезапуском, но повторно flaky →
+чинить причину.
+
+**Этап 9. Эксплуатация: инцидент — это руда.** Наблюдаемость по golden signals; каждый инцидент →
+(а) record/replay — воспроизвести из трейса, (б) регресс-тест, (в) при повторе класса — новый
+постоянный гейт. Петля «прод-инцидент → eval-кейс → гейт» — главный механизм роста качества.
+
+**Этап 10. Еженедельный GC.** Cleanup-сессия агента (мёртвый код, дубли, несогласованные паттерны,
+doc-gardening) — отдельными PR; консолидация правил харнеса (неиспользуемое — прунить). Метрика
+здоровья: **Code Durability** (доля кода, дожившего N недель) и rework rate — не LOC.
+
+**Этап 11. Петля обучения человека (сквозная).** Из каждого среза человек забирает: сравнение
+предсказания с фактом · конспект «что понял» своими словами · прочитанные ADR («почему так») ·
+повторение по кривой забывания. Агент обязан объяснять цепочки целиком по запросу — это не
+вежливость, а часть процесса (анти-review-debt).
+
+## 4. Классика → AI-эра (что именно трансформировалось)
+
+| Этап | Было (человек сам) | Стало | Что гарантирует качество |
+|---|---|---|---|
+| Требования | ТЗ «для людей» | спека, читаемая агентом: глоссарий, контракты, TQ | devils-advocate + человек |
+| Дизайн | опыт архитектора | контракт-first + письменное предсказание | предсказание vs факт |
+| Кодинг | руки, часы | агент, минуты | жёсткие гейты вокруг петли |
+| Ревью | человек читает строки | пирамида: гейты → LLM → человек-инварианты | eval самих ревьюеров |
+| Тесты | «после, если успеем» | красный арбитр ДО кода, залочен | test lock + поведение>реализация |
+| QA | ручные прогоны | агент живёт в live-stack сам | чек-лист швов |
+| Документация | пишется и гниёт | durable-доки + статус в git, doc-gardening | правило «прогресс не в доках» |
+| Рефакторинг | «когда-нибудь» | еженедельный GC + слоп-линтеры | Code Durability |
+| Обучение разработчика | пишет код руками | предсказания, вскрытия инцидентов, сократический аудит | §6 |
+
+## 5. Что НЕ изменилось (вечное)
+
+Спека дешевле кода; ошибка в модели данных — самая дорогая; границы модулей решают масштабируемость
+команды (теперь — агентов); наблюдаемость закладывается, а не прикручивается; простое надёжнее
+сложного (Люссер: каждый последовательный узел множит ненадёжность); **понимание не аутсорсится**.
+ИИ — множитель: он умножает и порядок, и хаос.
+
+## 6. Как расти «джун → сеньор», не печатая код (честный ответ)
+
+Вопрос «можно ли стать хирургом по видео» — правильный, но профессия сместилась. Ты растёшь не в
+хирурга, а в **главврача с навыками патологоанатома**: не оперируешь руками, но (а) решаешь, какую
+операцию делать, (б) распознаёшь, когда она идёт не так, (в) вскрываешь каждый инцидент до причины.
+Декларативное знание («знаю что») даёт теория; **процедурное («знаю как») нарабатывается — просто
+процедура теперь другая**:
+
+1. **Предсказание → факт → разбор** (этап 2/9) — так тренируется суждение о системах. Это
+   процедурный навык, его нельзя посмотреть на YouTube, но можно наработать без клавиатуры.
+2. **Вскрытие инцидентов** — читать трейс/лог/дифф до момента «понял причину», без агента-суфлёра
+   сначала, потом сверить с ним.
+3. **Сократический аудит агента** — «почему так, а не иначе? что сломается, если…?» Если агент
+   не может объяснить просто — это красный флаг кода, если ты не можешь пересказать — красный флаг
+   понимания. Merge только после пересказа.
+4. **Проектирование проверок** — новый критерий сеньорности: не «пишет сложный код», а «умеет
+   спроектировать арбитра, которому можно верить». Метрики/тесты/гейты — твоя специализация (50%
+   времени по твоей же формуле 30/20/50).
+5. **Теория по кривой забывания** (roadmap.sh → конспект → повторение) — да, но каждый рунг
+   немедленно привязывается к живому проекту, иначе декларативное знание испаряется.
+
+Ловушка, которой надо бояться: **иллюзия понимания через чтение**. Проверка простая — если не
+можешь предсказать поведение системы до запуска и объяснить инцидент после, понимания нет, сколько
+бы кода ты ни «читал».
+
+## 7. Против «не пришло в голову» (замыкание круга)
+
+Круг «не покроешь тестом то, что не придумал» размыкается ЧУЖИМИ головами и машинным перебором:
+
+- **Чужие перспективы**: devils-advocate/gap-finder свежим контекстом; cross-model ревью; чек-листы
+  классов дыр (BenchJack 8 классов, OWASP) — это «то, что пришло в голову другим до тебя».
+- **Property-based тесты** (hypothesis): ты задаёшь свойство («скор детерминирован», «баланс
+  необходим, но не достаточен»), машина фантазирует тысячи случаев за тебя.
+- **Фаззинг контракта** (schemathesis): перебор того, что ты не догадался бы послать.
+- **Pre-flight нулевые агенты** (null/random/injection): ловят «дыру в задаче», которую автор не видит.
+- **Инцидент-петля**: то, что всё-таки прорвалось, становится тестом навсегда.
+
+Круг не замыкается — он превращается в спираль: каждая итерация покрывает больше.
+
+## 8. Self-eval по arXiv — да, но через шлюз (наш протокол)
+
+Идея «агент сам читает статьи и эволюционирует» рабочая, но **автовнедрение запрещено** (риски:
+взять ненужное, статья с ошибкой, эффект «100 модных практик = ноль фокуса»). Наш проверенный
+сегодня протокол:
+
+1. Периодически (или по событию «застряли/новая фаза») — research-агенты ищут **дельту** против
+   уже-внедрённого (им даётся список текущего арсенала, иначе получишь пересказ известного).
+2. Находки → reference-док со статусами (✓ первоисточник прочитан / ◐ вторично) и датой.
+3. Каждой находке — вердикт: **внедрить сейчас** (стережёт существующий артефакт) / **триггер**
+   (записать условие в ADR) / **отклонить** (с причиной).
+4. Внедрение — только через обычный пайплайн (план → го → гейты). Никогда «агент прочитал — агент
+   применил».
+
+Так научное знание становится топливом эволюции харнеса, а не источником хаоса.
+
+---
+
+**Связанные документы:** инструменты и конфиги — `agent-harness-playbook.md` · решения по гейтам —
+`spec/decisions/006-quality-gates.md` · продуктовые решения — `reference/memo-decisions.md` ·
+источники — `reference/deep-research-2026-07.md` и остальные `reference/*`.