agent-quality-kit 0.2.2

package/kit/docs/ai/anthropic-ai-native-sdlc-2026-08.md

@@ -0,0 +1,294 @@
+---
+title: Разбор «The AI-Native SDLC playbook» (Anthropic, 2026-08-21)
+description: Конспект плейбука Anthropic по перестройке SDLC под агентов и построчная сверка каждой практики с тем, что реально настроено в этом репозитории.
+tags:
+  - topic/ai
+  - kind/research
+---
+
+# Разбор «The AI-Native SDLC playbook» (Anthropic, 2026-08-21)
+
+> **Что это.** Конспект статьи Anthropic Applied AI о перестройке жизненного цикла разработки
+> под агентов — и **сверка каждой практики с нашим репозиторием**: что уже есть, чего нет, что
+> брать, а что не наш случай.
+>
+> **Источник:** блог Anthropic, «The AI-Native SDLC playbook», Louis Claxton, 21.08.2026.
+> Статья описывает практику команды Applied AI у корпоративных клиентов, а не измерение.
+>
+> **Как читать пометки:**
+> 📄 — тезис статьи: **чужая практика, не измерение**. Верификация — на нас.
+> 📏 — проверено на нашем проекте (дата и способ рядом).
+> ⚖️ — место, где практика статьи спорна для нас или упирается в наш контекст.
+>
+> **Чем отличается от соседей по корпусу:** [`ai-sdlc.md`](ai-sdlc.md) — **наш** процесс по
+> этапам · [`agent-harness-playbook.md` §18](agent-harness-playbook.md) — наша ежедневная дисциплина ·
+> [`stream-2026-08-ai-coding-panel.md`](stream-2026-08-ai-coding-panel.md) — срез практики
+> индустрии на август 2026. **Здесь — одна конкретная внешняя методичка и наш ответ на неё.**
+>
+> Дата разбора: **2026-08-26**. Сверка сделана чтением конфигов, а не по памяти.
+
+---
+
+## 0. Главный тезис статьи, и почему он про нас
+
+📄 **Код перестал быть узким местом — узкими стали соседние стадии.** Когда сборка сжимается
+до часов, план, ревью и выкат остаются человеческой скорости, и очередь просто переезжает
+влево и вправо от «написать код». Контроли, придуманные под ручное написание («ревьюер читает
+каждую строку»), перестают быть выполнимыми, а не просто становятся медленными.
+
+📄 Ответ статьи: каждая стадия **заканчивается артефактом в системе контроля версий**, который
+читает следующая стадия. Цепочка коммитов и есть аудиторский след: кто что попросил, что агент
+произвёл, кто одобрил.
+
+📏 **Для нас это не новость — это ровно наша конструкция.** `specs/tasks/<домен>/task-XXX.md` →
+человеческий апрув → тесты → код → ревью → апрув → коммит. Мы пришли к этому раньше и своим
+путём, из собственных инцидентов (см. [`agent-harness-playbook.md` §18](agent-harness-playbook.md)). Ценность статьи не
+в тезисе, а в **двух-трёх местах, где у неё есть звено, которого у нас нет** — они в §7.
+
+⚖️ Существенная разница контекста: статья написана для организации с командой людей, ролями и
+регулятором. У нас **один владелец и агенты**. Всё, что в статье решает проблему «согласовать
+между отделами», нам не нужно; всё, что решает проблему «человек не успевает понять, что
+произошло», нужно вдвойне.
+
+---
+
+## 1. Стадия Plan — «intent.md»
+
+📄 Идея исходит от того, кто её придумал, а не от того, кто умеет писать требования. Человек
+разговаривает с агентом, тот записывает `intent.md` в терминах автора: проблема, желаемый
+исход, кого затрагивает, ограничения, открытые вопросы. Владелец продукта правит и коммитит.
+Дальше это читает следующая стадия.
+
+| Практика | У нас | Чем доказано |
+|---|---|---|
+| Намерение как версионируемый артефакт | ⬜ **частично** | есть `specs/tasks/`, но это уже **план**, а не намерение |
+| Автор намерения = не инженер | ✅ есть | владелец формулирует задачу словами, Planner превращает в план |
+| Шаблон намерения как скилл | ⬜ частично | есть скилл `plan-template` — но он про план, не про намерение |
+
+⚖️ **Стоит ли нам заводить отдельный `intent.md` — не очевидно.** Аргумент за: у нас регулярно
+теряется «зачем» — план начинается со «что делаем», и через месяц причина восстанавливается по
+переписке. Аргумент против: лишний артефакт на каждую задачу при одном владельце — это налог,
+а не польза; у Planner'а уже есть раздел цели.
+
+📏 **Реальный след проблемы у нас есть.** В `docs/rebuild/_archive/2026-08-02-priority-slice.md`
+и в реестре несколько пунктов помечены «план УДАЛЁН по решению владельца, знание протокола
+сохранено здесь» — то есть намерение пережило план и его пришлось спасать вручную в реестр.
+Это ровно тот случай, ради которого статья разводит `intent` и `plan`.
+
+**Вывод:** не заводить отдельный файл, но **дописать в шаблон плана обязательную секцию
+«Намерение»** — проблема своими словами + чего человек лишён сегодня. Дёшево, и решает
+наблюдаемую потерю.
+
+---
+
+## 2. Стадия Design — «spec.md»
+
+📄 Требования и дизайн схлопываются в одну сессию: агент читает `intent.md`, применяет
+организационные **скиллы** (бренд, безопасность, комплаенс, UX) и выдаёт `spec.md` с явно
+помеченными местами конфликта политик. Владелец продукта рецензирует, но не пишет.
+
+| Практика | У нас | Чем доказано |
+|---|---|---|
+| Политики применяются **пока пишется спека**, а не в ревью через недели | ✅ есть | 28 скиллов в `.claude/skills/`, правило CLAUDE.md «скилл грузить ДО ответа по теме» |
+| Отдельный `spec.md` между намерением и планом | ❌ нет | у нас сразу план |
+| Явно помеченные конфликты политик | ⬜ частично | правило «отступление от ADR — вопрос владельцу, а не комментарий в коде» есть, но оно **дисциплинарное** |
+
+📏 **Наш след того, что дисциплинарного правила мало.** Инцидент 2026-08-06, записан в
+`.claude/CLAUDE.md`: путь сборки рабочего документа отъехал от ADR-018 D5 (XlsxWriter потоком)
+на `openpyxl`, отступление было **осознано и записано комментарием в докстринге** — владелец
+нашёл его через день, читая доки. Цена отложенная: +435 МБ на 100k строк против +128 КБ.
+Это буквально та ситуация, которую статья предлагает ловить пометкой «areas of concern» в
+спеке, до кода.
+
+⚖️ Механический гейт на это владелец делать отказался дважды (2026-08-06 и 2026-08-07):
+«правило дисциплины, а не хук». Значит и `spec.md` как отдельный документ, скорее всего, не
+приживётся. Но **пометка конфликта как обязательное поле плана** — это не гейт, это строка
+шаблона, и она не спорит с решением владельца.
+
+---
+
+## 3. Стадия Build — plan mode, CLAUDE.md, skills, hooks
+
+📄 Ничего не реализуется без принятого плана. Институциональное знание становится файлами,
+которые агент читает. Ограничения работают как код, а не как привычка.
+
+| Практика статьи | У нас | Чем доказано |
+|---|---|---|
+| Plan mode обязательным стартом; план коммитится | ✅ **есть** | железное правило CLAUDE.md «Plan-first», `specs/tasks/<домен>/task-XXX.md`, апрув человека отдельным коммитом |
+| План неизменяем после реализации | ✅ **есть и жёстче статьи** | у нас отдельное правило: реализованный план — запись о случившемся, дописывать можно только «Лог выполнения» |
+| `CLAUDE.md` как контекст новичка | ✅ есть | `.claude/CLAUDE.md` + `@import` карты проекта |
+| Правило «ошибся дважды → в CLAUDE.md» | ✅ есть | каждое правило в CLAUDE.md несёт свой инцидент с датой |
+| «Держать под страницу» | ⚖️ **у нас длиннее** | наш CLAUDE.md существенно больше страницы; мы сознательно платим контекстом за прослеживаемость до инцидента |
+| Skills как институциональное знание | ✅ **есть, и глубже статьи** | 28 скиллов, у доменных — собственный `reference/` корпус (напр. `nextcloud-webdav` L1–L20) |
+| Skills распространяются централизованно | ⛔ не наш случай | плагины и marketplace нужны организации, у нас один репозиторий |
+| Hooks как ограничители во время сборки | ✅ **есть** | 4 типа хуков Claude Code (`block-dangerous-commands`, `require-graph-search`, `auto-format`, уведомления) + 22 гейта в pre-commit |
+| Параллельные сессии в worktree | ⬜ частично | worktree доступен, но наш ограничитель — не число сессий, а RAM WSL2 (одна `pytest` за раз, 6 ГБ) |
+| Субагенты для повторяющихся работ | ✅ есть | 13 агентов в `.claude/agents/` |
+
+📄 **Самое сильное место главы — про «толстый AGENTS.md»:** один большой файл правил проигрывает
+оглавлению плюс дереву `docs/` по четырём причинам (контекст дефицитен · «важно всё» = не важно
+ничего · гниёт · непроверяемо). У нас это уже записано в
+[`sources-building-with-agents.md`](sources-building-with-agents.md) со ссылкой на OpenAI.
+
+⚖️ **И здесь же наше живое противоречие.** Наш `.claude/CLAUDE.md` растёт именно как толстый
+файл: каждое новое правило приезжает с абзацем обоснования и инцидентом. Прослеживаемость —
+наша сознательная ставка, но она платится контекстом в **каждой** сессии. Это стоит однажды
+измерить, а не решать вкусом.
+
+---
+
+## 4. Стадия Test — feedback loop и непрерывные evals
+
+📄 Первая половина главы — «дай агенту способ проверить себя»: одна команда сборки, одна команда
+тестов, измеримая цель, для багфикса — **сначала падающий тест, и хук запрещает агенту править
+тестовые файлы во время починки**.
+
+| Практика | У нас | Чем доказано |
+|---|---|---|
+| Одна команда на сборку/тесты/линт | ✅ есть | `make verify` / `make verify-full`, зеркало CI (task-327) |
+| Для бага — сначала падающий тест | ✅ есть | TDD-правило CLAUDE.md, RED от Tester до Builder |
+| Агент не может ослабить проверку, которую чинит | ✅ **есть, и своим способом** | `scripts/test-lock.sh snapshot` перед Builder → `verify` после; расхождение = стоп и разбор |
+| Проверка как условие «готово» | ✅ есть | Live-stack E2E перед сдачей человеку, `.claude/rules/testing.md` |
+| Визуальная петля для UI | ✅ есть | Playwright MCP, живой UI на `:8180` |
+
+📄 Вторая половина — **continuous evals**: 20–50 реальных задач с записанным приемлемым исходом,
+прогон в CI **на каждое изменение `CLAUDE.md`, скиллов и хуков**, порог прохождения как условие
+слияния, каждый прод-инцидент становится постоянным eval'ом.
+
+**❌ Этого у нас нет — и это главная дельта статьи.**
+
+📏 Замер конфигурации 2026-08-26:
+
+- в `.gitlab-ci.yml` whitelist «что считается кодом» перечисляет `.claude/hooks/**` и
+  `.claude/schemas/**` — их поведение защищает harness-suite;
+- `.claude/skills/**` (28 штук), `.claude/agents/**` (13), `.claude/rules/**` (8) и сам
+  `.claude/CLAUDE.md` в whitelist **не входят вовсе** — пуш, лежащий целиком в них, пайплайна
+  не создаёт;
+- в `.claude/skills/trigger-evals/` лежат **17 готовых наборов**, а прогонщика к ним нет —
+  это открытый пункт §8 реестра;
+- `scripts/` не содержит ни одного eval-скрипта;
+- единственный тест харнеса — `.claude/hooks/tests/test_require_graph_search.sh`, то есть один
+  хук из четырёх.
+
+**Что это означает практически:** правка описания скилла может молча выключить его загрузку, и
+единственный арбитр этого — «владелец заметит через день, читая доки». Именно так вскрылось
+отступление от ADR-018. И у нас уже есть **зафиксированный каталог** таких молчаливых поломок:
+пункт реестра «три расхождения в скиллах, найденные 2026-08-02» — `celery-tasks` описывает две
+полосы вместо шести, у `fsd-architecture` таблица разрешённых импортов **перевёрнута** и
+противоречит собственной диаграмме, `safe-migrations` предлагает опасный приём. Все три нашлись
+чтением человеком, не проверкой.
+
+⚖️ **Цена честно.** Каждый прогон eval-набора — это реальные токены, и делать его на каждый пуш
+при 17 наборах дорого. Плюс правило владельца: «гейт стережёт существующий артефакт» и «собрал
+базовый гейт → СТОП, строй продукт». И у нас открыт P0 «нет бэкапов». Поэтому это **кандидат в
+очередь, а не работа на сегодня** — но кандидат с самой высокой ставкой из всей статьи, потому
+что закрывает целый класс отказов, у которого сегодня арбитра нет вообще.
+
+📄 Дешёвый первый шаг, который статья же и подсказывает: гонять eval не на каждый пуш, а
+**на изменение `.claude/**` и по расписанию**. Тогда цена привязана к частоте правок харнеса,
+а не к частоте коммитов.
+
+---
+
+## 5. Стадия Deploy — ревью, хуки-ворота, CI/CD
+
+📄 Ревью работает в обе стороны: агент рецензирует чужие PR по записанной политике и сам
+чинит замечания в своих. Политика живёт файлом `REVIEW.md`: какие проходы (баги · безопасность ·
+соответствие спеке и плану), что считается Important, а что придирка, и потолок числа придирок.
+
+| Практика | У нас | Чем доказано |
+|---|---|---|
+| Агент в ревью | ✅ есть | агент `reviewer`, команда `/code-review`, `/code-review ultra` |
+| Человеческий гейт после ревью | ✅ **есть и строже статьи** | правило CLAUDE.md: после APPROVED — СТОП, ждать слов владельца; Archivist никогда не запускается автоматически |
+| Разделение обязанностей: писавший код не одобряет | ✅ есть | Builder ≠ Reviewer ≠ Archivist, тесты пишет Tester |
+| **`REVIEW.md` как отдельный файл политики** | ⬜ **частично** | политика есть, но в скилле `review-checklist` — то есть её читает наш агент, но её не читает внешний ревьюер (`/code-review`, боты в PR) |
+| Потолок числа придирок | ❌ нет | severity-уровни есть, лимита на объём — нет |
+| Находки ревью возвращаются в CLAUDE.md | ✅ есть | правило «повторный баг одного класса → новый гейт», Analyzer/Evolver в пайплайне |
+
+📄 **Хуки как ворота согласования** (не как ограничители): хук может не блокировать, а *спросить*,
+приостановив действие до одобрения конкретного человека. Не-отключаемые хуки живут в managed
+settings, которые инженер не может выключить.
+
+| Практика | У нас |
+|---|---|
+| Хук-ворота на опасное действие | ✅ есть — `block-dangerous-commands.sh` |
+| Хук-ворота на выкат в прод | ⬜ иначе: у нас ручная кнопка `deploy:production` в GitLab, а не хук |
+| Managed settings, которые нельзя отключить | ⛔ **не наш случай** — одна машина, один владелец; защищать не от кого |
+| Sandbox с сетевым allowlist, запрет чтения `~/.ssh`/`~/.aws` | ⚖️ **стоит перечитать** — единственный кусок «корпоративного» блока, который применим и соло: он защищает не от инженера, а от **угнанного агента** (см. `deep-research-2026-07.md` §1.2, CVE-2025-66032) |
+
+📄 CI/CD: агент работает non-interactive внутри пайплайна на местах, где нужно суждение
+(разбор упавшей сборки, флейки, черновик changelog), деплой выражается инструментами MCP с
+правами по окружению, **откат — самый отрепетированный путь в пайплайне**.
+
+📏 У нас откат отрепетирован **наполовину**: возврат на предыдущий образ — основной способ
+быстро чиниться, и он прямо назван в реестре причиной, почему `DROP TABLE` разводится на два
+выката (expand and contract). Но **восстановление данных не отрепетировано вовсе** — бэкапов
+нет, это P0. То есть у нас есть откат кода и нет отката данных.
+
+---
+
+## 6. Стадия Maintain — замыкание петли
+
+📄 Детерминированный скрипт следит за метрикой с устойчивым базисом (правила Western Electric),
+и при выходе за полосу **сам вызывает агента без человека в цепочке**: 1σ — только запись,
+2σ — диагностика только на чтение, 3σ — разрешено действовать, но лишь открыв PR в тот же
+гейт ревью или запустив заранее одобренный runbook. Найденное записывается как `intent.md` и
+входит в тот же конвейер.
+
+| Предпосылка | У нас |
+|---|---|
+| Централизованные логи | ✅ есть — Loki + Alloy (task-221) |
+| Метрики и алерты | ✅ есть — Prometheus/Grafana/Alertmanager |
+| **Трекинг прод-ошибок** | ❌ **нет** — P0 в реестре: исключения никто не группирует и не алертит |
+| Достоверные метрики веб-процесса | ❌ **нет** — `WEB_CONCURRENCY=4` без `PROMETHEUS_MULTIPROC_DIR`: `/metrics` отдаёт счётчики случайного процесса, и на этих данных работают два живых алерта |
+| Отрепетированный откат данных | ❌ нет — бэкапов нет |
+
+**Вывод по главе честный: замыкать петлю нам нечем и рано.** Автоматический вызов агента по
+аномалии требует приборов, которым можно верить, а у нас прямо сейчас есть
+задокументированный случай прибора, которому верить нельзя. Сначала §1 и §5 реестра, потом эта
+глава.
+
+⚖️ Отдельно про «Claude в Slack как первый респондент»: у нас нет команды дежурных, чью работу
+это ускоряет. Не наш случай сегодня.
+
+---
+
+## 7. Что забрать — по убыванию отношения пользы к цене
+
+| # | Что | Цена | Почему именно это |
+|---|---|---|---|
+| 1 | **Секция «Намерение» в шаблоне плана** — проблема словами владельца + чего человек лишён сегодня | строка в скилле `plan-template` | у нас уже был случай, когда план удалили, а намерение пришлось спасать вручную в реестр |
+| 2 | **Обязательное поле «конфликты и отступления» в плане** — где решение спорит с ADR/политикой, названо ДО кода | строка в шаблоне, не гейт | ADR-018 D5: отступление было записано в докстринге и найдено через день; правило дисциплины уже есть, ему не хватает **места в артефакте** |
+| 3 | **`REVIEW.md` в корне** — вынести политику ревью из скилла в файл, который читают и внешние ревьюеры | полдня | сегодня `/code-review` и любой бот не видят нашу политику вовсе |
+| 4 | **Eval-прогонщик по 17 готовым наборам**, запуск на изменение `.claude/**` и по расписанию | ощутимая: токены + день работы | закрывает единственный класс отказов, у которого сегодня арбитра нет; уже есть каталог из трёх молчаливо разошедшихся скиллов |
+| 5 | **Перечитать блок sandbox/credentials** статьи применительно к угнанному агенту, а не к инженеру | час чтения | единственная часть «корпоративного» раздела, применимая соло |
+
+**Чего в этом списке нет намеренно:** `intent.md` и `spec.md` отдельными файлами, managed
+settings, marketplace плагинов, Claude в Slack, замыкание петли по полосам. Первые два — налог
+без выигрыша при одном владельце; остальные — либо не наш масштаб, либо требуют приборов,
+которых нет.
+
+---
+
+## 8. Что статья подтверждает, не добавляя нового
+
+Это тоже результат, и его стоит назвать: по **plan-first, неизменяемости принятого плана,
+skills как институциональной памяти, хукам-ограничителям, feedback loop, разделению обязанностей
+в ревью и человеческому гейту перед коммитом** статья описывает ровно то, что у нас уже
+работает — местами мягче нашего. Мы пришли к этому раньше и из собственных инцидентов, а не по
+методичке.
+
+⚖️ Осторожность, которую стоит удержать: совпадение с чужой методичкой — **не** доказательство
+правильности. Это два независимых наблюдателя, а не арбитр. Арбитром остаётся то, что у нас
+ловит отказ: гейт, тест, замер.
+
+---
+
+## Связанное
+
+- Наш процесс по этапам — [`ai-sdlc.md`](ai-sdlc.md)
+- Наша ежедневная дисциплина — [`agent-harness-playbook.md` §18](agent-harness-playbook.md)
+- Практики с агентами из других источников — [`ai-native-development.md`](ai-native-development.md)
+- Срез практики индустрии 2026-08 — [`stream-2026-08-ai-coding-panel.md`](stream-2026-08-ai-coding-panel.md)
+- Угон агентов через недоверенный контент — [`deep-research-2026-07.md`](deep-research-2026-07.md) §1
+- Очередь работ по харнесу — `../rebuild/10-open-work-register.md` §8