agent-quality-kit 0.2.2

package/kit/docs/ai/index.md

@@ -0,0 +1,64 @@
+# Методички: разработка с агентами
+
+> **Что это за папка.** Полный корпус про разработку, когда код пишет агент. Раскладывается в
+> проект командой `aqk init` как `.aqk/docs/`.
+>
+> **Одна документация, без сокращённых копий.** Здесь лежат полные тексты. Если что-то кажется
+> лишним — это удаляется целиком и обоснованно, а не подрезается кусками.
+>
+> **Проверяемое живёт не здесь.** Здесь текст, который агент может проигнорировать. То, что держит
+> машина, — в `kit/gates/` (команда плюс красный и зелёный образец) и в `.aqk.yml` проекта.
+
+## С чего начинать
+
+| Если вы… | Читайте |
+|---|---|
+| ведёте проект как **владелец**, а не как программист | [Стратегия разработки приложений](app-owner-strategy.md) |
+| хотите список **что обязано быть на проекте**, без привязки к языку | [Обязательный минимум проекта](project-baseline.md) |
+| поднимаете **новый проект** с нуля | [Плейбук харнеса](agent-harness-playbook.md) |
+| хотите понять, **как работать каждый день** | [Плейбук харнеса](agent-harness-playbook.md), раздел 18 |
+| хотите увидеть **процесс по этапам** | [SDLC эпохи агентов](ai-sdlc.md) |
+| ищете **готовое правило**, прежде чем писать своё | [Готовые правила](../ready-made-rules.md) |
+| ставите **гейты** и хотите отличить работающий от мёртвого | `kit/gates/README.md` — норма записи, храповик, четыре способа вранья |
+
+## 1. Наше — применяется в работе
+
+| Документ | О чём | Класс |
+|---|---|---|
+| [`agent-harness-playbook.md`](agent-harness-playbook.md) | чек-лист «День 0»: конфиги, линтеры, хуки, CI, Docker. Раздел 18 — дисциплина в каждой задаче | PORTABLE |
+| [`project-baseline.md`](project-baseline.md) | что обязано быть на любом проекте, чтобы работу можно было отдать машине. Назначение без названий инструментов | PORTABLE |
+| [`ai-sdlc.md`](ai-sdlc.md) | процесс по этапам: от «зачем» до эксплуатации. Отвечает «в каком порядке», а не «каким инструментом» | CURRENT |
+| [`app-owner-strategy.md`](app-owner-strategy.md) | документ владельца: бизнес-ТЗ → ограничения → сайзинг → тех-дизайн | OWNER DOCTRINE |
+
+Журнал шишек лежит отдельно, в корне комплекта: `incidents/README.md`. Он общий на все проекты и
+пользователю не раскладывается.
+
+## 2. Чужое — доказательная база со сверкой
+
+Датированные снимки. Ресёрч от указанной даты не перестаёт быть правдой о том, что было прочитано,
+но перестаёт быть правдой о том, что есть сейчас. Где свежий файл перебивает старый, это отмечено
+внутри пометкой «⚠️ обновляет».
+
+| Документ | О чём | Дата сбора |
+|---|---|---|
+| [`anthropic-ai-native-sdlc-2026-08.md`](anthropic-ai-native-sdlc-2026-08.md) | плейбук Anthropic по перестройке SDLC под агентов, разобранный по шести стадиям | 2026-08-26 |
+| [`ai-native-development.md`](ai-native-development.md) | практики из двух каналов, каждая с отметкой «есть у нас / нет» | 2026-08-25 |
+| [`stream-2026-08-ai-coding-panel.md`](stream-2026-08-ai-coding-panel.md) | панель практиков: 🎙 мнение · 📏 замер · ⚖️ спорно | 2026-08-24 |
+| [`quality-gates-checklist.md`](quality-gates-checklist.md) | снимок 98 гейтов audit_project со статусами — сырьё каталога гейтов | 2026-08-24 |
+| [`harness-best-practices.md`](harness-best-practices.md) | каталог приёмов, снятых с чужих харнесов; устройство собственного агента исключено | 2026-07-13 |
+| [`deep-research-2026-07.md`](deep-research-2026-07.md) | gap-ресёрч: харнес · безопасность · качество кода · платформы | 2026-07-05 |
+| [`sources-building-with-agents.md`](sources-building-with-agents.md) | статьи OpenAI / Anthropic / Manus, с провенансом | 2026-07 |
+
+## 3. Что отсюда убрано и куда
+
+Ничего не подрезано кусками. Убраны только настоящие дубли — тексты, существовавшие в двух местах:
+
+| Было | Куда ушло целиком |
+|---|---|
+| `how-we-work.md` | `agent-harness-playbook.md`, раздел 18 |
+| `harness-lessons.md` | `incidents/README.md`, запись 2026-08-27 |
+| разделы «Скиллы» из `how-we-work.md` | `agent-harness-playbook.md`, раздел 13 |
+| правила кода и тестов из плейбука | `kit/rules/` — там они источник истины, в плейбуке указатель |
+
+Статусы «у нас» внутри чужих файлов относятся к `audit_project` и проверяются по коду, а не по
+этим документам: статусы в документах устаревают молча.

