Make the agent prove its work - Universal Agent Kit

Функции в этом руководствеFunctions in this guideФункції в цьому посібнику

Доказать, что правка работает, прежде чем объявлять её готовойProve a change works before calling it doneДовести, що правка працює, перш ніж оголошувати її готовоюВозьмите самую дешёвую проверку, которая доказывает именно эту правку, запишите ожидаемое и фактическое и называйте шаг готовым, только прочитав результат.Pick the lowest check that proves this change, write down expected and actual, and call the step done only after you have read the result.Візьміть найдешевшу перевірку, що доводить саме цю правку, запишіть очікуване й фактичне та називайте крок готовим, лише прочитавши результат.
Запустить изменение и проверить, что оно правда работаетRun a change and see whether it actually worksЗапустити зміну й перевірити, що вона справді працюєЗапустить и посмотреть: проверка заканчивается одной строкой, PASS, DEFECT, COULD NOT VERIFY или NOT APPLICABLE, с путём к свидетельствам.Run the thing and observe it: the check ends in one line, PASS, DEFECT, COULD NOT VERIFY or NOT APPLICABLE, with the path to its evidence.Запустити й подивитися: перевірка закінчується одним рядком, PASS, DEFECT, COULD NOT VERIFY або NOT APPLICABLE, зі шляхом до свідчень.
Провести ревью изменения и получить замечания по серьёзностиCritique a change and get findings by severityПровести рев'ю зміни й отримати зауваження за серйозністюСжатое ревью diff, документа, набора данных или договора: сначала замечания, самые серьёзные выше, у каждого место и конкретная правка.A terse review of a diff, a document, a dataset or a contract: findings first, highest severity on top, each with a place and a concrete fix.Стисле рев'ю diff, документа, набору даних чи договору: спершу зауваження, найсерйозніші вгорі, у кожного місце й конкретна правка.
Не дать сгенерированному коду сгнитьKeep generated code from rottingНе дати згенерованому коду згнитиСемь шаблонов, которые выглядят нормально и тихо гноят кодовую базу: не пишите их, отмечайте с первого взгляда и блокируйте только новые нарушения.Seven patterns that look fine and quietly rot a codebase: do not write them, flag them on sight, and gate only new violations.Сім шаблонів, що виглядають нормально й тихо гноять кодову базу: не пишіть їх, позначайте з першого погляду й блокуйте лише нові порушення.
Обновить все места, где пользователь встречает изменение, под одним именемUpdate every place a user meets a change, under one nameОновити всі місця, де користувач зустрічає зміну, під одним іменем/surfaces перечисляет все места, где пользователь встречает изменение, до правок, затем выравнивает каждое затронутое под одним именем в каждой авторской локали./surfaces lists every place a user meets a change before any edit, then makes each touched one say the same thing, under one name, in every authored locale./surfaces перелічує всі місця, де користувач зустрічає зміну, до правок, потім вирівнює кожне зачеплене під одним іменем у кожній авторській локалі.
Проверить реализацию по спеке и выставить статус тикета по фактуAudit a build against its spec and set the ticket status from realityПеревірити реалізацію за спекою й виставити статус тікета за фактомСверяет тикет с тем, что реально лежит в файлах, и выставляет статус: Verified, Partial или Broken, а пока открыта ручная проверка, BlockNeedUserTest.Audits a ticket against what the files really contain and sets its status: Verified, Partial or Broken, or BlockNeedUserTest while a manual check is open.Звіряє тікет із тим, що справді лежить у файлах, і виставляє статус: Verified, Partial чи Broken, а поки відкрита ручна перевірка, BlockNeedUserTest.
Обеспечить соблюдение правила механически через хук событияEnforce a rule mechanically with an event hookЗабезпечити дотримання правила механічно через хук подіїПосчитайте, что видит событие, выберите вердикт, при ошибке хука пропускайте вызов и внесите хук в реестр в том же изменении.Count what the event sees, pick a verdict, fail open when the hook errs, and list the hook in an inventory in the same change.Порахуйте, що бачить подія, виберіть вердикт, за помилки хука пропускайте виклик і внесіть хук до реєстру в тій самій зміні.

ШагиStepsКроки

