From 210b38ec98504a2d31a79a0b2da711e4410ce19f Mon Sep 17 00:00:00 2001 From: "Claude (backend session)" Date: Sun, 9 Aug 2026 01:14:00 +0300 Subject: [PATCH] Ratify D39.121: post-review self-plan with findings gate, absorb official Anthropic practices via research 26, add compaction and test-integrity guardrails --- CLAUDE.md | 2 + docs/ORCHESTRATOR_SESSION_PROMPT.md | 2 + docs/README.md | 2 +- docs/architecture/05-decisions-log.md | 10 ++++- docs/research/26-anthropic-guidance-digest.md | 38 +++++++++++++++++++ 5 files changed, 52 insertions(+), 2 deletions(-) create mode 100644 docs/research/26-anthropic-guidance-digest.md diff --git a/CLAUDE.md b/CLAUDE.md index e0a7e14e..e247b8e8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,6 +41,8 @@ Go-бэкенд издательского художественного пер - Провайдерские ловушки: **DeepSeek — НИКОГДА не отключать thinking** (эхо-мина; гейт `echoMineViolation` это принуждает); grok-4.3 reasoning off — только ЯВНЫЙ `reasoning_effort:"none"` (дефолт low; wire-квирк в силе, но из РЕДАКТОРСКИХ ролей reasoning-off снят — no-op, D30.1); слаги моделей не менять без live-фактчека `/models`; ⚠ «слаг живой» ≠ «модель та же» — DeepSeek 31.07 сменил веса под слагом (D39.61), при аномалиях сверять поведение и вендор-лог обновлений. **Пробы/запросы падают или ведут себя странно (флейки, 404 живой модели, новый finish_reason, игнор параметров) → идём в официальную доку вендора (deprecations/changelog/status) и гуглим, НЕ гадаем** — интерпретацию аномалии без вендор-сверки в доки/промты не абсорбировать (решение владельца 10.07; правило двух направлений — `00-provider-quirks.md` шапка). - Дисциплина: не верь заголовкам — грунтуй выводы `file:line`/цитатой; спорное верифицируй адверсариально (author≠reviewer); эмпирика на PD-классике из претрейна считается предварительной до вебновелл-среза. - **Общность движка (владелец 24.07):** Go-логика НЕ ветвится по паре/книге; пара-данные → `internal/lang`+`configs/langpacks/`, книго-каноны → сид/brief (данные); книжный термин в общем пар-слое = утечка. Тест-данные пары легитимны. Норматив (только больные места): `docs/architecture/12-go-style-notes.md`. Ревью-вопрос по умолчанию: «заработает ли на паре, которой в репо ещё НЕТ, без правки Go?» +- **При компакции/сжатии контекста ВСЕГДА сохранять:** список изменённых файлов · незакрытые находки ревью и их диспозиции · обязательства и открытые вопросы сессии · команды тестов (D39.121). +- **Тесты и гейты не подгонять под зелень:** править или удалять тест/голден/гейт, чтобы он прошёл, — НЕДОПУСТИМО; несогласие с тестом — вопрос оркестратору пингом, не правка (D39.121). - **Мандат самопроверки в промтах сессий (обязателен, решение владельца 12.07):** промты полигон-сессий — и вообще любых пишущих код / запросы к моделям — ДОЛЖНЫ явно требовать ревью ИСПОЛНЕНИЕМ: своего кода + сформированных запросов к моделям + полученных результатов. Полигон регулярно ошибается/багует, и это искажает эксперименты (D37: заявленные «0 ошибок» = 36 ошибок+биллинг, «13 катастроф» = ~5–6 при оверфлаге судьи; exp13 +10% бюджета). Бэкенд-промты — явный бэкенд-ревью после кода (обычно отрабатывает по опыту, но требовать явно). Пост-хок адверсариальная верификация оркестратора при лендинге — второй рубеж, НЕ замена самопроверки. - **Git-координация мультисессий:** - **Коммитит только оркестратор.** Сессии зон — бэкенд, полигон, фронт, платформа — не коммитят: своё дерево готовят и передают на лендинг (исключение прежнее: пре-рег фризы полигона). Чужую зону не трогает НИКТО. diff --git a/docs/ORCHESTRATOR_SESSION_PROMPT.md b/docs/ORCHESTRATOR_SESSION_PROMPT.md index c06bb203..136a7f21 100644 --- a/docs/ORCHESTRATOR_SESSION_PROMPT.md +++ b/docs/ORCHESTRATOR_SESSION_PROMPT.md @@ -48,6 +48,8 @@ - **Свип зонных решений владельца (урок D39.99 п.4):** при каждом лендинге зоны вычитать из зонного журнала НОВЫЕ «решения владельца» и вынести на confirm списком; решение, живущее только в зонном доке при противоречащем каноне, — дефект синхронизации, чинится ратификацией или опровержением, не молчанием. - **Анти-паттерны приёмки:** приёмка проверяет НАПРАВЛЕНИЕ и решения пака, не только клеймы отчёта. Шесть ловушек: след отчёта (проверяешь лишь названные автором места) · связность вместо истинности (форма отчёта убеждает сама) · соглашательство с чёткой позицией (распространенная ошибка ллм моделей склонных соглашаться с человеком) · рационализация задним числом · слепой участок общих моделей обученных на одинх и тех же данных (выводы одной модели усиливают уверенность в правильности другой) · экономия усилия на неудобном. Механика-минимум: ≥1 верификатор выносит мнение по промту+диффу ДО чтения отчёта · ≥1 ищет дефекты ВНЕ карты отчёта · экспериментальный клейм без ре-рана (хотя бы редуцированного) в D-ноте помечается «со слов сессии», не «исполнением» · «решение владельца», известное только со слов сессии, НЕ ратифицируется — список confirm/deny владельцу ДО лендинга, если решение несущее · к утверждениям самой приёмки та же дисциплина «заявление=команда» (догадку фактом не подавать) · оценочные эпитеты в ноты не писать. - **Кросс-модельные контуры ревью (владелец 08.08, D39.120; это НАПРАВЛЕНИЕ, не буква — разумное отступление с аргументом легитимно и приветствуется, соглашательство с нормой ради нормы = антипаттерн):** (1) в приёмочной панели ≥1 опровергатель ДРУГОЙ моделью семейства — на ТЕКСТОВЫХ/ОЦЕНОЧНЫХ линзах (чтение отчёта, аудит промта, дизайн-доводы; глушит self-preference и контекстное закрепление); механические линзы (пере-раны, посадки) от смены модели не выигрывают — там правит исполнение. (2) Тяжёлые ратификации (класс D39.106: новый механизм/шов/контракт) и периодический аудит СВОИХ записей — параллельная сессия-ревьюер другой моделью: промт пишет оркестратор, стартует владелец, онбординг у неё СВОЙ (по докам, не по пересказу — это снимает фрейминг оркестратора, чего воркфлоу-агент не может по построению), мнение приходит владельцу ДО ратификации (прецеденты: кросс-чек D39.106, аудит записей D39.112). (3) Семейный слепой участок кросс-моделью ВНУТРИ Anthropic ослабляется, но не снимается — оценочные вердикты калибруются внешним семейством (Sol/grok, как ратифицировано), а первичными остаются пере-ран и исполнение. +- **Записка-план и финдингс-гейт (владелец 09.08, D39.121; фактура — research/26; направление, не буква).** После тяжёлого ревью с верифицированными находками сессия пишет СЕБЕ структурированную записку-план (ID находки → статус → улика; СТРУКТУРИРОВАННЫЙ формат, не проза — Anthropic: модель переписывает Markdown легче, чем JSON) и движется по ней, а не по памяти; сдача = все ID имеют диспозицию, сверка скриптом (тем же классом гейта, что числа). «Заявление=команда» действует на клеймы ревью О СЕБЕ («находки отработаны» = клейм с бременем доказательства). Комплектность против ЗАКАЗА (каждый пункт промта → исполнено/отказ-с-причиной) — механически, для паков среднего+ веса: детекция асимметрично слепа к пропускам. Числовой гейт сторожит ПРИСУТСТВИЕ числа, не истинность предложения — пороговые/сравнительные утверждения приёмка читает отдельным списком. +- **Стандартный блок будущих кодовых хендоффов (D39.121, из официальных сниппетов Anthropic):** (1) ground-progress-claims: «перед отчётом о прогрессе сверь каждый клейм с результатом инструмента ЭТОЙ сессии; о непроверенном скажи явно»; (2) «перед завершением проверь последний абзац: если это план/обещание — сделай работу сейчас»; (3) «править или удалять тесты, чтобы они прошли, — недопустимо»; (4) интервальная самоверификация субагентом в длинных сессиях, против ЯВНЫХ критериев хендоффа (не «проверь всё» — over-verification жжёт бюджет). Панелям оркестратора: obstacle reporting («что НЕ удалось/не сделано») — ОБЯЗАТЕЛЬНОЕ поле схемы; ревьюеру — рамки «флагай только бьющее по корректности/заявленным требованиям, остальное — опционально» (анти-оверфлаг). - **Предметные оси самопроверки — по характеру работы (владелец 08.08, D39.120):** каждый кодовый промт несёт 1–3 ПРЕДМЕТНЫЕ оси ревью своего пака (бэкенд — общность §0.1 «пара, которой нет в репо»; платформа — сверка с индустриальным первоисточником, stdlib/устоявшаяся библиотека прежде велосипеда; фронт — контракт/доступность; подбирает оркестратор под пак). Это направление, не чек-лист: сессия вправе добавить свою ось или аргументированно снять предложенную. Дисциплина же РЕВЬЮЕРА (шесть антипаттернов приёмки) от характера работы не зависит и в сессионные промты не грузится. - **Пре-рег дисциплина полигона:** фриз-коммиты ДО платных вызовов — ЕДИНСТВЕННЫЕ коммиты сессии (стадийный пак — по фризу на фазу, фриз включает код оснастки фазы; форма эксп-22); amend фриза запрещён, девиации — НОВЫМ коммитом и явно в отчёте (D39.108 п.1); изменения смысла после фриза = новый experiment-ID; стоп-гейты по бюджету легитимны; «если не влезает — стоп и пинг, не резать молча». *(испр. 08.08 №15: было «единственный коммит сессии» — синк с ратифицированной практикой D39.108/эксп-22.)* - **Лендинг:** микро-дефекты доков чинишь сам с пометкой «испр. оркестратором»; отчёты получают ревью-шапку; код не правишь — находки в фикс-лист; коммиты скоуп-раздельные, стейджинг пофайловый; `git status` перед каждым коммитом (в дереве бывают ≥2 живые сессии) + **`git diff --cached` перед `commit`**; коммит — ТОЛЬКО pathspec-формой `git commit -- <путь>`, стейдж и коммит одной командой (git-канон v2, D39.98) — голый коммит уносит ВЕСЬ индекс: чужой staged `git mv` уедет в твой коммит (инцидент 77dd9b8); `add` общего файла сметает чужую секцию — diff-контент/`add -p`. **Лендинг, двигающий файлы или состав активных промтов, обновляет `docs/README.md` тем же коммитом** (норма D39.80; урок 02.08: README объявлял заленденный пак «можно запускать» с мёртвой ссылкой — поймал не процесс, а новая сессия). Статус/голову README не несёт вовсе — единственный носитель состояния = PROGRESS CURRENT-STATE. **Перед коммитом ратификации — механический чек головы, и он теперь ИНСТРУМЕНТ, а не памятка:** `python3 docs/scripts/counts.py --check` печатает голову по трём носителям (последняя нота D-лога · шапка-диапазон · CURRENT-STATE) и все производные числа доков, ненулевой код = расхождение; тот же скрипт зовёт зонный хук `docs/scripts/githooks/pre-commit` при каждом коммите, задевающем D-лог или PROGRESS (ПРЕДУПРЕЖДАЕТ, не блокирует — жёсткий гейт только словом владельца). Заведено потому, что голова отставала ТРИЖДЫ у трёх разных оркестраторов (D39.81 · D39.83 · D39.112 п.5б): одна и та же ошибка у независимых сессий на одном поле — свойство поля. **Производные числа (счёт очереди, зоны, вес открытых строк реестра) руками больше не переписывать** — носитель несёт команду, литерал сверяется этой же командой в том же касании. diff --git a/docs/README.md b/docs/README.md index 2cb2df6e..cf7ede84 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ - [09-target-architecture.md](architecture/09-target-architecture.md) — целевая 7-слойная архитектура (статус стройки — шапка-таблица; §3 — карта находок H/L) · [10-prompt-architecture.md](architecture/10-prompt-architecture.md) — промпт-слой · [12-go-style-notes.md](architecture/12-go-style-notes.md) — норматив общности §0 · [13-tech-debt-anchors.md](architecture/13-tech-debt-anchors.md) — якоря техдолга (справочник к бэклогу, НЕ трекер) · [14-api-contract/](architecture/14-api-contract/) — **контракт API v0 фронт↔платформа (D39.99)**: нормативная спека OpenAPI 3.1 (типы фронта генерятся из неё) + компаньон-README (провенанс ✓/◆/○, К-вопросы; зонная копия `frontend/docs/api-contract/` — байт-зеркало, сверять при лендинге). - Исторические, читать через ⚠-баннеры: [01-decisions.md](architecture/01-decisions.md) (Р1–Р10) · [02-mvp-plan.md](architecture/02-mvp-plan.md) · [03-implementation-notes.md](architecture/03-implementation-notes.md) · [04-unhappy-paths.md](architecture/04-unhappy-paths.md) · [06-memory-risk-registry.md](architecture/06-memory-risk-registry.md). - `experiments/` — эмпирика полигона: [00-provider-quirks.md](experiments/00-provider-quirks.md) — **читать перед любым вызовом провайдера**; [08-cost-model-v2.md](experiments/08-cost-model-v2.md) — денежная модель; [09-pilot-protocol.md](experiments/09-pilot-protocol.md) — пилот Ф2.5; остальные 01–20 — отчёты закрытых экспериментов (судьба — в баннерах/D-логе; 18–20 — с ревью-шапками приёмки D39.108, шапка первична). -- `research/` — фактура ресёрчей 01–25; у принятых — ревью-шапки, часть тел под ⚠ superseded: **читай баннер прежде содержимого**. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа (транспорт superseded D39.106) · 25 холодное ревью шва — форма D39.106, отвергнутые альтернативы, требования к эмиттеру (читать перед любым кодом стыка) · 24 арбитраж банка (ПРИНЯТ D39.102: консилиум закрыт классом, вход фикс-пака банка — §G). +- `research/` — фактура ресёрчей 01–26; у принятых — ревью-шапки, часть тел под ⚠ superseded: **читай баннер прежде содержимого**. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа (транспорт superseded D39.106) · 25 холодное ревью шва — форма D39.106, отвергнутые альтернативы, требования к эмиттеру (читать перед любым кодом стыка) · 24 арбитраж банка (ПРИНЯТ D39.102: консилиум закрыт классом, вход фикс-пака банка — §G) · 26 официальные практики Anthropic (D39.121: записка-план, сниппеты хендоффов, карта «уже делаем/перенять»). - [PROGRESS.md](PROGRESS.md) — журнал: CURRENT-STATE + **ЕДИНЫЙ БЭКЛОГ** (единственный трекер) + живой хвост хроники. НЕ источник решений. - `scripts/counts.py` — **производные числа доков считаются им, а не руками** (голова по трём носителям · счёт очереди и зон · вес открытых строк регистра платформы); `--check` даёт ненулевой код на расхождении. Его же зовёт зонный хук `scripts/githooks/pre-commit` при коммите, задевающем D-лог или PROGRESS — предупреждает, не блокирует. Заведено по D39.112 п.5б: голова отставала трижды у трёх разных оркестраторов. - Активные хендофф-промты сессий (состав обновляется при каждом лендинге — норма D39.80): [ORCHESTRATOR_SESSION_PROMPT.md](ORCHESTRATOR_SESSION_PROMPT.md) (роль/нормы; состояния не дублирует) · [POLYGON_PACKAGE4_SESSION_PROMPT.md](POLYGON_PACKAGE4_SESSION_PROMPT.md) (полигон, отложен) · **платформа: ОТРАБОТАН ЦЕЛИКОМ** — четыре сессии (P0 D39.107 · P1+P2 D39.109 · фикс-пак P3 D39.114); текст в архиве, [`archive/prompts/PLATFORM_P0_SESSION_PROMPT_2026-08-04.md`](archive/prompts/PLATFORM_P0_SESSION_PROMPT_2026-08-04.md), копия с баннером ещё лежит в зоне. **Платформа: [`../platform/docs/PLATFORM_RUNNER_SESSION_PROMPT.md`](../platform/docs/PLATFORM_RUNNER_SESSION_PROMPT.md)** (раннер: юниты/River/реконсилятор/тейлер + первые ручки /v0; D39.119, запуск = владелец) · **фронт: S3 ОТРАБОТАН и ПРИНЯТ D39.115** (контракт 0.2.0 в каноне, копии байт-равны, слой данных построен); текст в архиве, [`archive/prompts/FRONTEND_S3_SESSION_PROMPT_2026-08-04.md`](archive/prompts/FRONTEND_S3_SESSION_PROMPT_2026-08-04.md). **S4 ГЕЙЧЕН словом владельца о качестве оболочки (D39.119 п.4):** сначала список претензий → «S3.5 фикс-пак оболочки» (VS Code-вкладки + Ф-19) → S4. Зонные журналы фронта/платформы — `frontend-PROGRESS.md` / `platform-PROGRESS.md` в их зонах (решение владельца 04.08: прогресс зон только там). **бэкенд: фикс-пак банка ОТРАБОТАН и ПРИНЯТ D39.118** (код `bccf2d8`; отчёт с ревью-шапкой — [`archive/reports/BANK_CLUSTER_FIXPACK_2026-08-08.md`](archive/reports/BANK_CLUSTER_FIXPACK_2026-08-08.md); текст промта в архиве — [`archive/prompts/BACKEND_BANK_CLUSTER_FIXPACK_SESSION_PROMPT_2026-08-04.md`](archive/prompts/BACKEND_BANK_CLUSTER_FIXPACK_SESSION_PROMPT_2026-08-04.md)); **Бэкенд: [BACKEND_CONTRACT_BLOCKERS_SESSION_PROMPT.md](BACKEND_CONTRACT_BLOCKERS_SESSION_PROMPT.md)** (движковые блокеры контракта 99/100/101/125/145; D39.119, запуск = владелец; эмиттер 103 — следующим промтом) · **Полигон: [POLYGON_TENANT_PANEL_SESSION_PROMPT.md](POLYGON_TENANT_PANEL_SESSION_PROMPT.md)** (эксп-22 «панель жильцов»; санкция D39.117, ЗАПУЩЕН 08.08 — сессия живая) · **эксп-21 ОТРАБОТАН и ПРИНЯТ** (D39.117; отчёт `experiments/21-role-topology.md`), текст промта в архиве — [`archive/prompts/POLYGON_ROLE_TOPOLOGY_SESSION_PROMPT_2026-08-06.md`](archive/prompts/POLYGON_ROLE_TOPOLOGY_SESSION_PROMPT_2026-08-06.md). Очередь и состояние — только CURRENT-STATE. diff --git a/docs/architecture/05-decisions-log.md b/docs/architecture/05-decisions-log.md index 15b82375..ea0d9dac 100644 --- a/docs/architecture/05-decisions-log.md +++ b/docs/architecture/05-decisions-log.md @@ -1,4 +1,4 @@ -# Журнал решений оркестратора — контракт D1–D39.120 (развязки 04.07 · пакеты 09–10.07 · приёмка/качество-первым/пивот/эмпирика 11–12.07 · арх-ресет+стройка пере-прогонного стека 13–19.07) +# Журнал решений оркестратора — контракт D1–D39.121 (развязки 04.07 · пакеты 09–10.07 · приёмка/качество-первым/пивот/эмпирика 11–12.07 · арх-ресет+стройка пере-прогонного стека 13–19.07) > **⟶ КАРТА АКТУАЛЬНОСТИ (ревизия D31, продлена до D38.2 [12.07]; исторические записи ниже НЕ переписываются — дисциплина D23.3).** Читая контракт целиком, держи под рукой, что чем перекрыто: > ⚠ **Навигация (актуализация 07.08, эра D39.1xx):** append-only-дисциплина (D23.3) означает, что @@ -1702,3 +1702,11 @@ API-529-долг закрыт: 8-осевой refute-by-default воркфлоу **1. Ратифицировано словом владельца 08.08 (пересказ; финал — «да, нормально» с оговоркой свободы):** (а) в приёмочных панелях ≥1 опровергатель ДРУГОЙ моделью семейства на текстовых/оценочных линзах (глушит контекстное закрепление и self-preference; механические линзы от смены модели не выигрывают); (б) тяжёлые ратификации класса D39.106 и периодический аудит записей оркестратора — параллельная сессия-ревьюер другой моделью с СОБСТВЕННЫМ онбордингом (снимает фрейминг оркестратора; промт — оркестратор, старт — владелец, мнение — владельцу ДО ратификации; прецеденты D39.106/D39.112); (в) семейный слепой участок кросс-моделью внутри Anthropic не снимается — оценочные вердикты по-прежнему калибруются внешним семейством, первичны пере-ран и исполнение; (г) каждый кодовый промт несёт 1–3 ПРЕДМЕТНЫЕ оси самопроверки по характеру работы (бэкенд — общность §0.1; платформа — индустриальный первоисточник/stdlib прежде велосипеда; фронт — контракт/доступность), дисциплина ревьюера (шесть антипаттернов) в сессионные промты не грузится. **2. Оговорка владельца — часть нормы:** всё выше — НАПРАВЛЕНИЕ, не буква; сессиям и оркестратору оставлена свобода суждения, разумное отступление с аргументом легитимно и приветствуется; упарывание в букву стандарта и соглашательство с нормой ради нормы — сами по себе антипаттерн. Носитель — промт оркестратора (два новых буллета «Методологии»). + +## D39.121 — ЗАПИСКА-ПЛАН ПОСЛЕ ТЯЖЁЛОГО РЕВЬЮ + ОФИЦИАЛЬНЫЕ ПРАКТИКИ ANTHROPIC абсорбированы нормой-направлением (владелец 09.08). ✅ + +**1. Слово владельца 09.08 (пересказ):** сессии должны решать свои проблемы максимально самостоятельно — после сложного ревью с верифицированными находками сессия составляет МИНИ-ПРОМТ САМОЙ СЕБЕ (записанный план) и движется по нему, а не по памяти; плюс заказ: разобрать официальные гайды Anthropic и перетянуть применимое. Исполнено веб-ресёрчем (3 агента, 86 рекомендаций с URL-грунтовкой) — выжимка и карта применимости: **`docs/research/26-anthropic-guidance-digest.md`**. + +**2. Ратифицировано (направление, не буква — оговорка D39.120 п.2 действует):** (а) **записка-план**: после тяжёлого ревью — структурированный файл «ID находки → статус → улика» (не проза: инцидент диспозиций 08.08 случился в прозе, и Anthropic это же говорит о Markdown против JSON), движение по записке, сдача гейтится сверкой «все ID имеют диспозицию»; (б) «заявление=команда» распространяется на клеймы ревью о себе; (в) комплектность против заказа — механически (пункт промта → исполнено/отказ), для паков среднего+ веса; (г) числовой гейт сторожит присутствие, не истинность — сравнительные/пороговые утверждения приёмка читает списком; (д) стандартный блок будущих кодовых хендоффов из официальных сниппетов (ground-progress-claims · «проверь последний абзац» · запрет подгонки тестов · интервальная самоверификация против явных критериев); (е) панелям — obstacle reporting обязательным полем схемы и анти-оверфлаг-рамки ревьюеру. Носители: промт оркестратора (два буллета) + CLAUDE.md (компакция-инструкция и запрет подгонки тестов — механизм-уровень, читается каждой сессией). + +**3. Конвергенция зафиксирована** (research/26 §2): половина канона проекта совпала с официальными рекомендациями независимо («заявление=команда» = show-evidence · author≠reviewer = fresh-context verifiers · execute-first приёмка = grade-final-state · онбординг-диета = lean CLAUDE.md · «один носитель на факт» = JIT-указатели). Не перенимается: promptfoo · lock-файлы (нужны только при двух сессиях в одной зоне) · метапромпт как прод-механизм (§5 research/26). Вопрос владельца о «сайте prompts md» закрыт указателем — research/26 §4. diff --git a/docs/research/26-anthropic-guidance-digest.md b/docs/research/26-anthropic-guidance-digest.md new file mode 100644 index 00000000..9515019c --- /dev/null +++ b/docs/research/26-anthropic-guidance-digest.md @@ -0,0 +1,38 @@ +# 26. Официальные рекомендации Anthropic — выжимка и карта применимости к проекту + +**Оркестратор №15, 09.08.2026.** Веб-ресёрч по слову владельца: три агента по официальным источникам (platform.claude.com/docs · anthropic.com/engineering · Academy/Skilljar · github.com/anthropics/*), 86 рекомендаций с URL-грунтовкой; несущее внесено сюда, каждая строка несёт первоисточник. **Статус: принят D39.121** — нормы живут в промте оркестратора и CLAUDE.md, этот файл — фактура и карта применимости. + +## §1. Что прямо отвечает на наш инцидент «объявила сделанным несделанное» + +1. **Ground progress claims** (модельная страница Fable 5): сниппет «Before reporting progress, audit each claim against a tool result from this session. Only report work you can point to evidence for; if something is not yet verified, say so explicitly» — по замерам Anthropic «nearly eliminated fabricated status reports». → Стандартным блоком в хендофф-промты рабочих сессий. [platform.claude.com/docs/.../prompting-claude-fable-5] +2. **«Проверь последний абзац перед завершением»** — если он план/обещание, сделай работу сейчас. → Туда же. [та же страница] +3. **Состояние — структурированно, нарратив — прозой**: task/test-статусы в JSON («model is less likely to inappropriately change or overwrite JSON files compared to Markdown»); «only mark passing after careful testing». Наш инцидент случился ровно в прозе. → Реестр находок/диспозиций сессии = структурированный файл со статусом на ID; статус меняется только с уликой. [claude-4-best-practices; engineering/effective-harnesses-for-long-running-agents] +4. **Лестница гейтов завершения**: чек в промте → evaluator после каждого хода → детерминированный Stop-hook (не даёт завершиться, пока чек-скрипт не прошёл) → свежий субагент. «Правила каждый-раз-без-исключений — в хуки, не в текст». → Скрипт-чек «у каждой находки есть диспозиция» как гейт сдачи тяжёлого пака. [code.claude.com/docs/en/best-practices; курс Claude Code in Action] +5. **Obstacle reporting обязательным полем** контракта субагента («что НЕ удалось / не сделано» — required, не свободный текст). → В схемы всех панелей оркестратора. [курс Introduction to Subagents] +6. **Компакция**: инструкцией в CLAUDE.md сохранять при компакции список изменённых файлов, незакрытые находки и обязательства — авто-компакция = правдоподобный механизм потери диспозиций. [code.claude.com/docs/en/best-practices] +7. **Стартовый блок каждой следующей сессии**: «прочитай журнал + git log + прогони базовый чек ДО новой работы». [effective-harnesses] + +## §2. Что мы уже делаем — независимая конвергенция (валидация, действий не требует) + +«Заявление=команда» = «show evidence rather than asserting success» · author≠reviewer свежим контекстом = «fresh-context verifiers outperform self-critique» · приёмка execute-first = «grade the final state, not the path; отчёт = транскрипт, ему не верят» · пропорциональность = «simplest solution first, agents only when needed» · эхо-протокол = «golden rule: покажи промт коллеге без контекста» · онбординг-блок п.1а = «давать мотивацию инструкций» · онбординг-диета = «lean CLAUDE.md: for each line — would removing this cause mistakes?» · «один носитель на факт» = JIT-retrieval/указатели вместо копий · лестница грейдеров ($0-гейты → судья → владелец) = code→model→human · наши хендоффы = «objective + output format + tools + boundaries» из чек-листа делегирования · counts.py/хуки = «advisory text vs deterministic hooks». + +## §3. Шорт-лист к перениманию (сверх §1; всё дёшево) + +1. **Рамки ревьюеру против оверфлага**: «flag only gaps that affect correctness or the stated requirements, treat the rest as optional» — в панельные промты (наш D37-урок оверфлага судьи, теперь формулой). [code.claude.com best-practices] +2. **Интервальная верификация в длинных сессиях**: субагент-чек по интервалам, не только на финале. [prompting-claude-fable-5] +3. **Структура промпта судьи**: рубрика отдельно · рассуждение принудительно ДО вердикта · вердикт в выделенном машинно-извлекаемом теге — чек-лист аудита Ф2-судьи полигона. [cookbooks/building_evals] +4. **Порядок элементов ролевых промптов движка**: длинные данные (банк/сид/глоссарий) — ДО ссылающихся инструкций, задание и формат — в конец; «сначала процитируй релевантное» для длинных документов. → Аудит 10-prompt-architecture при следующем касании. [prompt-eng-interactive-tutorial гл.9; long-context tips] +5. **Запрет порчи тестов дословно**: «It is unacceptable to remove or edit tests…» — одна строка в кодовые хендоффы (сейчас запрет неявный). [effective-harnesses] +6. **«После двух неудачных поправок — не лечить, а перезапускать»** со свежим промтом, вобравшим урок; свежее окно часто лучше компакции. [best-practices; claude-4-best-practices] +7. **Evaluator-optimizer детали**: ревьюеру явный запрет «решать за автора»; трёхуровневый вердикт (PASS/NEEDS_IMPROVEMENT/FAIL) со стоп-условием; в ретрай передавать предыдущую попытку+фидбек. [cookbooks/patterns/evaluator_optimizer] +8. **Диагностика по транскриптам**: скармливать транскрипты прогонов отдельной сессии для починки промтов/харнесса (усиление author≠reviewer). [writing-tools-for-agents] +9. **Ре-аудит промтов под новые модели** (старые прескриптивные инструкции деградируют качество новых моделей); prefill assistant-хода на новейших Claude больше не поддерживается — для наших СЕССИОННЫХ промтов, движка не касается (пайплайн не на Claude). [claude-4-best-practices] +10. **Формулировки из опубликованных системных промтов claude.ai** как стилистический эталон verify-before-claim: «драфт — это НЕ выполнение действия». [platform.claude.com/docs/en/release-notes/system-prompts] + +## §4. Ответ на вопрос владельца про «сайт promts md» + +Отдельной живой Prompt Library у Anthropic больше НЕТ — её URL редиректят на «Prompting best practices» (проверено 09.08.2026). Живые официальные «.md-источники»: **github.com/anthropics/skills** (формат SKILL.md: YAML-шапка «когда применять» + markdown-тело — готовый образец для наших ролевых/хендофф-промтов) · вся дока платформы доступна как .md через `platform.claude.com/docs/llms.txt` (553 страницы — удобно сессиям для машинного чтения) · **github.com/anthropics/claude-cookbooks** (бывший anthropic-cookbook; паттерны агентов, evals, метапромпт) · опубликованные системные промты claude.ai. + +## §5. Что НЕ перенимать + +promptfoo-миграция (наш полигон глубже этой лестницы; Go-стек, свои судьи) · orchestrator-workers как код (у нас он реализован процессом оркестратор-сессия→хендоффы) · метапромпт как прод-механизм (только генератор черновиков пар-данных, строго через полигон-eval) · lock-файлы задач (нужны только при двух сессиях в ОДНОЙ зоне — у нас зонная развязка).