package/kit/docs/ai/project-baseline.md

@@ -0,0 +1,261 @@
+---
+title: Обязательный минимум проекта — что должно быть, чтобы код писала машина
+description: Список того, что обязано существовать на любом проекте, на любом языке, чтобы работу можно было отдать агентам и при этом видеть брак. Без названий инструментов — только назначение.
+tags:
+  - topic/ai
+  - kind/checklist
+---
+
+# Обязательный минимум проекта
+
+> **Зачем этот файл.** Цель владельца — «тёмная фабрика»: цех, где работа идёт круглосуточно и
+> людей у станка нет. Свет не нужен машине — но машине нужно другое: **видеть, что она делает,
+> ловить собственный брак и уметь остановиться**. Здесь перечислено ровно то, что для этого
+> обязано быть на проекте.
+>
+> **Как читать.** Никаких названий библиотек: они разные в каждом языке и устаревают за год.
+> Написано **назначение** — что должно уметь. Подбирать инструмент под язык — отдельная работа,
+> и она простая, когда известно, что именно ищешь.
+>
+> **Проверка себя на любом пункте:** «если это сломается — я узнаю сам, или мне расскажет
+> пользователь?» Второй ответ означает, что пункт не выполнен.
+
+---
+
+## 0. Главный принцип
+
+**Тёмная фабрика держится не на умных станках, а на приборах и на упорах.**
+
+- **Прибор** — показывает, что происходит: сколько, как быстро, где встало.
+- **Упор** (гейт) — не пускает брак дальше: не собралось, не сошлось, не по правилу — стоп.
+- **Арбитр** — независимо отвечает «правильно или нет», и его нельзя уговорить.
+
+Всё, что ниже, — это приборы, упоры и арбитры. Если чего-то из трёх нет, работу нельзя отдать
+машине: она будет производить брак быстро и молча.
+
+---
+
+## 1. Воспроизводимость: одинаково у всех и всегда
+
+1. **Одна команда поднимает проект целиком.** Не «установи, настрой, потом запусти» — одна.
+2. **Точные версии всего**, что участвует в сборке, записаны в файл и хранятся в репозитории.
+   Не «примерно та же версия» — точная.
+3. **Среда одинакова** на машине разработчика, в конвейере и на сервере. Расхождение сред — это
+   класс ошибок, который невозможно поймать тестами: «у меня работает» и есть его симптом.
+4. **Настройки приходят снаружи** (переменные окружения), а не лежат в коде. Один и тот же
+   собранный артефакт должен уметь работать и в тесте, и в бою.
+5. **Секреты не хранятся в коде вообще.** Ни в истории, ни в примерах, ни в тестах.
+
+---
+
+## 2. Упоры на входе в репозиторий
+
+Срабатывают до того, как код попал в общую ветку. Каждый — быстрый, иначе его начнут обходить.
+
+6. **Форматирование** — единый вид кода, применяется автоматически. Спор о пробелах должен быть
+   невозможен.
+7. **Линтер** — ловит подозрительные конструкции и заведомые ошибки без запуска кода.
+8. **Проверка типов** — если язык её поддерживает. Это самый дешёвый способ поймать «передал не
+   то» до запуска.
+9. **Поиск секретов** — ключ, пароль, токен не должны попадать в историю. Из истории их потом не
+   вычистить.
+10. **Ограничение размера файла** — и продуктового, и тестового. Файл, который не помещается в
+    поле внимания, перестают читать: и человек, и машина.
+11. **Свои инварианты проекта** — то, чего нет в готовых линтерах: «отладочная печать запрещена»,
+    «пометки „доделать“ запрещены», «невидимые символы запрещены», «вход разбирается на границе,
+    а не по месту», «широкая ловушка ошибок обязана либо записать причину, либо пробросить».
+12. **Проверка, что структура описана** — если в проекте есть карта («что где лежит»), добавление
+    модуля без правки карты не проходит.
+
+**Важнее списка — форма сообщения.** Отказ обязан говорить: что нарушено, где, **и как починить**.
+Отказ без инструкции превращается в «обойди меня».
+
+---
+
+## 3. Арбитры правильности
+
+13. **Тест, проверяющий поведение через внешнюю границу** — не внутренности. Вызвал как
+    пользователь, проверил ответ и состояние хранилища. Такой тест переживает переписывание кода;
+    тест на внутренности — нет.
+14. **Отдельные быстрые тесты на чистую логику** — расчёты, преобразования, разборы. Их много и
+    они дешёвые.
+15. **Эталон от авторитетного источника** там, где он есть: отчёт, выгрузка, документ. Сверка
+    «до копейки» с внешним источником сильнее любого написанного нами теста, потому что источник
+    не подстраивается под нас.
+16. **Прогон на живой системе перед сдачей** — как пользователь, через настоящий вход. Мок-тесты
+    структурно слепы на «швах»: сеть, прокси, перезапуски, регистрация фоновых задач, права.
+17. **Правило про количество:** тестов должно быть столько, сколько нужно для доказательства.
+    Мера — не проценты, а вопрос: «если поведение сломается, что покраснеет?» Если ответ «ничего» —
+    тестов мало. Если «двести тестов, и все про одно» — их много.
+18. **Тест на исправленный дефект.** Каждый прод-баг превращается в тест до того, как его чинят.
+
+---
+
+## 4. Конвейер
+
+19. **Собирается один артефакт** и он же едет во все среды. Пересборка под каждую среду означает,
+    что проверяли не то, что выкатили.
+20. **Дешёвое раньше дорогого**: форматирование и линт — секунды, тесты — минуты, тяжёлое — ночью.
+21. **Ясно, что блокирует, а что советует.** «Советует» допустимо временно и с зафиксированным
+    уровнем: не хуже, чем сейчас. Вечный совет — это украшение, его перестают читать.
+22. **Ветка, из которой выкатывают, защищена**: попасть туда можно только зелёным.
+23. **Откат дешевле починки.** Предыдущий артефакт лежит рядом и поднимается одной командой.
+24. ⚠️ **Тишина конвейера — это отказ, а не успех.** Обязательна проверка, что прогон вообще
+    случился: правка, не попавшая в список отслеживаемых путей, не запускает проверок — и не
+    появляется кнопка выката. Выглядит как «всё хорошо».
+
+---
+
+## 5. Приборы: наблюдаемость
+
+25. **Логи структурные** — не строки для глаз, а записи с полями, по которым можно искать.
+26. **Сквозной идентификатор запроса** проходит через все части системы. Без него нельзя собрать
+    историю одного случая.
+27. **Логи собираются в одно место** и хранятся столько, сколько нужно, чтобы разобрать
+    вчерашний инцидент.
+28. **Метрики четырёх видов**, минимум: сколько запросов, сколько ошибок, как быстро (по худшим
+    случаям, не по среднему), сколько ресурсов занято.
+29. **Очереди фоновых задач видны**: глубина и **возраст самой старой задачи**. Очередь, которая
+    встала, снаружи выглядит как «медленно работает».
+30. **Ошибки собираются отдельно от логов**, группируются по типу и умеют сообщить о новом типе.
+    Лог — это поток, в котором ошибка тонет; трекер ошибок — это список того, что сломалось.
+31. **Тревога только на то, из-за чего вы готовы встать ночью.** Остальное — отчёт, а не тревога.
+    Прибор, который звенит постоянно, выключают.
+32. **К каждой тревоге — короткая инструкция**, что делать. Иначе разбираться будет тот, кто её
+    получил, с нуля и в три часа ночи.
+33. **PII и секреты в логи не попадают** — ни в поля, ни в тексты ошибок.
+
+---
+
+## 5-бис. Приборы на сам процесс, а не только на продукт
+
+Раздел выше — про то, как живёт **система**. Этот — про то, как живёт **производство**. На тёмной
+фабрике это единственный способ понять, что цех работает, а не имитирует работу.
+
+Ниже — пять семейств. Мерить всё сразу не нужно; нужно знать, чего у вас нет.
+
+**А. Скорость потока (четыре классических)**
+- сколько времени проходит **от правки до боя** — главный показатель, всё остальное его объясняет;
+- **как часто выкатываем** — редкий выкат означает крупные партии, а крупная партия ломается дороже;
+- **какая доля выкатов ломает** прод;
+- **сколько занимает восстановление** после поломки. Быстрое восстановление ценнее редких поломок.
+
+**Б. Из чего складывается время** — чтобы знать, что чинить: время до первого коммита у новичка ·
+время сборки · время прогона проверок · доля падений конвейера · время до первого ревью · сколько
+раз изменение возвращается на доработку · размер изменения.
+
+**В. Качество проверок** — тот самый раздел, ради которого мы весь день работали: доля
+автоматизированных проверок · **доля пропущенных (`skip`) тестов** · **доля неустойчивых тестов**,
+которые падают через раз. Неустойчивый тест хуже отсутствующего: он приучает перезапускать, не
+глядя.
+
+**Г. Качество тревог** — приборы про приборы: сколько тревог приходит на человека · какая доля
+из них не требует действий · сколько тревог **никто не открывал ни разу**. Тревога, на которую
+никто не реагирует, — это выключенный прибор, который выглядит включённым.
+
+**Д. Нагрузка на голову** — сложность кода · сколько инструментов нужно тронуть ради одной правки ·
+сколько людей должны договориться. Для тёмной фабрики это переводится так: **сколько мест нужно
+изменить, чтобы поменять одно правило.** Если больше трёх — правило разъедется.
+
+**Как этим пользоваться, чтобы не навредить.** Метрика — термометр, а не цель: как только по ней
+начинают отчитываться, её начинают улучшать напрямую, и она перестаёт что-либо показывать. Смотреть
+на них надо парами, где одна сдерживает другую: скорость выката — вместе с долей поломок; число
+тестов — вместе с долей неустойчивых; число тревог — вместе с долей бесполезных.
+
+**Минимум, с которого стоит начать:** доля поломанных выкатов, время восстановления, доля
+неустойчивых тестов, доля тревог без действия. Четыре числа отвечают на вопрос «фабрика работает
+или имитирует».
+
+---
+
+## 6. Сохранность
+
+34. **Резервная копия данных по расписанию** — и **проверенное восстановление**. Копия, которую ни
+    разу не разворачивали, копией не является.
+35. **Копия лежит не на том же диске**, что и сама база.
+36. **Тревога на отсутствие свежей копии.** Бэкап ломается молча: вчера он был, сегодня его нет,
+    и узнают об этом в день аварии.
+37. **Файлы пользователей защищены правами**, а не незнанием адреса. Ссылка, которую нельзя
+    угадать, — это не право доступа.
+38. **Понятно, что делать при потере**: срок, за который данные восстанавливаются, и объём, который
+    допустимо потерять, названы числами заранее.
+
+---
+
+## 7. Что нужно именно машине (а не человеку)
+
+39. **Проект читается машиной**: где что лежит, как запустить, как проверить — записано в
+    репозитории, а не в голове.
+40. **У агента есть способ проверить себя**: запустить тесты, поднять приложение, прочитать логи,
+    посмотреть метрики. Без этого он вынужден заканчивать словами «готово», и это слово ничего не
+    стоит.
+41. **Сообщение об ошибке — это подсказка агенту.** Инструкция в тексте отказа стоит дешевле, чем
+    любые объяснения в документации: она приходит ровно в тот момент, когда нужна.
+42. **Правила живут в репозитории и версионируются** вместе с кодом. Правило в переписке не
+    существует.
+43. **Знание фиксируется там, где оно понадобится**: решение — рядом с решением, предупреждение —
+    рядом с опасным местом.
+
+---
+
+## 8. Дисциплина против самообмана — самое важное
+
+Этот раздел отличает работающую фабрику от красивой. Всё выше можно поставить и получить
+**видимость** защиты.
+
+44. **У каждого упора должен быть образец, на котором он обязан сработать.** Файл с нарушением —
+    отказ; чистый файл — молчание. Оба образца лежат в репозитории и проверяются на каждом прогоне.
+    Упор без образца доказывает лишь то, что он запускается.
+45. **Ломай упор нарочно и смотри, заметил ли это образец.** Иначе рано или поздно получится
+    сторож, который зелен всегда — и никто не узнает.
+46. **Проверка обязана выносить вердикт словом**, а не пустым выводом. Пустой вывод читается как
+    «прошло» и оказывается «не проверялось».
+47. **Долг записывается поимённо и может только убывать.** Список исключений с причинами — это
+    очередь. Список без причин — это индульгенция.
+48. **Условие внедрения записывается машинно, а не словами.** «Когда появятся такие-то файлы —
+    завести проверку» само не сработает: нужен скрипт, который читает репозиторий и говорит
+    «условие наступило, сторожа нет».
+49. **Документ, утверждающий, что защита есть, ничего не доказывает.** Проверяется замером, а не
+    чтением. Запись о состоянии устаревает молча.
+50. **Повторившийся дефект превращается в упор**, а не в напоминание быть внимательнее. Дисциплина
+    не масштабируется, механика — да.
+
+---
+
+## 9. Порядок внедрения на новом проекте
+
+1. **Сначала воспроизводимость** (§1). Пока среда разъезжается, всё остальное меряет шум.
+2. **Потом упоры на входе** (§2) — они дешёвые и дают эффект сразу.
+3. **Потом один настоящий арбитр** (§3): один сквозной тест «как пользователь», который падает,
+    когда сломано. Один настоящий важнее двадцати формальных.
+4. **Потом конвейер** (§4) — чтобы упоры и арбитр работали без вас.
+5. **Потом приборы** (§5) — когда есть что наблюдать.
+6. **Сохранность** (§6) — до того, как появятся данные, которые жалко потерять, а не после.
+7. **Образцы для упоров** (§8) — вместе с каждым упором, а не «потом».
+
+**Чего не делать:** ставить инструмент, которому нечего охранять. Упор без объекта — это шум,
+который приучает игнорировать отказы.
+
+---
+
+## 10. Как проверить, что фабрика правда тёмная
+
+Семь вопросов. Ответ «не знаю» равен «нет».
+
+1. Если сломается — я узнаю раньше пользователя?
+2. Если упор сломается — я узнаю? Чем именно?
+3. Могу ли я поднять систему заново на чистой машине одной командой?
+4. Разворачивали ли мы резервную копию хоть раз?
+5. Могу ли я по одному идентификатору собрать историю одного случая целиком?
+6. Знаю ли я, где у меня нет арбитра вовсе — то есть где я полагаюсь на слово?
+7. Что случится, если я не буду смотреть на проект неделю?
+
+Последний вопрос — и есть определение тёмной фабрики.
+
+---
+
+## Связанное
+
+- Инструменты и конфигурации нашего проекта — [`agent-harness-playbook.md`](agent-harness-playbook.md)
+- Процесс по этапам — [`ai-sdlc.md`](ai-sdlc.md)
+- Наша дисциплина и её история — [`agent-harness-playbook.md` §18](agent-harness-playbook.md)