Выберите самую низкую ступень, которая доказывает эту правку: grep < run-script < compile < targeted test < full build < run-and-observe, как описано в лестнице проверок. Не гоняйте весь набор тестов ради переименования в одну строку и не заявляйте об исправлении поведения, имея только компиляцию. Записывайте expected до запуска и actual после и читайте его: проверка, чей actual вы не прочли, не состоялась.Pick the lowest rung that proves this change: grep < run-script < compile < targeted test < full build < run-and-observe, as set out in the validation ladder. Do not run the whole suite for a one-line rename, and do not claim a behaviour fix with only a compile. Write expected before you run and actual after, and read it: a check whose actual you did not read did not happen.Оберіть найнижчий щабель, що доводить цю правку: grep < run-script < compile < targeted test < full build < run-and-observe, як описано в драбині перевірок. Не ганяйте весь набір тестів заради перейменування в один рядок і не заявляйте про виправлення поведінки, маючи лише компіляцію. Записуйте expected до запуску й actual після та читайте його: перевірка, чий actual ви не прочитали, не відбулася.
Оценивайте каждый результат одним из четырёх ответов: PASS, DEFECT, COULD NOT VERIFY или NOT APPLICABLE. Последние два ничего не доказывают. При провале остановитесь: запишите блокер и дайте человеку решить по свидетельствам, ничего не откатывайте автоматически и не идите дальше. Зелёный бывает лживым: у сцепленных команд, команд через конвейер и в фоне код возврата часто принадлежит завершающей обёртке, поэтому читайте строку вердикта нужной операции. «Должно работать» - жёсткая остановка.Score every result with one of four answers: PASS, DEFECT, COULD NOT VERIFY or NOT APPLICABLE. The last two prove nothing. On a failure, stop: record the blocker and let a human decide from the evidence, never auto-revert and never move on. A green can lie: with chained, piped or backgrounded commands the exit status often belongs to a trailing wrapper step, so read the verdict line of the operation that matters. 'Should work' is a hard stop.Оцінюйте кожен результат однією з чотирьох відповідей: PASS, DEFECT, COULD NOT VERIFY або NOT APPLICABLE. Останні дві нічого не доводять. У разі провалу зупиніться: запишіть блокер і дайте людині вирішити за свідченнями, нічого не відкочуйте автоматично й не йдіть далі. Зелений буває брехливим: у зчеплених команд, команд через конвеєр і у фоні код завершення часто належить завершальній обгортці, тому читайте рядок вердикту потрібної операції. «Має працювати» - жорстка зупинка.
Запустите то, что увидит пользователь, и понаблюдайте. /prove запускает цель, проходит сценарий из одного-пяти шагов, снимает вывод и логи и заканчивает одной строкой с целью и ровно одним вердиктом, указывая путь к файлу сценария в scratch. Если цель или инструмент недоступны, он говорит COULD NOT VERIFY и успех не изображает. Спеки, планы и статусы он не правит и ничего не коммитит.Run what the user will see and observe it. /prove starts the target, walks a scenario of one to five steps, captures the output and logs, and ends in one line with the target and exactly one verdict, with the path of the scenario file in scratch. If the target or the instrument is out of reach it says COULD NOT VERIFY and never fakes a pass. It edits no specs, plans or statuses and commits nothing.Запустіть те, що побачить користувач, і поспостерігайте. /prove запускає ціль, проходить сценарій з одного-п'яти кроків, знімає вивід і логи та закінчує одним рядком із ціллю й рівно одним вердиктом, вказуючи шлях до файлу сценарію в scratch. Якщо ціль або інструмент недоступні, він каже COULD NOT VERIFY і успіх не вдає. Спеки, плани та статуси він не править і нічого не комітить.
Отдайте дифф на ревью командой /critique. Она читает изменение и достаточно окружающего кода, проверяет по порядку корректность, безопасность данных, архитектуру, тесты, правила против мусора и ясность и выдаёт замечания в виде severity · file:line · проблема · конкретная правка, от bug до q. Замечания высокой серьёзности она сначала подтверждает или опровергает сама, а в конце называет единственное самое важное, что нужно решить до слияния.Have the diff reviewed with /critique. It reads the change and enough surrounding code, checks correctness, security and data safety, architecture, tests, anti-slop and clarity in that order, and reports findings as severity · file:line · the problem · a concrete fix, from bug down to q. It confirms or refutes its own high-severity findings first, and closes with the single most important thing to address before merge.Віддайте діф на рев'ю командою /critique. Вона читає зміну й достатньо навколишнього коду, перевіряє за порядком коректність, безпеку даних, архітектуру, тести, правила проти сміття й ясність та видає зауваження у вигляді severity · file:line · проблема · конкретна правка, від bug до q. Зауваження високої серйозності вона спершу підтверджує або спростовує сама, а наприкінці називає єдине найважливіше, що треба розв'язати до злиття.
Просмотрите дифф на семь шаблонов, которые выглядят нормально и тихо гноят кодовую базу, они перечислены в разделе против мусора: каждый ищется grep'ом, так что проверка может входить в «готово». В кодовой базе, которая уже нарушает правило, блокируйте только новые нарушения: зафиксируйте текущее число как закоммиченную базовую линию, которую инструмент может снижать, но обязан отказываться поднимать, так что долг идёт только вниз, как на храповике.Scan for the seven patterns that look fine and quietly rot a codebase, listed in anti-slop: each one is greppable, so the check can be part of 'done'. On a codebase that already breaks a rule, gate on new violations only: freeze the current count as a checked-in baseline that tooling may lower but must refuse to raise, so the debt only ratchets down.Перегляньте діф на сім шаблонів, які виглядають нормально й тихо гноять кодову базу, вони перелічені в розділі проти сміття: кожен шукається grep'ом, тож перевірка може входити в «готово». У кодовій базі, що вже порушує правило, блокуйте лише нові порушення: зафіксуйте поточну кількість як закомічену базову лінію, яку інструмент може знижувати, але мусить відмовлятися піднімати, тож борг іде лише вниз, як на храповику.
Докажите, что видимое пользователю изменение дошло до каждой поверхности, то есть до каждого места, где пользователь с ним встречается, через /surfaces. Таблица поверхностей печатается до любых правок, а строка «не применимо» обязана назвать причину: так прячется забытая поверхность. После правки затронутых строк во всех авторских локалях команда ищет по ним ключевое существительное и прежнее имя и сообщает счётчики. Изменение, которого никто не видит, заканчивается строкой surfaces: not user-visible - <reason>.Prove that a user-visible change reached every surface, every place a user meets it, with /surfaces. It prints the table of surfaces before any edit, and a row marked not applicable must name its reason, since that is how a forgotten surface hides. After editing the touched rows in every authored locale it greps the key noun, and any old name it replaced, across them and reports the counts. A change nobody can see ends with surfaces: not user-visible - <reason>.Доведіть, що видима користувачеві зміна дійшла до кожної поверхні, тобто до кожного місця, де користувач із нею зустрічається, через /surfaces. Таблиця поверхонь друкується до будь-яких правок, а рядок «не застосовно» мусить назвати причину: так ховається забута поверхня. Після правки зачеплених рядків в усіх авторських локалях команда шукає по них ключовий іменник і попереднє ім'я та повідомляє лічильники. Зміна, якої ніхто не бачить, завершується рядком surfaces: not user-visible - <reason>.
Проведите аудит тикета по спеке командой /spec-check. Она проверяет файлы, сборку не запускает и выставляет статус по найденному. Для Verified каждая проверка должна быть PASS или EXEMPT, а открытых ручных пунктов быть не должно; упавшая проверка или не добравшаяся до предмета даёт Broken, предупреждение - Partial, а открытая ручная проверка держит тикет на BlockNeedUserTest. Проверка человеком, которой ещё не было, - не зачёт, а ожидание: строку в ## Manual checks отмечает человек, а /prove лишь даёт доказательство.Run an audit of the ticket against its spec with /spec-check. It checks the files, runs no build and sets the status from what it finds. Verified needs every check to be PASS or EXEMPT and no manual item open; a failed check, or one that could not reach its subject, gives Broken, a warning gives Partial, and an open manual check holds the ticket at BlockNeedUserTest. A human check that has not happened is pending, not a pass: the human ticks the line in ## Manual checks, and /prove only supplies evidence.Проведіть аудит тікета за спекою командою /spec-check. Вона перевіряє файли, збірку не запускає й виставляє статус за знайденим. Для Verified кожна перевірка має бути PASS або EXEMPT, а відкритих ручних пунктів бути не повинно; перевірка, що впала або не дісталася предмета, дає Broken, попередження - Partial, а відкрита ручна перевірка тримає тікет на BlockNeedUserTest. Перевірка людиною, якої ще не було, - не залік, а очікування: рядок у ## Manual checks позначає людина, а /prove лише дає доказ.
Когда одно и то же правило раз за разом игнорируют, уберите его из прозы. В эталонном корпусе kit правило прозой выполнялось в 1-8% случаев, а с механической проверкой за спиной - примерно в 99% (одно портфолио, а не константа для вашего проекта). Берите хук события, когда сбой настоящий, повторяющийся и механически обнаруживаемый. Назовите событие, посчитайте, какая доля интересующих вас случаев через него проходит, и выберите вердикт.When the same rule keeps getting ignored, move it out of prose. In the kit's reference corpus a rule as prose was followed 1-8% of the time, against about 99% with a mechanical check behind it (one portfolio, not a constant for your project). Use an event hook when the failure is real, recurring and mechanically detectable. Name the event, count how much of what you care about actually passes through it, then pick the verdict.Коли одне й те саме правило раз у раз ігнорують, приберіть його з прози. В еталонному корпусі kit правило прозою виконувалося в 1-8% випадків, а з механічною перевіркою за спиною - приблизно в 99% (одне портфоліо, а не константа для вашого проєкту). Беріть хук події, коли збій справжній, повторюваний і механічно виявний. Назвіть подію, порахуйте, яка частка цікавих вам випадків через неї проходить, і виберіть вердикт.
Опишите контракт хука и проверьте его с обеих сторон. Хук с отказом блокирует сигналом блокировки среды - одним конкретным кодом выхода, а не любым сбоем (в Claude Code это код 2, а код 1 не блокирует никогда), с нулём разрешает и при ошибке разбора, пути или ввода-вывода пропускает вызов. Где верный ввод известен, исправляйте его, а не отказывайте. Пробуйте и ввод, который хук обязан отклонить, и ввод, который обязан пропустить: вторые случаи самые важные, потому что защиту, которая блокирует лишнее, выключают. В том же изменении добавьте хуку строку в реестр хуков.Write the hook's contract and test it from both sides. A refusing hook blocks with the runtime's blocking signal, one specific exit code and not any failure (in Claude Code exit 2; exit 1 never blocks), exits zero to allow, and fails open on any parse, path or IO error. Where the correct input is knowable, correct it instead of refusing. Try payloads it must refuse and payloads it must allow: the allow cases carry the weight, because a guard that over-blocks gets switched off. In the same change, add a row for the hook to the hook inventory.Опишіть контракт хука й перевірте його з обох боків. Хук із відмовою блокує сигналом блокування середовища - одним конкретним кодом виходу, а не будь-яким збоєм (у Claude Code це код 2, а код 1 не блокує ніколи), з нулем дозволяє і за помилки розбору, шляху чи вводу-виводу пропускає виклик. Де правильний ввід відомий, виправляйте його, а не відмовляйте. Пробуйте і ввід, який хук зобов'язаний відхилити, і ввід, який зобов'язаний пропустити: другі випадки найважливіші, бо захист, що блокує зайве, вимикають. У тій самій зміні додайте хукові рядок у реєстр хуків.

Что вы должны увидетьWhat you should seeЩо ви маєте побачити

Каждое «готово» подкреплено строками expected и actual, которые вы прочли, вердиктом /prove там, где важно поведение, ревью с уровнями серьёзности, таблицей поверхностей видимого изменения, статусом тикета, выставленным аудитом, а повторяющийся сбой теперь ловит зарегистрированный и проверенный хук, а не напоминание.Every claim of 'done' comes with an expected line and an actual line you have read, a verdict from /prove where behaviour mattered, a review with severities, a table of the surfaces of a user-visible change, a ticket status set by an audit, and a recurring failure now caught by a registered, tested hook instead of a reminder.Кожне «готово» підкріплене рядками expected і actual, які ви прочитали, вердиктом /prove там, де важлива поведінка, рев'ю з рівнями серйозності, таблицею поверхонь видимої зміни, статусом тікета, виставленим аудитом, а збій, що повторюється, тепер ловить зареєстрований і перевірений хук, а не нагадування.

Заставить агента доказывать свою работуMake the agent prove its workЗмусити агента доводити свою роботу

Функции в этом руководствеFunctions in this guideФункції в цьому посібнику

ШагиStepsКроки

Термины на этой страницеTerms on this pageТерміни на цій сторінці