agent-quality-kit 0.2.2

package/kit/docs/ai/agent-harness-playbook.md

@@ -0,0 +1,596 @@
+<!-- источник: audit_project/docs/ai/agent-harness-playbook.md -->
+# Плейбук: харнес для разработки с ИИ-агентом (воспроизводимый опыт)
+
+> **Что это.** Методичка «как поднять новый проект, где код пишет агент, а человек рулит».
+>
+> ⚠️ **Честно о переносимости.** Разделы 0, 4, 6–8, 11–18 не зависят от языка. Разделы 2 и 3 —
+> **конкретика Python и GitHub Actions**: это снимок с живого проекта, а не универсальный рецепт.
+> На другом стеке читать их как образец рассуждения, а не как список команд.
+> Дистиллят того, что мы внедрили и проверили на memo + чего решили НЕ внедрять и почему + что
+> обязаны внедрить позже (с триггерами). Формат — TODO-чеклист: открой на новом проекте и иди сверху вниз.
+> Живой эталон каждого конфига — этот репозиторий (пути указаны у каждого пункта).
+>
+> **Источники:** reference-проект `audit_project`; gap-анализ обвязки 2026; AIE World's Fair 2026
+> (харнес > модель, receipts/replay, production evals, review debt); Karpathy Sequoia Ascent 2026;
+> Hashimoto/OpenAI harness engineering; наш опыт memo (все грабли — из реальных инцидентов).
+
+---
+
+## 0. Философия (прочитай, прежде чем копировать конфиги)
+
+1. **Харнес важнее модели.** Узкое место — не интеллект модели, а среда: гейты, трейсы, границы,
+   обратная связь. Та же модель в хорошем харнесе работает кратно лучше.
+2. **Гейты вместо надзора.** Качество держат детерминированные автоматические проверки с
+   fix-инструкцией в тексте ошибки — не «постараюсь лучше» и не построчный надзор человека.
+   Повторный баг одного класса → **новый гейт** (тест/линтер/хук), а не воспитание агента.
+3. **Гейт стережёт существующий артефакт.** Не ставь линтер на код, которого нет, — это мёртвое
+   правило, шум и ложное чувство защищённости. Каждому отложенному инструменту — **триггер** (§8).
+4. **Гейты — в первом коммите.** Гейт, добавленный потом, — долг (весь старый код красный);
+   добавленный сразу — множитель. День 0 нового репо = день установки харнеса (§2–§5), код — потом.
+5. **60–70% бюджета агента — в обвязку и техдолг**, не в фичи. Скучно, но после 1–2 недель
+   «наведения порядка» фичи начинают ехать кратно быстрее.
+6. **Детерминизм > LLM-judge.** Всё, что можно проверить кодом, — проверяем кодом. LLM-проверки —
+   только там, где код не справляется (и калибруем по человеку).
+7. **Чего нет в контексте — не существует.** Знание проекта живёт в репо (доки, правила, скрипты),
+   а не в голове и не в чате. Команды — copy-paste-исполнимые, не «запусти тесты».
+8. **Docker-first.** Всё исполняется в контейнерах. Локальные запуски мимо compose плодят мусор
+   (`dist/`, логи) и «у меня работает». Правило: `make up`, не `npm run dev` на хосте.
+9. ⚠️ **Review debt — риск №1 делегирования.** Код генерится быстрее, чем человек его понимает.
+   Гейты ловят механику, но НЕ ловят «согласился на дизайн, которого не понял». Противоядие:
+   заставляй агента **объяснять цепочку целиком** (архитектуру, «что с чем связано»), решения — в ADR.
+10. ⚠️ **Переинжиниринг харнеса — реальная ловушка.** Харнес — средство. Собрал базовый гейт →
+    СТОП, строй продукт. Остальное — из трения (баг повторился → гейт).
+11. **Мышление можно аутсорсить, понимание — нельзя** (Karpathy). Человек остаётся владельцем
+    «зачем», инвариантов и вкуса; агент — исполнения.
+
+---
+
+## 1. Чек-лист «День 0» — краткая карта (детали в §2–§5)
+
+- [ ] §2.1 git-гигиена: `.gitignore`, `.gitattributes` (LF для `*.sh`!), `.env`/`.env.example`
+- [ ] §2.2 `pyproject.toml`: uv + ruff (полный набор групп) + mypy + pytest
+- [ ] §2.3 `.pre-commit-config.yaml` + `bandit.yaml` + `pre-commit install`
+- [ ] §2.4 `scripts/arch-lint.sh` (свой линтер: print/TODO/NBSP/лимиты строк)
+- [ ] §2.5 `Makefile` (up/down/logs/migrate/test/lint/format/typecheck/arch-lint/precommit)
+- [ ] §3 CI: `.github/workflows/ci.yml` (статика · security · тесты)
+- [ ] §4 `.claude/`: CLAUDE.md, settings.json (allow/ask/**deny**), 3 хука, rules/, агенты-критики
+- [ ] §5 Docker: compose (web+db+frontend), healthcheck, `.dockerignore`
+- [ ] §6 Правила кода и §7 правила тестов — скопировать в `.claude/rules/`
+- [ ] §8 Прочитать таблицу отложенного арсенала, выписать триггеры под свой проект
+- [ ] §10 Если на Windows — прочитать грабли ДО первого хука
+
+---
+
+## 2. Python-фундамент
+
+### 2.1. Git-гигиена (5 минут, спасает часы)
+
+- [ ] `.gitattributes`: `*.sh text eol=lf` — **обязательно**. CRLF ломает shebang
+      (`#!/usr/bin/env bash\r`) в контейнере/WSL/хуках. Грабля реальная (memo, 2026-07).
+- [ ] exec-бит скриптам через git (Windows его не хранит):
+      `git update-index --chmod=+x путь/скрипт.sh`
+- [ ] `.env` в `.gitignore`; рядом `.env.example` с дев-дефолтами и комментами «как получить секрет».
+- [ ] Секреты в коде — никогда; только `os.environ`. (Двойная защита: deny на чтение `.env`
+      в §4.2 + gitleaks/detect-private-key в §2.3/§3.)
+
+### 2.2. `pyproject.toml` — всё в одном файле (эталон: `pyproject.toml` memo)
+
+- [ ] **uv** как менеджер (lock = воспроизводимое окружение; `[tool.uv] package = false` для приложения).
+- [ ] dev-группа: `pytest`, `pytest-django`(если Django), `ruff`, `mypy`, `pre-commit`.
+- [ ] **ruff** — линтер+форматтер одним тулом. Группы и ЗАЧЕМ каждая:
+
+| Группа | Что ловит | Почему обязательна для кода агента |
+|---|---|---|
+| `E,F` | база pycodestyle/pyflakes | неиспользуемые импорты/переменные — агент их плодит |
+| `I` | сортировка импортов | детерминизм диффов |
+| `B` | bugbear: мутабельные дефолты, ловушки | классические «правдоподобные» баги LLM |
+| `UP` | устаревший синтаксис | агент тянет паттерны из старых данных |
+| `DJ` | Django-специфика (`__str__`, порядок Meta) | реально ловил у нас DJ008/DJ012 |
+| `SIM` | упрощения | анти-слоп: агентный код ×2.3 многословнее |
+| `RUF` | ruff-специфика | — |
+| `DTZ` | naive datetime | бомба в любом дат-домене (аудит, отчёты) |
+| `T20` | запрет `print` | агенты обожают print-отладку |
+| `PT` | стиль pytest (составные assert и пр.) | точная диагностика падений |
+| `RET` | лишние return/else | анти-слоп |
+| `LOG,G` | корректность logging | f-string в логгере, потерянные exc_info |
+| `C90` | цикломатическая сложность, `max-complexity=10` | агент сам режет монолитные функции |
+
+- [ ] ignore: `RUF001/002/003` (если код/комменты на русском — иначе шум «кириллица похожа на
+      латиницу»), `RUF012` (Django class-level атрибуты — идиоматика).
+- [ ] per-file-ignores: `*/migrations/* = ["ALL"]`, `manage.py = ["I001","T20"]`,
+      `scripts/* = ["T20"]`, тесты — `F401`.
+- [ ] **mypy лёгкий** (не strict на старте): `ignore_missing_imports=true`,
+      `check_untyped_defs=true`, files = только прод-пакеты. Strict + django-stubs — по триггеру §8.
+
+### 2.3. `.pre-commit-config.yaml` — гейт коммита (эталон: наш файл)
+
+Принцип: **pre-commit = быстрая кроссплатформенная статика (секунды)**; тяжёлое (Go/Docker-бинари,
+тесты с БД) — в CI на Linux. Иначе на Windows гейт развалится или все будут его обходить.
+
+- [ ] `pre-commit-hooks`: `end-of-file-fixer` (exclude: `uv.lock`, прозаические `docs/`),
+      `trailing-whitespace` (exclude: `docs/`), `check-merge-conflict`, **`detect-private-key`**,
+      `check-added-large-files`, `check-yaml`, `check-toml`.
+- [ ] Если продукт выдаёт СВОИ секреты (API-ключи) — **`.gitleaks.toml` с правилом под их формат**
+      (префикс типа `xxx_sk_live_` и делает ключ обнаружимым сканером; эталон: наш `.gitleaks.toml`).
+- [ ] `ruff` (`--fix`) + `ruff-format`.
+- [ ] `bandit` (+ `bandit.yaml`: exclude tests/migrations; skips пустой) — статик-аудит безопасности.
+- [ ] `shellcheck-py` — **весь bash под статикой** (хуки, скрипты). Bash — самый багоопасный язык в репо.
+- [ ] `check-jsonschema → check-github-workflows` — сломанный CI-yaml ловится локально.
+- [ ] local: `arch-lint` (§2.4).
+- [ ] Установить: `uv run pre-commit install`. Прогнать всё: `uv run pre-commit run --all-files`.
+- [ ] ⚠️ Вайтспейс-фиксеры НЕ пускать в прозаические доки/сырые данные (`exclude: ^docs/`) —
+      иначе хук «редактирует» чужую работу при каждом прогоне.
+
+### 2.4. `scripts/arch-lint.sh` — свой линтер инвариантов (эталон: наш файл)
+
+То, чего нет в готовых линтерах. Каждая ошибка — **с fix-инструкцией в тексте**:
+
+- [ ] Запрет `print()` (py) / `console.log` (js/jsx) в прод-коде → «замени на logging».
+- [ ] Запрет `TODO/FIXME/HACK` → «заведи задачу в spec/plans/, маркер убери».
+- [ ] Запрет NBSP (невидимый \xc2\xa0 — агент вставляет из markdown).
+- [ ] **Лимиты размера** (агент уходит в рефакторинг/теряется на больших файлах):
+      прод-`.py` > **500** строк = error · компонент `.jsx/.tsx` > **300** = warn →
+      декомпозиция · тест-файл > **800** = error → разбить по доменам / `parametrize`.
+- [ ] Два режима: с аргументами (pre-commit, только staged) / без (полный скан, `make arch-lint`).
+
+### 2.5. `Makefile` — единый интерфейс команд (агенту и человеку)
+
+- [ ] `up/down/logs/migrate` (docker compose), `test` (pytest В КОНТЕЙНЕРЕ — реальный стек),
+      `test-local`, `lint`, `format`, `typecheck`, `arch-lint`, `precommit`.
+- [ ] Все команды copy-paste-исполнимые; `make help` перечисляет. Это «CLAUDE.md для рук».
+
+---
+
+## 3. CI (GitHub Actions) — эталон: `.github/workflows/ci.yml`
+
+Три параллельные джобы, fail-fast (дешёвое — первым):
+
+- [ ] **quality**: `uv sync --frozen` → `ruff check` → `ruff format --check` → `arch-lint`.
+- [ ] **security**: `gitleaks dir .` (секреты, сильнее detect-private-key) · `hadolint` на все
+      Dockerfile · `actionlint` (валидация самих workflow) · `pip-audit` по `uv export`
+      (известные CVE в зависимостях). Всё — скачиванием бинарей, на Linux это секунды.
+- [ ] **tests**: сервис `postgres:17` c healthcheck → `makemigrations --check --dry-run`
+      (**поменял модель — забыл миграцию** = красный) → `migrate` → `pytest`.
+- [ ] Branch protection на main: merge только через зелёный CI (включить в настройках GitHub).
+- [ ] Nightly-джобы — по триггерам §8 (mutmut, trivy, schemathesis, lychee).
+
+---
+
+## 4. Харнес агента — `.claude/` (самая недооценённая часть)
+
+### 4.1. `CLAUDE.md` — конституция, < 200 строк
+
+- [ ] Только: карта проекта (указатель на README/доки), язык, ключевые правила-принципы,
+      команды НЕ дублировать (они в Makefile). Раздутый CLAUDE.md агент игнорирует.
+- [ ] **Эмпирика 2026 (ETH Zurich + Vercel):** LLM-сгенерированные контекст-файлы СНИЖАЮТ успех (~−3%)
+      и удорожают на 20–23%; курируемые человеком дают +4 п.п. Критерий каждой строки: «агент не может
+      открыть это сам» — иначе удалить. Skills НЕ срабатывают сами в 56% случаев → правила подключать
+      явными указателями («перед задачей Y читай docs/X»), не надеждой на автотриггер. Бюджет ~150–200
+      надёжных инструкций на разговор («CLAUDE.md = RAM, docs/ = диск»).
+- [ ] Обязательные правила (проверены на memo):
+  - «Код — только после принятого плана и явного го» (человек владеет scope).
+  - «Путь файла в первой строке» (`# file: ...`) — агент и человек всегда знают, где находятся.
+  - «Развилки: варианты + рекомендация» — против молчаливых решений (анти-review-debt).
+  - «Статус — в git/коде, НЕ в доках» (прогресс в доках гниёт). Доки — только durable.
+  - «Обратимое и под гейтом → делай + запиши почему; необратимое → жди» (автономия с границами).
+  - «e2e на поведение > бесконтрольные юнит»; «повторный баг → новый гейт».
+  - Ссылки на `.claude/rules/*` (правило 14 в memo).
+
+### 4.2. `settings.json` — permissions тремя слоями (эталон: наш)
+
+- [ ] `allow`: базовые тулы (Bash, Read, Edit, Write, Glob, Grep, Web*).
+- [ ] `ask`: обратимое-но-опасное — `rm*`, `git reset --hard`, `git clean`, `push --force`,
+      `branch -D`, PowerShell-эквиваленты (`Remove-Item` и др. — на Windows у агента ДВЕ оболочки!).
+- [ ] `deny` (жёсткое «нет», не обсуждается): **`Read(./.env)`, `Read(./.env.*)`,
+      `Read(./secrets/**)`** (секрет не должен попасть в контекст агента = в логи API) +
+      force-push / reset --hard / `docker volume rm` / `docker system prune` / `rm -rf /` и `~`.
+- [ ] hooks-секция: PreToolUse → block-dangerous; PostToolUse(Write|Edit) → auto-format;
+      Stop → stop-gate. (Код — §4.3.)
+
+### 4.3. Три хука (эталоны: `.claude/hooks/*.sh` memo)
+
+| Хук | Событие | Что делает | Ключевые детали |
+|---|---|---|---|
+| `block-dangerous-commands.sh` | PreToolUse (Bash **и** PowerShell) | exit 2 + причина в stderr на необратимое: force-push, reset --hard, `DROP DATABASE`, `TRUNCATE`, `docker volume rm`, `rm -rf /` | fail-safe: не распарсил JSON → грепай сырой ввод. Штатный сброс дев-БД (`compose down -v`) — НЕ блокировать |
+| `auto-format.sh` | PostToolUse (Write\|Edit) | `ruff format` + `ruff check --fix` на изменённый `.py` | агент физически не оставляет неотформатированный код, контекст не тратится |
+| `stop-gate.sh` | Stop | красный `ruff` по прод-путям → exit 2 + хвост ошибок → агент чинит, а не «сдаёт» | обязателен гард `stop_hook_active` (иначе вечный цикл); проверять только СВОЙ домен, не параллельную работу человека |
+
+- [ ] ⚠️ **Грабля №1 (Windows): `jq` нет в Git Bash.** Хук с `command -v jq || exit 0` молча
+      превращается в no-op — защита «есть», но не работает. Парсить JSON через
+      `python -c "import sys,json..."` с fallback-цепочкой jq → python → сырой greп.
+- [ ] **Проверяй хуки функционально**: подай JSON с опасной командой → жди exit 2; безопасной →
+      exit 0. Хук, который никогда не тестировали, = хука нет. (Наш сам себя доказал:
+      заблокировал мою же тест-команду с `git push --force`.)
+- [ ] Каждому `.sh`: exec-бит через git (§2.1) + LF (§2.1) + shellcheck (§2.3).
+- [ ] Политика хуков: PreToolUse < 100 мс, узкие матчеры (не `.*`), тяжёлое — в PostToolUse; внешние
+      вызовы — таймаут 1–2 с и **fail-open с логом** (гейт не должен вешать агента). Проверить, что
+      deny-хуки держатся в bypassPermissions-режиме (`permissionDecision: "deny"` — единственный
+      несгораемый гейт). Каждый хук-запрет ссылается на rules-файл «почему и как правильно».
+- [ ] **Supply chain самого харнеса:** сторонние MCP-серверы/skills/plugins — только после ручного
+      аудита исходников + пин версии; их описания (SKILL.md, tool descriptions) = недоверенный ввод
+      (tool poisoning — реальный вектор 2026: 40% MCP-серверов без auth, вредоносные skills в маркетплейсах).
+
+### 4.4. `.claude/rules/` — стандарты по доменам
+
+- [ ] 5 файлов: `general.md` (принципы, запреты, лимиты, DoD), `security.md` (главный инвариант
+      проекта словами! + секреты/хэши/недоверенный контент), `testing.md` (§7),
+      `backend-*.md`, `frontend-*.md` — **под свой реальный стек**, вырезав правила про
+      технологии, которых нет (мёртвые правила = шум, агент перестаёт верить остальным).
+- [ ] Формат правила: не «пиши хорошо», а конкретика + почему + чем энфорсится
+      («лимит 500 строк — гейт arch-lint»). Правило без гейта — пожелание.
+
+### 4.5. Агенты-критики и память
+
+- [ ] Субагенты `gap-finder` / `devils-advocate` (read-only) — самопроверка планов/доков
+      **свежим контекстом** (self-review предвзят — confirmation bias).
+- [ ] Память агента: индекс + один факт = один файл; писать туда предпочтения человека и
+      процессные уроки, НЕ то, что уже записано в репо/git.
+- [ ] Cross-model / свежая-сессия ревью больших кусков — по возможности.
+
+---
+
+## 5. Docker-first
+
+- [ ] compose в **корне** (`compose.yml` — тогда `docker compose` работает без `-f`), Dockerfile — в `infra/`.
+- [ ] Минимум сервисов под текущий срез (web+db+frontend). Celery/Redis/observability — когда
+      появится работа для них, не «на вырост» (мы ровно это выпиливали из memo).
+- [ ] healthcheck у stateful; `depends_on: condition: service_healthy`; конфиг только env; логи в stdout JSON.
+- [ ] `.dockerignore`: `node_modules`, `dist`, `*.log`, `.git`.
+- [ ] Windows bind-mount: vite/webpack HMR не видит изменений → `usePolling: true` в конфиге.
+- [ ] Правило людям и агентам: **на хосте dev-серверы не запускать** — артефакты (`dist/`,
+      `*.log`) плодятся в рабочей папке. Появились — ищи, КТО запускает мимо Docker.
+
+---
+
+## 6–7. Правила кода и тестов
+
+Здесь их нет намеренно. Правила живут в `kit/rules/` и уезжают в проект как `.aqk/rules/`:
+
+| Файл | О чём |
+|---|---|
+| `general.md` | принципы, что запрещено в готовом коде, пределы размеров, новая зависимость, разбор входа на границе, коммиты, объяснение диффа, определение «готово» |
+| `testing.md` | поведение важнее реализации, порядок «красный тест первым», как написан сам тест, арбитр нельзя подгонять, живой прогон перед сдачей |
+| `security.md` | секреты, недоверенный ввод, права, необратимое, логи |
+
+**ПОЧЕМУ указатель, а не копия.** Правила агент читает всегда, методичку — по надобности. Две
+копии одного правила через месяц врут по-разному, и непонятно, какая настоящая.
+
+---
+
+## 7.1. Как ввести правило в проект, где старый код ему не соответствует
+
+Не «большой чисткой» и не необязательным предупреждением. **Храповиком:** файл со списком текущих
+нарушений; гейт разрешает список укорачивать и запрещает удлинять.
+
+Чистка откладывается навсегда, потому что она большая. Необязательное предупреждение не блокирует
+ничего, его листают, и правило не действует. Храповик даёт действующее правило **со дня установки**,
+не требуя трогать старый код.
+
+Проверка, что это храповик, а не советчик: «может ли новый код добавить нарушение и пройти?»
+Может — значит гейта нет.
+
+Механика, поля записи и остальные требования к гейту — в `kit/gates/README.md`. Ступень AQK-2
+требует именно этого: заполненные `samples` и `ratchets` в манифесте.
+
+---
+
+## 8. Отложенный арсенал — внедрить ПО ТРИГГЕРУ (не раньше и не позже)
+
+> Это часть методички, а не «может быть»: при наступлении триггера инструмент **обязателен**.
+> На memo зафиксировано в ADR 006 (`spec/decisions/006-quality-gates.md`).
+
+| Инструмент | Триггер внедрения | Что даёт |
+|---|---|---|
+| **import-linter** | ≥2 модулей со строгими границами (напр. scoring/runtime) | границы монолита конфигом, не дисциплиной; «ядро скорера не импортирует django» |
+| **django-migration-linter** + `check --deploy` | первые нетривиальные миграции домена | ловит обратно-несовместимые миграции (самая дорогая ошибка) |
+| **mypy strict + django-stubs** | стабилизация моделей/сервисов | типы = feedforward для агента |
+| **schemathesis** (nightly) | появился OpenAPI-контракт | property-фаззинг всех эндпоинтов против схемы бесплатно |
+| **hypothesis** | генератор/скорер (любая чистая детерминированная логика) | property-тесты: seed→байт-в-байт; score детерминирован и в границах |
+| **mutmut** (nightly) | ядро скорера/критическая логика | выжившие мутанты = слепые зоны тестов = завышенный балл |
+| **pre-flight null/random/injection-агенты** | каждая новая задача бенчмарка | тривиальный агент набрал >0 → задача/скорер сломаны |
+| **deny Edit на `tests/e2e/**`** (PreToolUse) | появились залоченные e2e-контракты | агент не переписывает арбитра под свой сломанный код |
+| **radon/xenon, vulture, jscpd** | заметный объём прод-кода | анти-слоп: сложность, мёртвый код, дубли |
+| **semgrep** (кастомные правила) | появились свои инварианты сложнее grep | инварианты как правила с fix-сообщением |
+| **trivy** (nightly) | публикуемые Docker-образы | CVE в образах |
+| **diff-cover** | стабильный test-suite | покрытие только изменённых строк (не роняем, не требуя 100% на легаси) |
+| **testcontainers** | интеграционные тесты вне compose | эфемерный PG на тест |
+| **Renovate/Dependabot** | выход в постоянную разработку | SCA-обновления зависимостей |
+| **markdownlint + lychee** (nightly) | докоцентричный репо стабилизировался | битые ссылки = детектор doc-гниения |
+| **FSD + TypeScript strict** (фронт) | плановая переделка фронта (отдельный срез!) | слои + eslint-boundaries; НЕ болтом поверх живого кода |
+| **React Query + queryKeys-guardian** | фронт начал реально ходить в API за данными | единые ключи кэша, guardian-скрипт в CI |
+| **Stop-хук с тестами** (не только ruff) | тесты стали быстрыми/стабильными в контейнере | полный Ralph-loop: «не завершай, пока не зелёное» |
+| **OTel GenAI semconv** | продукт пишет трейсы агентов | стандартная схема спанов, без вендор-лока |
+| **microVM/egress-allowlist** | публичная фаза платформы с чужим кодом | анти-чит и изоляция; раньше — карго-культ |
+| **aislop** (слоп-линтер) | заметный объём прод-кода; сперва advisory | 50+ детерминированных правил слопа (narrative-комменты, swallowed exceptions, hallucinated imports, дубли); заменяет vulture+jscpd+самописное |
+| **pytest-archon** (вместо/рядом с import-linter) | ≥3 модулей со строгими границами | архитектурные границы как pytest-тесты — в существующий `make test`, без нового CI-шага |
+| **test lock** (deny Edit тестов-верификаторов) | первые e2e ИЛИ первый случай «агент подогнал тест» | SpecBench: o3 хакает 30% прогонов удалением тестов/патчем верификатора |
+| **OTel самого Claude Code** | вопрос «куда уходят токены» / рост правил | встроенная телеметрия агента (tokens/task, cost, retry) — env-переменные, ноль разработки |
+| **cross-model review** (codex-плагин) | security-чувствительные/крупные срезы | чужая модель без сикофантии к своему коду; официальный плагин OpenAI для Claude Code |
+| **ignore-scripts + require-hashes + cooldown версий** | прод-зависимости / переход на pnpm | блок postinstall-атак и свежезарегистрированных пакетов (волны Shai-Hulud) |
+| **CSP (Django 6.0) + django-axes/ratelimit + `check --deploy` в CI** | перед первым внешним доступом | XSS-кража JWT; брутфорс логина; прод-мисконфиг |
+| **credential proxy** (Infisical Agent Vault) | реальные прод-ключи в окружении агента | «агент никогда не видит секрет»: подстановка кред ниже процесса агента |
+| **Code Durability + rework rate** | «хотим мерить прогресс» | доля кода, дожившего N недель (по git); анти-LOC-метрика ценности |
+| **progress-file + одна-фича-за-сессию** (Anthropic long-running) | многосессионные длинные срезы | feature-list JSON + smoke на старте сессии; главный failure mode — one-shot с обрывом контекста |
+
+## 9. Если твой продукт — платформа ДЛЯ агентов (уровень memo)
+
+Твой продукт и твой dev-харнес устроены одинаково — это не совпадение (ключ ответов вне
+досягаемости агента = e2e-контракты вне досягаемости кодера):
+
+- **The Log Is The Agent**: журнал (TraceEvent) — основа архитектуры; проектируй ЕГО первым.
+- **Record/replay**: полнота трейса такая, что прогон реплеится без LLM; инцидент → тест.
+- **Receipts**: каждое действие — проверяемый чек (что вызвал, с чем, что подтвердилось).
+- **Оси, а не цифра**: исход + процесс + безопасность + стоимость + восстановление; одна цифра —
+  произвольная свёртка для лидерборда, истина — разбивка.
+- **Минимум тулов** (3–4); рост → semantic routing, не 100 тулов в промпт.
+- **Анти-гейминг — инженерия, не промпт**: чек-лист BenchJack (8 классов дыр), «баланс сошёлся» —
+  необходимое, но НЕ достаточное (AccountingBench: агенты выдумывают транзакции под чек).
+- **Харнес — единица оценки**: балл без записи полной конфигурации харнеса невоспроизводим.
+- **CapCode-принцип**: подмешивай задачи с заведомо недостижимым честным 100% — балл выше потолка =
+  статистическое доказательство читерства (детекция по построению, не латание дыр).
+- **Интервалы, не точки**: pass@1 гуляет на 2–6 п.п. даже при temp=0 → 3–5 прогонов на пару
+  (агент, задача), pass@k/pass^k как границы, reliability (дисперсия) — отдельная колонка (пивот HAL).
+- **Пул задач**: в зачёте — pass-rate 30–70% (режет объём на 44–70% без потери ранжирования);
+  корреляция public/private рангов = метрика здоровья экзамена.
+- **Не изобретать домен**: сперва прочесть соседние бенчмарки (для сверки — FinBalance, AuditFlow),
+  переиспользовать таксономии ошибок, дифференцироваться платформой (seed-генерация, арена, трейс).
+
+## 10. Грабли Windows (проверено кровью memo)
+
+1. **`jq` нет в Git Bash** → все «стандартные» примеры хуков молча не работают. Fallback на python (§4.3).
+2. **CRLF ломает shebang** → `.gitattributes: *.sh text eol=lf` в первом коммите.
+3. **exec-бит не хранится** → `git update-index --chmod=+x` на каждый новый `.sh`.
+4. **PowerShell 5.1**: нет `&&`/`||`, `2>&1` на native-exe даёт ложные ошибки, UTF-16 по умолчанию
+   в `Out-File` → для файлов, которые читают другие тулы, `-Encoding utf8`.
+5. **У агента две оболочки** (bash + PowerShell) → permissions и block-хук должны покрывать ОБЕ.
+6. **vite/HMR через bind-mount не видит изменений** → `usePolling: true`.
+7. **WSL-файлы читаются с Windows** по UNC: `\\wsl.localhost\<distro>\...` (когда нужен чужой репо-эталон).
+8. Тяжёлые линтеры (gitleaks/hadolint/actionlint — Go-бинари) → в CI на Linux, не в локальный pre-commit.
+
+## 11. Порядок внедрения — сводка
+
+| Когда | Что |
+|---|---|
+| **День 0** (до первой строки кода) | §2 (git, pyproject, pre-commit, arch-lint, Makefile) + §3 CI + §4 .claude + §5 Docker |
+| **Первый кодовый срез** | e2e-арбитр ПЕРВЫМ (красный) → код до зелёного; `makemigrations --check` уже в CI |
+| **Из трения** (баг повторился) | новый гейт того же класса: тест / правило ruff / хук / строка в rules |
+| **По триггерам** | таблица §8 |
+| **Еженедельно** | cleanup-сессия агента: мёртвый код, устаревшие доки, несогласованные паттерны → PR |
+| **Никогда «на вырост»** | сервисы/линтеры/оркестрация без объекта, который они стерегут |
+
+---
+
+## 12. Карта понятий: два слоя над моделью, два материала обвязки
+
+**Слой 1 — низкоуровневый агент** (программный код): цикл «подумал → вызвал тул → прочитал →
+подумал», системный промпт, набор тулов, менеджмент контекста/сессии. Claude Code/Codex — ГОТОВЫЕ
+агенты этого слоя. Самописные — на Anthropic API / Agent SDK / pydantic-ai.
+
+**Слой 2 — обвязка поверх готового агента.** Внутри неё два РАЗНЫХ материала — не путать:
+
+| Материал | Примеры | Гарантия |
+|---|---|---|
+| **Мягкое** (текст в контексте) | CLAUDE.md, rules, skills, память | модель МОЖЕТ проигнорировать (вероятностна) |
+| **Жёсткое** (код в точках расширения) | hooks (exit 2), permissions deny, sandbox, pre-commit, CI | исполняется кодом, минуя волю модели |
+
+Главный приём инженерии обвязки: **переносить правила из мягкого в жёсткое** при каждом повторе
+нарушения. SlopCodeBench: промпт-интервенции НЕ замедляют деградацию — только механика. Мягкое
+оставляем для того, что нельзя механизировать: вкус, приоритеты, «почему».
+
+## 13. Skills: когда и как делать
+
+- **Когда НЕ делать**: постоянные правила → `rules/` (skills не срабатывают сами в 56% случаев;
+  rules с явными указателями — 100%). Skill — для **повторяемой процедуры по запросу** («выпусти
+  релиз», «заведи новую задачу бенчмарка»): чек-лист + скрипты, вызывается явно.
+- **Тело по TWI**: шаг → ключевой момент → **ПОЧЕМУ** (без «почему» агент обходит шаг при первом
+  неудобстве). Чек-листы — по месту применения, не в общем разделе. Убрать размытое
+  («periodically», «typically»).
+- **Git**: skills живут в репо → версии, ревью, история — как код («Skills are the New SDKs»).
+
+### Механика, которую надо знать (иначе строишь неверные ожидания)
+
+**Автоподхвата по ключевому слову не существует.** Видны только имя и описание; решение загрузить
+принимает агент. Поэтому «в описании же написано *загружать всегда*» ничего не гарантирует —
+нужен явный указатель в правилах. У нас он стоит в `CLAUDE.md`.
+
+**Загруженный скилл остаётся в контексте до конца сессии.** Это не разовая плата, а постоянная.
+Значит `SKILL.md` — короткая процедура, а длинные политики и справочники — в `reference/` рядом,
+подгружаются по требованию.
+
+**Бюджет списка скиллов ограничен** (порядка процента от окна). При переполнении описания
+**обрезаются**, начиная с редко вызываемых — и скилл перестаёт находиться именно потому, что им
+редко пользовались.
+
+> 📏 **У нас: 23 скилла, 7979 символов описаний.** На окне в миллион токенов это около 80% бюджета
+> листинга. **Запас почти выбран.** Новые скиллы добавляем, укорачивая старые описания, а не
+> дописывая сверху. На модели с окном поменьше мы бы уже были за границей и не знали об этом.
+
+**При сжатии контекста скиллы переносятся частично** — старые выпадают. После долгой сессии
+скилл, который «перестал влиять», надо просто перевызвать.
+
+### Структура
+
+Папка `<name>/` с `SKILL.md` во frontmatter которого `name` и `description` с конкретным
+триггером «when user asks to…». Внутри: `SKILL.md` (короткая процедура) + `reference/` (почему так устроено) + `scripts/` (инструменты) +
+данные рядом. Одна директория = самодостаточный пакет: инструкция, чем делать и на чём делать.
+
+> 📏 У нас подпапки есть у 8 скиллов из 23; полный набор «инструкция + инструменты + данные» —
+> пока только у `nextcloud-webdav`.
+
+### Что куда класть
+
+- Постоянное правило, действующее всегда → `rules/` или `CLAUDE.md` (всегда в контексте).
+- Процедура, нужная по теме → скилл.
+- Доступ к внешней системе → **свой** клиент или скрипт внутри скилла. Сторонний MCP — только если
+  своего нет и после аудита (см. §7).
+
+---
+
+### Как понять, что скилл работает
+
+«Сработал» — не значит «сработал правильно». Проверять надо две разные вещи: **срабатывание** и
+**результат**.
+
+- **Явный вызов** — работает, когда позвали по имени.
+- **Неявный** — срабатывает на естественной формулировке задачи, без имени.
+- **Негативный** — НЕ срабатывает там, где не должен.
+- **Прогон без скилла** — если результат тот же, скилл не нужен: **снести**. Модель могла дорасти.
+
+Дешёвая рабочая версия: пара реальных задач с ним и без него, в свежей сессии. Свежая — обязательно,
+иначе остатки контекста от написания скилла маскируют дыры в самой инструкции.
+
+---
+
+### Скилл — это тоже цепочка поставки
+
+Скилл можно установить, обновить и расшарить — значит его можно атаковать. Опасен **не только код**:
+инструкция на естественном языке в `reference/` для модели тоже исполняемая.
+
+Внешние данные для калибровки (не наши замеры): по публичным исследованиям 2026 года заметная доля
+опубликованных скиллов содержит дефекты безопасности, часть — активную полезную нагрузку; публичные
+сканеры обходятся довольно быстро, поэтому сканер — не гарантия, а фильтр.
+
+**Наше правило: скиллы пишем сами.** Сторонний — только после чтения всех файлов целиком и с
+фиксацией версии.
+
+> 📏 Проверено 2026-07-29: в наших 23 скиллах внешних загрузок нет (единственный `curl` — на
+> localhost, упоминания установки пакетов — документация зависимостей, не исполняемый код).
+> Стороннего происхождения один — `skill-creator`.
+
+Что проверять в своём скилле: что делают `scripts/`, куда они ходят по сети, нет ли секретов в
+файлах и аргументах, ограничены ли права, есть ли сухой прогон для разрушающих действий и **явная
+граница записи в коде**.
+
+---
+
+## 14. LLM-ревью кода: как строить и как МЕРИТЬ ревьюера
+
+Дизайн (паттерн Cloudflare, 131k ревью/мес): **специализированные ревьюеры** по доменам
+(security/perf/quality), а не один универсал · risk-tiering по размеру диффа · фильтрация
+lock/generated файлов ДО ревью · явный список **«что НЕ флагать»** (главное лекарство от шума) ·
+инкрементальный re-review с памятью прошлых находок и «won't fix» · cross-model или свежая сессия
+(нет сикофантии к своему коду). Честно: LLM-ревью слабо в архитектуре/concurrency — это остаётся
+человеку.
+
+**Ревьюер — тоже система, его меряют**: golden-set диффов с подсаженными известными багами →
+recall (сколько поймал) и false-positive rate (сколько шума). Источник кейсов — каждый реальный
+пропущенный баг становится кейсом эвала ревьюера. Ревьюер без эвала = генератор шума.
+Процессная часть (пирамида ревью, роль человека) — `ai-sdlc.md §3` этап 6.
+
+## 15. Рефакторинг, уборка, cron
+
+- SOLID/KISS напрямую линтером не проверяются — их прокси: сложность (C90≤10), размер файла
+  (500/300/800), дубли (jscpd/aislop), мёртвый код (vulture/aislop) — всё по триггерам §8.
+- **Процесс**: рефакторинг — отдельным PR от фич; маленькие шаги с зелёными тестами между;
+  критерий правильных тестов — «переписали реализацию, поведение то же → тест выжил».
+- **Первый скан слоп-линтера = лавина** (Thoughtworks): приоритизировать, не чинить всё сразу.
+- **Cron** двух видов: GitHub Actions `schedule:` — nightly-гейты (mutmut/trivy/lychee, §8);
+  планировщик Claude Code — еженедельная cleanup-сессия («найди мёртвый код/дубли/гниющие доки →
+  предложи PR»). Триггер обоих: появился объём, который есть смысл убирать.
+
+## 16. Structured output (когда нужен машинный JSON)
+
+- **Свой агент / скрипты**: tool use с `input_schema` + форсированный `tool_choice` — модель
+  обязана вернуть валидный JSON по схеме. Источник истины схемы — Pydantic (py) / Zod (ts).
+- **Петля**: validate → максимум 1 repair-попытка → ошибка + кейс в evals. Парсить регулярками
+  там, где можно schema-first, — запрещено.
+- **В Claude Code интерактивно**: просить JSON + валидировать скриптом-гейтом; субагенты умеют
+  форсированную схему.
+
+## 17. Путь в низкоуровневый агент (слой 1)
+
+Ядро любого агента — цикл ~20 строк: `system + история + tools → LLM → есть tool_calls? исполни,
+дозапиши результат в историю → повторяй, пока stop_reason != tool_use`. Надстройки добавляются
+**по боли, не заранее**: гардрейлы (workdir, чёрные списки) → loop detection (5 одинаковых вызовов
+→ «попробуй иначе») → компактизация контекста → субагенты → скиллы (name+description в промпт,
+тело по load_skill) → память. KV-cache дисциплина: стабильный байт-в-байт префикс, append-only
+история, `sort_keys=True` для тулов (см. reference/context-and-kv-cache).
+
+Лучший первый проект — **не учебный, а нужный**: минимальный клиент собственной платформы
+(эталонный агент ~50 строк с 3 тулами). Мост между слоями — Claude Agent SDK (харнес Claude Code
+как библиотека).
+
+## 18. Дисциплина в каждой задаче
+
+Переносится из `audit_project`: каждое правило ниже прослеживается до конкретного отказа,
+который там был. Правило без своего инцидента сюда не попадает.
+
+### Знание живёт в репозитории, а не в переписке
+
+Всё, что сказано в чате, умирает вместе с окном контекста. Поэтому durable-знание раскладывается
+по трём местам:
+
+| Куда | Что там | Когда читать |
+|---|---|---|
+| Очередь работ проекта | что осталось сделать и почему это важно | планирование, «что дальше» |
+| Методички проекта (`.aqk/docs/`) | как и почему устроена тема | любое касание темы |
+| Память агента | предпочтения человека и процессные уроки | автоматически |
+
+**Железное правило: прежде чем спрашивать человека — искать в репозитории.**
+
+> **Инцидент 2026-07-29.** Задал пять вопросов по дизайну интеграции Nextcloud. Четыре из пяти были
+> согласованы 2026-07-21 и лежали в репозитории готовыми ответами. Человек потратил время на то,
+> чтобы указать мне на мои же записи. Дешевле было потратить одну минуту на поиск.
+
+---
+
+### Документация врёт по умолчанию
+
+Документ пишется до кода и расходится с ним молча. Никто не замечает, пока не сверит.
+
+- **Сверять при каждом серьёзном касании темы**, а не «когда-нибудь потом».
+- Разделять **CURRENT** (проверено кодом) / **TARGET** (решение принято, не сделано) /
+  **HISTORICAL** (датированный замер). Утверждение без даты и способа проверки — не факт.
+- **Историю не переписываем задним числом.** Разошлось — добавляем раздел «фактическое состояние»
+  и помечаем расхождение по месту. Иначе теряется, что решение вообще менялось, и почему.
+
+> **Инцидент 2026-07-29.** Корпус документов по Nextcloud врал в четырёх местах: обещал иерархию
+> папок, которую платформа не строит; неверно называл момент создания папок; описывал очередь,
+> которой нет; и подавал три несделанных среза так, будто они часть готового.
+
+---
+
+### Не гадать — мерить
+
+- **Три источника:** официальная документация × наши правила и интернет × реальная система.
+  Расходятся → **СТОП** и сверка. Не выбирать один источник молча и не городить обход.
+- **Не обрезать структурный вывод.** `tail`/`head` при инвентаризации полей прячет поле и даёт
+  ложный вывод «его нет». Обрезка — только для шумных логов и прогонов тестов.
+- **Молчание документации — не разрешение решать самому, а повод поставить эксперимент.**
+- «Готово» = зелёный тест **плюс** живой прогон как пользователь **плюс** логи **плюс** метрика.
+  «Агент сказал готово» и «сходится» — не доказательства.
+
+> **Инцидент 2026-07-29.** Официальные доки Nextcloud не говорят, переживает ли идентификатор файла
+> корзину. Замер на живом инстансе показал: переживает — а наша детекция корзину от настоящей потери
+> **не отличает**. Заложенный необратимый откат принятой задачи сработал бы на штатном действии
+> пользователя, который через минуту достал бы файл обратно. Дока молчала, догадка была бы неверной.
+
+---
+
+### Границы: необратимое и чужое
+
+- **Боевые системы:** работаем только в своей песочнице, и **границу переносим в код**. Пример:
+  `sandbox()` в `nc_probe.py` падает до обращения к серверу, если путь вне разрешённого корня.
+  Память агента границу не держит — код держит.
+- **Деструктивный git запрещён.** В репозитории параллельно работает человек: не `checkout`, не
+  `reset`, не `clean`. Стейджим явные пути и проверяем состав индекса перед коммитом.
+- **Обратимое и под гейтом → делай и запиши почему. Необратимое → остановись и спроси.**
+- Секреты не читаем даже когда так удобнее — берём через окружение контейнера.
+
+---
+
+### Против срезания углов
+
+Агент срезает углы правдоподобно: «изменение маленькое», «визуально нормально», «полный прогон тут
+не нужен». Лечится не уговорами, а прямыми запретами в инструкции:
+
+- не запускал проверку — **не пиши «проверено»**;
+- есть дифф — сперва прочитай, потом резюмируй;
+- меняешь внешнюю систему — сперва сухой прогон;
+- нет данных — верни «нет данных», **не додумывай**;
+- три попытки не помогли — СТОП, к человеку.
+
+Сюда же: не сообщать об успехе того, что не сделано, и честно называть пропущенное. Отчёт, в
+котором скрыт незакрытый кусок, хуже отсутствия отчёта.
+
+---