191 lines
22 KiB
Markdown
191 lines
22 KiB
Markdown
# Промт: сессия КОНТРАКТ-РЕВЬЮ — API v0 фронт↔платформа на адекватность и индустриальные нормы (строка 179)
|
||
|
||
> Выдан оркестратором №17 15.08.2026 по заказу владельца (D39.136 п.5; форма «отдельная сессия»
|
||
> — слово владельца 15.08, эррата 15.08-в). Запуск — по слову владельца. Тяжёлый класс: полный
|
||
> аппарат — эхо-протокол, судейство буллетов, кросс-модельные опровергатели.
|
||
|
||
## 0. Какую проблему решаем и что даст твой результат
|
||
|
||
TextMachine — сервис издательского перевода книг: Go-движок `tmctl` (процесс-на-прогон, SQLite
|
||
на книгу) · SaaS-платформа `platform/` (пользователи/деньги/очередь, зовёт движок процессами,
|
||
проецирует его артефакты в HTTP) · веб-фронт `frontend/` (React, дом — мир моков MSW). Между
|
||
фронтом и платформой — ратифицированный контракт **OpenAPI 0.2.3**: канон
|
||
`docs/architecture/14-api-contract/openapi.yaml` + компаньон-README рядом (провенанс, К-вопросы).
|
||
|
||
Контракт рос ТОЧЕЧНЫМИ правками (0.2.0→0.2.3), каждую сверяли «спека ↔ код», но целиком «а
|
||
хороший ли это API» не смотрел никто. Владелец заказал жёсткое ревью: без костылей и хаков, по
|
||
индустриальным нормам, и — ключевое — **БЕЗ ИНЕРЦИИ от уже принятого**: «ратифицировано ≠
|
||
правильно». Живой пример, почему это не паранойя: правило PD-172 ратифицировано в форме «сервер
|
||
читает multipart-форму до части `file`, необязательное поле после файла МОЛЧА теряется при
|
||
успешном 201» — потому что так делает код платформы. Тихая потеря данных на успешном ответе —
|
||
кандидат в протёкшую реализацию, и таких мест может быть больше.
|
||
|
||
Твой результат: **доклад с СУЖДЁННЫМИ буллетами** — каждый с вердиктом, миграционной ценой и
|
||
рекомендацией — из которого владелец и оркестратор ратифицируют батч правок **0.3.0**. Сам ты
|
||
НИЧЕГО не правишь и не заводишь: ни спеку, ни код, ни бэклог, ни канон — только отчёт. Момент
|
||
идеальный: до беты, по одному построенному потребителю с каждой стороны — дешевле не будет.
|
||
|
||
## 1. Онбординг (порядок чтения; ⚠ вся документация и код написаны нейросетями — могут ошибаться)
|
||
|
||
1. `CLAUDE.md` (корень) — гардрейлы; жёсткие для тебя: `.env` НЕ читать · PUML не рендерить ·
|
||
чужие незакоммиченные файлы (сейчас в дереве живёт полигон: `eval/`, `docs/POLYGON_*`,
|
||
`docs/experiments/23-*`) не трогать · git-коммитов НЕ делать вовсе.
|
||
2. Канон: `docs/architecture/14-api-contract/openapi.yaml` ЦЕЛИКОМ + компаньон-README рядом
|
||
(К-вопросы, провенанс ✓/◆/○, §2.15 потолок).
|
||
3. Код — read-only, все три зоны: `platform/internal/` (httpapi, books, runs, ingest — что сервер
|
||
ДЕЛАЕТ на самом деле) · `frontend/src/api/` + `src/mock/` + использование в `src/showcase/`
|
||
(что клиент реально зовёт, чем лечится сам) · движок: `backend/cmd/tmctl/` +
|
||
`backend/internal/pipeline/{manifest,bankexport,status,export}.go` + эмиттер `events.jsonl`
|
||
(правда данных, которые контракт проецирует).
|
||
4. Планы (контракт обязан их пережить): `docs/product-requirements.md` (ПТ-реестр) ·
|
||
`frontend/docs/FRONTEND_SESSION_PROMPT.md` §3 (сценарии S5–S7: подпись банка, читалка,
|
||
экспорт/настройки/лимиты) · `docs/research/16` (ридер-IDE Ф3) · `docs/research/27` (структура
|
||
глав — двинет контракт: правка названий, типы глава/фрагмент) ·
|
||
`docs/architecture/15-money-path.md` · `platform/BACKLOG.md` (П-строки читающей поверхности) ·
|
||
строки единого бэклога 49 (annot-v1) · 94 · 160–162 · 169 · 178 (`docs/PROGRESS.md`).
|
||
5. Голова D-лога по контракту — только для контекста ратификаций: D39.99 (v0) · D39.115/123/127/
|
||
129/130/135 (минорные бампы). Помни мандат: эти решения МОЖНО опрокидывать — аргументом.
|
||
|
||
**Эхо-протокол:** первый деливерабл — ≤10 строк «что я понял: скоуп / инварианты / не-делать»
|
||
ДО работы. Расхождение чинится на минуте пять, не на приёмке.
|
||
|
||
## 2. Метод (ратифицировано направлением — отступление с аргументом в отчёте приветствуется)
|
||
|
||
Субагенты, панели и воркфлоу-оркестрация для тебя **РАЗРЕШЕНЫ ЯВНО** — дефолт-запреты харнесса
|
||
на это ревью не распространяются; изоляция агентов обязательна (читающие мандаты, state-changing
|
||
git запрещён перечислением: reset/checkout/restore/clean/stash/add/commit/rebase/push).
|
||
|
||
1. **Инвентарь фактов** чтением кода трёх зон и планов — каждый факт с `file:line`. Особо:
|
||
расхождения «сервер умеет — контракт молчит» и «контракт обещает — сервер не делает»
|
||
(известные: `BookIntake.title` платформа не читает, `Book.reject_reason` не проецирует —
|
||
это ратифицированный форвард с носителем в P7, НЕ находка; ищи НЕизвестные).
|
||
2. **Greenfield-контраст (главный механизм анти-инерции):** агент(ы), которые НАШУ СПЕКУ НЕ
|
||
ВИДЕЛИ, проектируют форму API с нуля от продуктовых требований (собери им бриф из §1 п.4 БЕЗ
|
||
ссылок на спеку). Потом дифф с нашей: совпадение — подтверждение, расхождение — вопрос на суд,
|
||
не приговор.
|
||
3. **Линза стандартов:** постатейная сверка с первоисточниками — RFC 9110 (семантика HTTP),
|
||
RFC 9457 (problem details), практики SSE, OpenAPI-конвенции, публичные стайлгайды уровня
|
||
Stripe/GitHub/Google/Microsoft. Интернет-доступ легитимен для чтения стандартов; выводы — с
|
||
цитатой источника.
|
||
4. **Аудит квирков:** каждое место спеки, рождённое «уточнением по коду», судится вопросом:
|
||
«это осмысленный контракт или протёкшая деталь реализации — и что дешевле чинить: спеку или
|
||
код?» (обе зоны построены — цена реальна с обеих сторон).
|
||
5. **Судейство буллетов ДО отчёта:** каждый кандидат-буллет проходит адверсариальную верификацию
|
||
— опровергатель с установкой опровергать, **кросс-модельно** (опровергатели текстовых/
|
||
оценочных линз — ДРУГИМ семейством модели, чем автор буллета); вердикт CONFIRMED / PLAUSIBLE /
|
||
REJECTED. Выживший буллет несёт: severity · чью боль лечит (фронт/платформа/движок/продукт/
|
||
индустрия) · **миграционную цену** (что и у кого переделывается) · рекомендацию «менять спеку /
|
||
менять код / оставить как есть с записанным обоснованием». REJECTED-буллеты — отдельной
|
||
секцией с причинами (отвержение лишнего — тоже результат).
|
||
|
||
## 2а. Наши антипаттерны и оплаченные уроки — дисциплина ТВОЕГО ревью, с генезисом (не декор; каждый куплен реальным инцидентом проекта)
|
||
|
||
Проект ведёт письменный канон дисциплины ревьюера (дом — `docs/ORCHESTRATOR_SESSION_PROMPT.md`,
|
||
блок «Анти-паттерны приёмки», и D-ноты D39.46/47/120/121). Шесть ловушек, в которые ревью на
|
||
LLM падает систематически — и как промт §2 их гасит:
|
||
|
||
1. **След отчёта** — ревьюер проверяет только места, НАЗВАННЫЕ автором. У тебя: суди контракт по
|
||
СВОЕЙ карте, построенной из кода и стандартов, а не по карте компаньона и наших ратификаций —
|
||
они и есть «отчёт автора».
|
||
2. **Связность вместо истинности** — гладкий, хорошо мотивированный текст убеждает сам собой
|
||
(наша спека многословно обосновывает свои решения — это форма, не доказательство). Гаситель —
|
||
greenfield §2.2: форма API проектируется ДО знакомства с нашими доводами.
|
||
3. **Соглашательство с чёткой позицией** — LLM склонны соглашаться с уже принятым/сформулированным.
|
||
Отсюда мандат «ратифицировано ≠ правильно» — он не разрешение, а ОБЯЗАННОСТЬ пере-судить.
|
||
4. **Рационализация задним числом** — найдя довод ЗА нашу форму, проверь: существовал бы этот
|
||
довод, если бы ты увидел такую форму в чужом API?
|
||
5. **Слепой участок общих моделей** — модели одного семейства обучены на пересекающихся корпусах:
|
||
подтверждение буллета тем же семейством НЕ независимо. Поэтому кросс-модельные опровергатели
|
||
§2.5 — требование, не пожелание (норма D39.120).
|
||
6. **Экономия усилия на неудобном** — самые дорогие находки живут там, где читать скучно:
|
||
пагинация, коды ошибок, идемпотентность, повторы. Скучное — читать первым, не последним.
|
||
|
||
Плюс три урока наших же ресёрчей и замеров:
|
||
|
||
- **Овер-атрибуция — ТИПОВОЙ провал ресёрчей этого проекта** (верные числа/цитаты не к тому
|
||
предмету; ловилось многократно, вплоть до приёмок): цитаты стандартов — ДОСЛОВНЫЕ, с URL,
|
||
сверенные по первоисточнику; пересказ RFC по памяти модели уликой НЕ является.
|
||
- **Сфабрикованная сходимость** (наш повторявшийся паттерн агрегации): «три линзы сходятся»
|
||
ощущается сильнее данных. Перед мульти-линзовым буллетом — leave-one-out: держится ли он без
|
||
каждой из линз по отдельности.
|
||
- **Вывод на агрегате до вскрытия единиц запрещён** (урок платных замеров, D39.61): вердикт по
|
||
КЛАССУ («ошибки без машинных кодов», «списки без пагинации») — только после вскрытия конкретных
|
||
мест с `file:line`, минимум по одному на затронутую зону.
|
||
|
||
**Предметные оси самопроверки этого пака** (норма D39.120; вправе добавить свою или
|
||
аргументированно снять): (1) *claim-fidelity* — перед сдачей выборочно пере-открой ≥10 случайных
|
||
`file:line`-улик своего отчёта исполнением; (2) *анти-инерция* — у каждого вердикта «оставить как
|
||
есть» записан КОНТРАРГУМЕНТ, который ты рассмотрел и отверг (пустая графа = не судил);
|
||
(3) *полнота интересов* — каждый буллет несёт, чью боль лечит и кому миграция дорога (§4).
|
||
|
||
**Разметка свободы:** метод §2 и входы §3 по ПОКРЫТИЮ — «делай ровно так» (каждому входу —
|
||
диспозиция, вплоть до «делать не надо, потому что…» — это легитимный ответ с аргументом);
|
||
СУЩЕСТВО вердиктов — целиком твоё (ты предлагаешь, ратифицируют владелец и оркестратор).
|
||
Аддендумы к промту доезжают только релеем владельца — эхо-подтверди получение и отрази отдельным
|
||
пунктом отчёта. Жаргон проекта (банк, юнит, волна, банкнота, сид…) — `docs/glossary.md`.
|
||
|
||
**Порядок чтения против якорения:** ты-лид читаешь всё; но greenfield-агентам §2.2 наша спека,
|
||
компаньон, D-ноты и этот раздел НЕ выдаются — им только продуктовый бриф. Мотивы наших правок
|
||
(провенанс ✓/◆/○ компаньона, приёмочные записи фронта) сам читай ПОСЛЕ того, как твоя
|
||
собственная карта фактов §2.1 построена.
|
||
|
||
## 3. Обязательные входы (вопросы, уже стоящие в очереди — каждому дать диспозицию в отчёте)
|
||
|
||
- **Ф-56**: конец разбора книги никто не объявляет — клиент лечится опросом раз в 3 с; кадр/канал?
|
||
- **Ф-57**: какие пары языков продукт принимает — контракт не выражает ни список, ни отказ по паре.
|
||
- **Ф-61 + машинные коды + i18n**: платформа и движок шлют человеческие строки хардкод-английским;
|
||
машинных кодов ошибок нет; слово владельца 15.08 — хардкод недопустим во ВСЕХ зонах; как
|
||
контракт должен нести причины (код + словарь клиента? Accept-Language? где живут фразы)?
|
||
- **Ф-62**: переименование книги — направление «в контракт» ратифицировано (D39.136 п.4в); дать
|
||
форму — и шире: какие записи на книге вообще легитимны (сейчас на всей поверхности НИ ОДНОЙ).
|
||
- **Форма PD-172**: потоковое правило multipart (см. §0) — контракт или протёкшая реализация?
|
||
- **Пагинация и масштабы**: банк пагинирован (1000/курсор), а главы (реальная книга — 2284
|
||
раздела), юниты, замечания, события — нет; сверь масштабы с движковыми артефактами.
|
||
- **Зашитые числа**: 16 частей · 1 КиБ на поле · page 1000 — принадлежат ли контракту (коммент
|
||
кода платформы зовёт их «делом деплоя»).
|
||
- **Паттерн-консистентность**: `paused_reason` required+nullable против `reject_reason` optional
|
||
— одна семантика, два паттерна (спека мотивирует; суди мотивацию); найди ВСЕ такие пары.
|
||
- **Идемпотентность** `POST /books` (ретрай загрузки = дубль книги?), семантика 408/413, 404 как
|
||
«на этом деплое нет интейка».
|
||
- **Версионная политика**: клиент сверяет только мажор, миноры аддитивны — достаточно ли для
|
||
планов S5–S7/Ф3.
|
||
- **К-вопросы компаньона** — статусы и что ревью может закрыть.
|
||
- **Спойлер (В-10)**: ТОЛЬКО если владелец к моменту запуска сказал «защита» — тогда форма
|
||
«sense по явному раскрытию»; если «вежливость» или слова нет — НЕ трогать.
|
||
|
||
## 4. Интересы, которые обязаны быть учтены (владелец 15.08: «учесть интересы все»)
|
||
|
||
Фронт (что реально нужно UI: лаг, спам запросов, honest states) · платформа (реализуемость,
|
||
деньги/холды, деплой) · движок (контракт не должен ВРАТЬ о данных движка и их именах; ложные
|
||
друзья класса source/origin уже ловились) · продукт и планы S5–S7/Ф3 (подпись банка, читалка,
|
||
экспорт — без слома контракта) · индустрия (стандарты §2.3). Конфликт интересов — называть
|
||
явно, не решать молча в чью-то пользу.
|
||
|
||
## 5. Границы
|
||
|
||
- Ты НЕ правишь: спеку · код · бэклог · D-лог · README. Единственный твой файл —
|
||
`docs/research/28-contract-review.md` (отчёт). Дерево НЕ коммитить — лендит оркестратор.
|
||
- $0 по внешним провайдерам перевода: платных LLM-вызовов НЕТ (агент-токены твоего харнесса —
|
||
не в счёт). Интернет — только чтение стандартов/доков.
|
||
- Живой стенд платформы поднимать НЕ требуется (можно read-only читать код тестов, чтобы понять
|
||
поведение; вердикт о рантайме без прогона помечай PLAUSIBLE — D39.129).
|
||
|
||
## 6. Самопроверка и сдача (мандат, не пожелание)
|
||
|
||
- «Заявление = команда»: каждый факт — `file:line` или цитата стандарта с URL; числа — командой.
|
||
- Записка-план по буллетам (ID → статус → улика; D39.121) — движение по ней, сдача = все ID
|
||
имеют диспозицию.
|
||
- Критик полноты на финале: что НЕ покрыто (зона/ось/вход из §3) — явным списком, не молчанием.
|
||
- Obstacle reporting: что не удалось прочитать/проверить — явно.
|
||
- Отчёт `docs/research/28-contract-review.md`: (1) карта фактов по зонам · (2) буллеты
|
||
CONFIRMED/PLAUSIBLE с ценой и рекомендацией, упорядоченные по severity · (3) REJECTED с
|
||
причинами · (4) предложение состава батча 0.3.0 (или честное «контракт здоров, N точечных
|
||
правок») · (5) не покрытое. Владельцу — краткое резюме поверх файла.
|
||
- Стиль отчёта — норма «без саги»: плотность, не объём; эрудиция ≠ улика (каждое утверждение —
|
||
`file:line` или дословная цитата с URL, иначе пометка «мнение»); без пересказа промта и
|
||
шаблонных оговорок.
|
||
|
||
## 7. Канал вопросов
|
||
|
||
Непонятно / промт конфликтует с кодом или доками / нужна правка вне твоего файла → пинг
|
||
оркестратору через владельца, НЕ интерпретация. Настоящие развилки эскалируй быстро — это норма.
|