review · git:20261102.4ccab09 · 2026-11-02 · sha256 c3c80ab98135e58f
review git:20261102.4ccab09A
Immutable. This exact content never changes and is served at /api/v1/blob/c3c80ab98135e58f.
---
name: review
description: Незалежна рецензія плану чи документа кількома агентами. Окремий агент-координатор вибирає вузьких рецензентів (узгодженість, структура, здійсненність, опонент рішень, безпека, архітектура, мережа, вимоги, доменний експерт тощо); вони працюють паралельно й незалежно; знахідки щодо документа ще перевіряє опонент; головна сесія звіряє кожну знахідку з джерелом і зводить для власника. Великий документ ділиться на частини між рецензентами. Для нечутливих проєктів план додатково йде на Codex. Використовувати завжди, коли власник каже «план готовий», «перевір незалежно», «прожени план через рецензентів», «рецензія HLD», «рецензія ТЗ», «мультиагентна рецензія документа», «прожени документ через рецензентів», «тест читача», «чи зрозуміло це без мене», а також перед тим, як ADR, план чи документ іде в роботу. Не вмикатися на перевірку мови й «перевір ТЗ» (language), фактчекінг (factcheck), письмо чи правку тексту (write) і на художній текст — тест читача глави чи сцени робить ukrainian-fiction.
---
# Рецензія плану чи документа
План чи документ, складений у розмові, перевіряють агенти, які цієї розмови не
бачили. Головна сесія разом із власником складала предмет і тому схильна
вважати важливим те, що обговорили, і не бачити пропущеного. Тому рецензентів
вибирає не вона, а окремий координатор, і кожен рецензент бачить лише текст
предмета.
Рецензенти — вузькі кути огляду, однакові для плану й документа. Що в
конкретному жанрі вважати знахідкою, визначає жанровий файл пакета
(`../../shared/genres/<жанр>.md` від теки цього скіла), а дані проєкту — його
профіль (слот «Рецензія»). Скіл даних проєктів не тримає.
Агенти скіла лежать у теці `agents/` плагіна й мають повне ім'я з префіксом
плагіна: `ukrainian-tech-docs:review-coherence` тощо. У цьому файлі й у
`references/` вони названі коротко, без префікса. Файлів скіла агенти самі не
знаходять: абсолютні шляхи до теки скіла й до `shared/` їм передає головна
сесія в завданні (крок 5).
## Коли
- Після планування — завжди: щойно власник сказав, що план готовий.
- На прохання «перевір незалежно» — для плану, ADR чи документа, що йде
в роботу.
- На прохання рецензувати документ: HLD, LLD, ТЗ, runbook, концепцію.
«Перевір ТЗ» без слова «рецензія» чи «незалежно» — аудит ТЗ скілом
`language`, а не рецензія.
- Перед виходом документа Замовнику рецензія сама не вмикається: якщо її ще
не було, головна сесія пропонує її власникові одним рядком.
- Власник каже «план готовий», а плану в розмові немає — спитати, де план
(файл чи текст), і без нього не починати.
- Не для дрібних нот, правок і реєстрів.
## Два режими
| | План | Документ |
|---|---|---|
| Предмет | план, ADR як рішення до виконання | документ будь-якого жанру |
| Рецензенти повертають | до семи рядків (`review-contract.md`) | компактні рядки без межі й списки (`review-contract.md`, `document.md`) |
| Рецензія опонента | ні: знахідки звіряє головна сесія | так, `review-verifier` (`consolidation.md`, розд. 2) |
| Codex | для нечутливих проєктів | ні: `codex-whole-plan.md` написано для плану |
| Великий предмет | — | ділиться на частини (`large-document.md`) |
| Звіт | таблиця в чаті (крок 6) | звіт за `report.md` |
Документ більший за межу читання одного рецензента (близько 170 КБ разом з
обов'язковими правилами й першоджерелами) — головна сесія читає
`large-document.md` і йде за його фазами. Кроки нижче лишаються каркасом.
Знахідки опрацьовує головна сесія: звіряє, зводить, показує власникові.
Координатор лише вибирає рецензентів.
### Склад за типом документа
| Документ | Склад |
|---|---|
| Великий документ з архітектурними рішеннями — HLD, LLD, пакет вимог, документ на багато частин, повний прогін | повний: кути, чиї предмети в документі є, перехресна перевірка, опоненти, зведення (`large-document.md`). Оцінку обсягу й кількість агентів власник бачить на фазі 0 |
| Документ до межі читання, частковий прогін кількох частин, ADR, окрема глава | не більше п'яти агентів разом з опонентом: два-чотири кути, чиї предмети в частинах найсильніші, і `review-verifier`. Суміжний кут зі слабким сигналом не запускається окремо, а його предмет бере сильніший кут (мережу глави про ізоляцію — безпека, схеми — узгодженість). Перехресна перевірка `ПЕР` входить у стелю: її запускають замість одного кута, якщо власник так вирішив на фазі 0. Інакше пари «Залежностей назовні» йдуть у звіт списком «Не перевірено через межу прогону» |
| Похідний документ без власних рішень — стислий виклад, оглядова нота | ролями не рецензується. Працює звірка з батьківським документом у два боки з проходом розділу «Компроміси» (`review-coherence`) |
Стеля в п'ять агентів — рішення власника 2026-11-01. Більше — лише коли
власник прямо погодив склад на фазі 0.
Похідний документ не рецензують ролями, бо його правильність — це правильність
переносу з батьківського документа, і її ловить звірка. Ролі на такому
документі дублюють рецензію батьківського, а доповнення власника, яких
батьківський документ ще не має, читають як дефект. Якщо власник усе ж запускає
ролі на похідному документі, у бриф ідуть дві речі: батьківський документ як
джерело істини й перелік доповнень власника, які знахідкою не є.
### Тест читача
«Тест читача», «чи зрозуміло це без мене» — окремий легкий режим за
`../../shared/genres/general.md`, розд. 6: один свіжий субагент читає документ
без контексту розмови й каже, що незрозуміло. Координатора, кутів й опонента в
цьому режимі немає. Текст не правиться.
Без субагентів тест читача робить головна сесія окремим проходом: читає лише
текст документа, не спираючись на розмову, і записує питання, які виникли б у
читача, якого називає документ чи власник. Звіт першим рядком каже: «Читач не свіжий:
тест пройшла модель, яка бачила розмову про документ.»
### Середовище без субагентів
Скіл розрахований на субагентів: координатор, кути й опонент працюють у
власних контекстах і не бачать розмови. Там, де субагентів немає (звичайний
чат), рецензія йде запасним шляхом. Кроки 2 і 5 тоді виконуються так:
1. **Замість координатора** головна сесія сама читає `references/roster.md` і
вибирає кути за тими самими умовами «коли вмикати» й «коли не вмикати», з
тією самою стелею складу. Таблицю «кут · брати · чому» вона показує в
оголошенні (крок 4).
2. **Кути по черзі.** Для кожного кута прочитати його файл із теки `agents/`
плагіна як інструкцію ролі. Поля завдання, на які файл агента посилається,
заповнюються так:
- `<тека скіла>` — тека `skills/review/` цього плагіна, спільна тека —
`shared/`;
- правила проєкту, профіль, слот «Рецензія» — як у кроці 1; немає — поле
пропускається, а у звіті є рядок «не було: <поле>»;
- кроки, яким потрібна тека проєкту (минулі уроки, наявне в проєкті), —
лише коли проєкт і його тека відомі; інакше рядок «не перевірялось: немає
теки проєкту».
`references/review-contract.md` і, для документа, `references/document.md`
читаються один раз, перед першим кутом.
3. **Знахідки кута записуються до наступного кута.** Файловий вихід є
(скретчпад чи тека прогону) — у файл `<код кута>.md` теки прогону, як у
кроці 5, але рукою, без скрипта `extract-agent-reply.py`. Файлового виходу
немає — окремим блоком відповіді із заголовком кута. Наступний кут не
перечитує знахідок попередніх і не спирається на них. Повної ізоляції в
одній розмові немає, і саме про це каже рядок над звітом (п. 5).
4. **Опонент** — для документа: прохід за `agents/review-verifier.md` по всіх
знахідках, з тими самими вердиктами (`consolidation.md`, розд. 2).
5. **Звіт** — за `references/report.md` (для плану — таблиця кроку 6). Над
звітом, перед його першим розділом, стоїть рядок: **«Рецензія не
незалежна: кути проходила та сама модель у цій розмові й бачила попередні
кути та обговорення предмета.»** Файловий вихід є — звіт файлом у теці
прогону, а в чаті — розд. 1 і таблиця розд. 3 (`report.md`, «Звіт у чаті»);
немає — увесь звіт у чаті.
Codex у цьому режимі не запускається.
Цей запасний шлях — не те саме, що «Послідовний режим» великого документа
(`large-document.md`, розд. 7): там субагенти є, а кути йдуть по черзі через
межу контексту головної сесії.
Слабша перевірка краща, ніж жодної, коли звіт чесно каже про її межу.
## Крок 1. Предмет у файл
Рецензенти читають той самий текст, а не переказ.
- План чи документ уже лежить у сховищі проєкту чи репозиторії — беремо цей файл (для
документа із частинами — зміст і теку частин).
- План є лише в розмові — записати його в скретчпад сесії:
`<скретчпад>\review\<РРРР-ММ-ДД>-<коротка-тема>\plan.md`. Текст — повний,
як погоджено з власником, без скорочень.
Визначити проєкт і шляхи до його правил для рецензентів. Їх називає сам
проєкт: рядок «Правила для рецензентів» у кореневому файлі проєкту для агента
(`CLAUDE.md` чи аналог) або профіль проєкту, слот «Рецензія». Рядка немає —
взяти `CLAUDE.md` теки проєкту, якщо він є, і
сказати власникові, що рядка бракує. Шляхи не вигадувати.
Для документа знайти профіль проєкту й слот «Рецензія». Слота немає — сказати
власникові, яких даних бракує (`large-document.md`, розд. 1), і не вигадувати
їх.
## Крок 2. Координатор
Запустити агента `review-coordinator` (окрема задача в чеклісті: «Субагент:
вибір рецензентів»). У завданні — лише тип предмета (план, ADR чи документ із
жанром), шлях до плану або до змісту й вступу документа, розмір документа,
назва проєкту, стеля складу з таблиці «Склад за типом документа»,
базовий набір вимог із профілю (назви й шляхи джерел або «немає») і, для
часткового прогону, вибрані частини зі шляхами до них. Висновків сесії,
побажань щодо складу й переказу предмета не давати.
Без рядка про базовий набір координатор не вмикає `review-requirements`:
умова roster спрацьовує лише тоді, коли набір названо в завданні. У пробному
прогоні 2026-11-02 координатор через це відкинув кут вимог словами «набору
вимог у прогоні немає».
Координатор повертає таблицю «рецензент · брати · чому».
## Крок 3. Друга модель
Лише для плану. Широку сітку на Codex вирішує головна сесія, а не координатор:
чутливість даних класифікує власник.
Чи можна віддати предмет сторонній моделі, каже правило чутливості проєкту:
профіль, слот «Рецензія», рядок «Субагенти», або правила проєкту. Правила
немає — Codex не запускати, а в оголошенні спитати власника. Заборона в
правилах проєкту діє, поки власник прямо не дозволив Codex для цього плану.
Перед першим запуском Codex у сесії переконатись, що власник вимкнув навчання
в ChatGPT («Налаштування → Керування даними»). Якщо загальні правила
користувача це вже фіксують — не питати. Не підтверджено — Codex не запускати
й сказати про це в оголошенні.
## Крок 4. Оголошення
Одним-двома реченнями сказати власникові, кого запущено й кого відкинуто, з
причиною в кілька слів біля кожного умовного рецензента. Не чекати відповіді:
власник може зупинити чи додати агента. Приклад:
> Рецензують узгодженість, здійсненність, обсяг, експлуатація (скрипт
> запускатиметься щотижня) і Codex. Безпека не потрібна: скрипт лише читає
> локальні файли.
Для великого документа замість оголошення — контрольна точка фази 0
(`large-document.md`, розд. 6): там далі лише після підтвердження власника.
Поки рецензенти працюють, не повідомляти про кожного, хто повернувся.
## Крок 5. Рецензенти
Усіх вибраних запустити паралельно, одним повідомленням; `review-verifier` —
пізніше, на кроці 6. Кожен — окрема задача в чеклісті: «Субагент:
<рецензент>». Завдання кожному однакове:
```text
Рецензія <плану | документа>.
Предмет: <шлях до plan.md | шлях до документа чи перелік частин цього рецензента>
Тип: <план | ADR | документ, жанр: <HLD, LLD, ТЗ…>>
Проєкт: <назва>
Правила проєкту: <шляхи з кроку 1>
Файли скіла: <абсолютний шлях до теки скіла review>; спільна тека: <абсолютний шлях до shared/ плагіна>
<для документа: «Профіль: <шлях>, слот «Рецензія». Код кута: <код>.
Бриф: <шлях до brief.md>» — бриф лише для великого документа>
<для документа з межею читання: «Межі читання: <файл · до рядка N>» або
посилання на розділ брифу, де вони стоять>
<коли кут бере предмет незапущеного: «Додатково бере предмет кута <код>:
<що саме, у яких частинах>»>
<для кута, що залежить від `ВИМ`: «Таблиця вимог: <шлях> — відміть покриття
вимог своїх частин»>
<для повторного прогону: «Повторний прогін, коло N. Змінено: <розділи>.
Відхилено власником: <перелік>»>
```
Понад це в завдання нічого не йде — ні висновків сесії, ні того, що вже знайшли
інші.
Для документа відповідь кожного рецензента записується дослівно в теку
прогону: `<скретчпад>\review\<РРРР-ММ-ДД>-<тема>\<код>.md`. Записує її скрипт,
а не модель:
```bash
python <тека скіла>/scripts/extract-agent-reply.py <agent-id> "<тека прогону>/<код>.md"
```
Скрипт бере останню відповідь агента з його журналу
(`~/.claude/projects/<тека-проєкту>/<сесія>/subagents/agent-<id>.jsonl`).
Файл `output_file`, який повертає інструмент запуску агента у фоні, порожній, а
передрук відповіді моделлю коштує 30–40 КБ виводу на кут і може її змінити
(перевірено 2026-11-02). Опонент і перехресна перевірка отримують шляхи до
цих файлів, а не переказ.
Codex — лише для плану, у фоні, паралельно з рецензентами:
```powershell
$dir = '<порожня тека прогону>'
$task = Get-Content -Raw '<тека скіла>\references\codex-whole-plan.md'
$plan = Get-Content -Raw '<шлях до плану>'
$task + "`n`n<<<PLAN`n" + $plan + "`nPLAN>>>`n" |
& "$env:USERPROFILE\.codex\.sandbox-bin\codex.exe" exec -s read-only --skip-git-repo-check --ephemeral -C $dir -o "$dir\codex-findings.md" -
```
План іде Codex текстом у завданні, а не файлом: на Windows у пісочниці
`read-only` не стартує інструмент команд, і `plan.md` Codex прочитати не може
(перевірено 2026-11-01). Заборона читати файли стоїть у завданні, а не в
пісочниці, тож межа чутливості з кроку 3 обов'язкова.
## Крок 6. Зведення
### План
Знахідки агентів — не факти. Перш ніж показати власникові, кожну:
1. звірити з джерелом: прочитати процитоване місце плану й файл чи сторінку з
колонки «Джерело»;
2. поставити вердикт: `підтверджено`, `хибна` (з причиною одним рядком) або
`не перевірити` (що саме пробував);
3. злити повтори в один рядок із переліком рецензентів, що знайшли.
Таблиця для власника:
| № | Вага | Знахідка | Хто знайшов | Джерело | Вердикт |
|---|---|---|---|---|---|
- Знахідку, яку незалежно дали двоє рецензентів на Claude, позначати «двоє
незалежно», але не «підтверджено»: модель та сама, і помилка в них може бути
спільна.
- Знахідки Codex позначати «інша модель».
- Хибні знахідки — окремим коротким списком під таблицею, щоб власник бачив, що
відкинуто й чому.
- Під таблицею — один рядок: які рецензенти не мали знахідок.
### Документ
1. Для великого документа — перехресна перевірка `ПЕР` (`large-document.md`,
фаза 3).
2. Рецензія опонента: головна сесія розподіляє знахідки між агентами
`review-verifier` так, щоб кожна дісталась рівно одному (`large-document.md`,
фаза 4). Документ до межі читання — один опонент на всі знахідки.
3. Звірка вердиктів: кожна знахідка має вердикт опонента або позначку «без
рецензії опонента» з причиною.
4. Зведення і розбіжності — `consolidation.md`, розд. 3–4; для великого
документа — за групами, потім підсумкове зведення через межу груп.
5. Звіт — за `report.md`, у чаті. Запис у сховище проєкту — лише після
підтвердження власника, ім'я і тека — з профілю (`large-document.md`,
розд. 8).
## Крок 7. Правка й повторний прогін
Що правити, вирішує власник. Рецензія частин, не змінених після попередньої
рецензії, здебільшого повторює вже записане: у прогоні 2026-11-02 так вийшло
16 знахідок із 35. Тому фаза 0 звіряє дати й дає власникові вибір
(`large-document.md`, розд. 6). Повторний прогін — лише на його запит і лише для
змінених частин: перезапустити тих, чию ділянку зачепила правка, і завжди
`review-coherence`, бо нові суперечності з'являються саме в правках. Не більше
трьох кіл: на третьому, якщо лишились блокери, сказати власникові, що латати
предмет далі не варто й треба переглянути підхід.
Правка документа за знахідками йде через скіл `write` пакета, а не в
рецензії.
## Закривальний рядок
Після звіту — закривальний рядок і підсумок маркерів за
`../ukrainian-tech-docs/SKILL.md`, розд. 3: які файли скіла прочитано, які кути
й опонент працювали, у якому режимі (із субагентами чи запасним шляхом), і
«текст не змінювався». Рецензія маркерів у предмет не ставить. Приклад:
`Стадії: рецензія документа (review/SKILL, roster, review-contract, document, consolidation, report) · режим: запасний шлях · кути (УЗГ, ЗДС, СТР, БЕЗ) · опонент (review-verifier) · текст не змінювався`.
## Склад
| Файл | Що це |
|---|---|
| `references/roster.md` | Перелік рецензентів з умовами вибору для плану й для документа — його читає координатор (англійською: координатор на Haiku) |
| `references/review-contract.md` | Спільний формат знахідок і межі для всіх рецензентів, окремо для плану й документа |
| `references/document.md` | Спільні правила рецензії документа: стик зі скілом письма, що не вигадувати, типи, серйозність, упевненість, уже відоме, межа жанру, фактчекінг |
| `references/large-document.md` | Великий документ: межа читання, розподіл частин, фази 0–6, послідовний режим, частковий прогін |
| `references/consolidation.md` | Суперечності, рецензія опонента, зведення, розбіжності, перевірка перед звітом |
| `references/report.md` | Структура звіту рецензії документа |
| `references/codex-whole-plan.md` | Завдання для широкої сітки на Codex (англійською: читає інша модель) |
| `scripts/extract-agent-reply.py` | Дослівний запис відповіді субагента з його журналу у файл теки прогону (крок 5) |
| `agents/review-*.md` плагіна | Координатор, рецензенти й опонент. Доменного експерта (агента конкретного проєкту) називає профіль проєкту, слот «Рецензія»; у плагін доменні агенти не входять |
Рецензенти й коди їхніх знахідок у документі:
| Агент | Кут | Код |
|---|---|---|
| `review-coherence` | узгодженість; перехресна перевірка частин | `УЗГ`, `ПЕР` |
| `review-structure` | структура документа: зміст, додатки, джерела, терміни, коди | `СТР` |
| `review-feasibility` | здійсненність, минулі уроки, документ без автора | `ЗДС` |
| `review-scope` | обсяг, межа жанру | `ОБС` |
| `review-adversary` | опонент рішень | `СПР` |
| `review-security` | безпека | `БЕЗ` |
| `review-operations` | експлуатація | `ЕКС` |
| `review-architecture` | архітектура, доступність, відмови, масштабування | `АРХ` |
| `review-network` | мережа й потоки | `МЕР` |
| `review-platform` | хмарна й гібридна платформа | `ПЛТ` |
| `review-capacity` | ресурси й ємність | `РЕС` |
| `review-requirements` | вимоги й трасування | `ВИМ` |
| `review-diagrams` | текст ↔ схема | `СХЕ` |
| `review-reality` | зовнішні твердження плану | — |
| `review-verifier` | рецензія опонента на знахідки | `ОПН` |
Нового рецензента додають файлом агента й рядком у `roster.md` з умовою «коли
вмикати» і «коли не вмикати». Рецензенти інструмента запису не мають; у теку
прогону пише лише головна сесія.
## Джерела
- Compound Engineering, `ce-doc-review`, MIT:
[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin/tree/main/skills/ce-doc-review) —
двоє рецензентів завжди, решта за письмовими умовами вмикання і невмикання,
оголошення складу одним реченням, повторний прогін лише змінених ділянок,
широка сітка на іншій моделі (`whole-doc-reviewer`), пошук минулих уроків
(`learnings-researcher` з `ce-plan`), опис рецензента умовою, а не роллю.
- review-council, MIT: [deployhq/review-council](https://github.com/deployhq/review-council) —
друга модель через `codex exec`, позначка знахідок за моделлю.
- agent-review-panel, MIT: [wan-huiyan/agent-review-panel](https://github.com/wan-huiyan/agent-review-panel) —
застереження, що рецензенти однієї моделі — самокритика, а не незалежна
перевірка.
- unlazy, MIT: [Leonxlnx/unlazy](https://github.com/Leonxlnx/unlazy) — перевірка,
що вміє провалитись, і переміряні числа в `review-operations`.
- Власний промпт мультиагентної рецензії HLD (редакція 2026-09-28, тест
2026-10-01) — метод для документа: ролі, формат знахідки,
фази, рецензія опонента, звіт. Шаблон, з якого він зібраний, — «MASTER PROMPT:
MULTI-AGENT HLD REVIEW».