AGENTS.md — работа над самим AQK

Это точка входа для агента, работающего над комплектом, а не над проектом-получателем. Что это за проект, где мы сейчас и что дальше — в README.md. Здесь только правила работы.

Железные правила

• План до кода. Нетривиальная задача начинается с плана, одобренного словами. <!-- aqk: человек -->
• Красный тест до кода. Сначала проверка, которая падает. <!-- aqk: человек -->
• Максимум 3 попытки. Не решил за три — стоп и человеку. <!-- aqk: человек -->
• Готово = доказано. Назови арбитра: прогон, живая проверка, сверка. «Выглядит рабочим» — <!-- aqk: человек --> не готово.
• Развилка — вопрос человеку, а не комментарий в коде. <!-- aqk: человек -->
• Цитата сверяется с первоисточником перед публикацией. <!-- aqk: человек --> В графе «откуда» пишется место, где лежит дословный текст — файл и строка либо ссылка, а не название проекта. Проверено 2026-09-06 — в опубликованной статье две строки, оформленные дословной цитатой из документации pre-commit, оказались нашей же формулировкой их позиции: запись «откуда: pre-commit.com» через неделю прочиталась как цитата с того сайта.
• Любое сомнение проверяется снаружи. Всегда, а не когда покажется важным. Не знаешь, как <!-- aqk: человек --> принято сейчас; не знаешь, есть ли готовое; собираешься написать то, что наверняка уже написано; помнишь ответ, но помнишь его из обучения, а не из проверки, — ищи. Обучение агента кончилось в прошлом, а мир нет: догадка выглядит как знание и стоит столько же, сколько ошибка. «Спрошу владельца» поиска не заменяет: человек чаще всего не знает тоже, и вдвоём вы договоритесь до местного костыля вместо общепринятого решения — с той разницей, что костыль будет выглядеть согласованным. Спрашивать человека надо о том, чего нет снаружи: чего он хочет. Если выхода в сеть нет — сказать вслух «не проверено, догадка», а не выдать одно за другое. Проверено 2026-09-08 — три адреса чужих репозиториев были написаны по памяти, уверенно и подряд; все три дали 404. Те же адреса, взятые из реестра npm, оказались верными, и попутно выяснилось, что проектов с именем agentlint два, разных, — этого память сообщить не могла в принципе. Раньше, 2026-09-06, тот же класс: разбор каталога начался с догадки «поле зрелости надо завести, как у соседей», а их код показал, что копировать надо было не форму, а отказ.
• Прибор раньше улучшений. Прежде чем чинить, заводи то, чем видно, что чинить. Правило не <!-- aqk: человек --> о том, как заканчивать («готово = доказано»), а о порядке: без прибора улучшают то, что заметно, а не то, что сломано. Проверено 2026-09-06 — мутационная проверка гейтов, написанная до единой правки, нашла четыре записи из пятнадцати, врущих на windows-переносах строк; ни одна из них не была в списке того, что мы собирались чинить.
• Зависимостей у CLI нет и не будет. Инструмент, который ставят одной командой в чужой <!-- aqk: deps-are-pinned --> проект, обязан читаться глазами за один присест. Каждая библиотека — лишняя дверь в цепочке поставок и лишний узел надёжности.

Правила самого стандарта

• Если утверждение не проверяется машиной — его в стандарте нет. Иначе уровень означает <!-- aqk: человек --> доверие к автору, а не факт.
• Ступень не добавляется без проверки. Сначала код, который её считает, потом строка в <!-- aqk: человек --> таблице.
• Зрелость записи считается, а не объявляется. Поле, которое заполняет автор, означает <!-- aqk: gates --> доверие к автору. Единственное исключение — deprecated: это решение, а не факт, и оно обязано нести преемника.
• Стандарт описывает то, что мы уже делаем. Всё, чего мы сами не соблюдаем, из него вылетает. <!-- aqk: человек -->
• Запись опознаёт конструкцию, а не понимает текст. Первое устойчиво, второе хрупко по <!-- aqk: человек --> построению. Замер 2026-09-15 по 400 чужим репозиториям: двенадцать наших шестнадцати ложных срабатываний дали две записи, читающие свободный текст; три остальные записи вместе дали четыре. Запись второго рода обязана называть цену вслух и не может быть основанием писать человеку. Подробно — SPEC.md §6.
• Раздувание = смерть. Появилось желание добавить десятый пункт «для полноты» — не добавлять. <!-- aqk: человек -->

Где что лежит

Опись файлов — в MAP.md: что лежит в tool/lib, tool/commands, tool/selfcheck, kit/ и зачем каждый файл существует. Вынесена отдельно, потому что свод обязан умещаться в предел, за которым Codex молча перестаёт читать (32 КиБ), а опись — справочник, нужный только тому, кто лезет в код. Её полноту сторожит проверка №104.

Команды

• проверить синтаксис всех исходников: bash tool/selfcheck/syntax.sh
• прогнать на чистой папке: T=$(mktemp -d) && cd "$T" && git init -q . && node <путь>/tool/program.mjs init && node <путь>/tool/program.mjs doctor
• уровень этого репозитория: node tool/program.mjs doctor
• обязательный минимум проекта прогоном: node tool/program.mjs doctor --baseline
• собрать методички одним файлом: node tool/program.mjs blob → GOD_AI.md
• проверить функции программы: node --test tool/selfcheck/units*.mjs
• доказать, что гейты ловят брак: node tool/program.mjs prove
• договор установки инструмента: node tool/program.mjs adopt <гейт> — код 0, только если гейт объявлен, у него есть образцы, он краснеет на красном и идёт в конвейере
• сверить цитаты в сведениях об инструментах с их документацией (нужна сеть): node tool/selfcheck/tools-quotes.mjs
• проверить комплект: bash tool/selfcheck/smoke.sh
• проверить гейты: bash tool/selfcheck/gates.sh
• проверить, что гейт краснеет на КЛАССЕ примеров, а не на одном: bash tool/selfcheck/mutation.sh
• зрелость записей каталога: AQK_LANG=ru node tool/selfcheck/lifecycle.mjs
• только то, что внёс диф: node tool/program.mjs doctor --run --since main
• отчёт по репозиторию: node tool/program.mjs report
• отчёт для человека одной страницей: node tool/program.mjs report --html → .aqk/report.html; doctor --run пишет его сам каждый раз. Закончив работу, покажи его человеку
• состояние репозитория для контекста агента: node tool/program.mjs context — уровень, красные гейты, правила без арбитра, храповики, три следующих шага с готовыми командами и правила «ситуация → команда» (перед коммитом, после правки проверки, когда проверка мешает). Ничего не запускает: читает манифест и .aqk/last-run.md, потому что хук обязан укладываться в секунду. Где не знает — говорит «неизвестно», а не молчит: тишину машина прочитает как «чисто»
• всё целиком — карта команд и свод дословно: node tool/program.mjs context --full (≈7000 токенов против ≈500; решение владельца 2026-09-08, принятое после возражения)
• поставить хук Claude Code: node tool/program.mjs context --install (или --full --install)
• одно задание для агента — что починить, по порядку, и чем доказать: node tool/program.mjs prompt
• отзыв автору комплекта одной командой: node tool/program.mjs feedback — а feedback --send отправит его сам, вашим же gh, комментарием в обсуждение. Без флага наружу не уходит ничего; подмена gh для проверок — AQK_GH — собирает отчёт из последнего прогона и пробы (без путей и без кода) и даёт готовую ссылку. Ничего не отправляет. Просьба об этом печатается ОДИН раз на проект и только при содержании; выключатель AQK_FEEDBACK=0
• подключено ли то, чем комплект работает: node tool/program.mjs vitals — инструменты объявленных гейтов — и первое слово команды, и программа из requires: записи: обёртка начинается с bash, и по нему не видно, чего не хватает, — хук в .git/hooks, состояние агенту, свежесть версии. Четыре состояния: подключено · СЛОМАНО · не подключено и это выбор · посмотреть не смогли. Код возврата роняет только СЛОМАНО
• что сказано вслух и не записано: node tool/program.mjs learn — читает логи Claude Code этого проекта на этой машине, печатает КАНДИДАТОВ в правила. Только в терминал, ничего на диск
• чем доказан диф: node tool/program.mjs report --since main — три состояния у каждого файла: назван проверкой, обойдён молча, не тронут никем. Второе и третье не сливаются: «просмотрен и чист» и «никто не смотрел» по выводу неразличимы, и выдавать одно за другое нельзя
• значок уровня в README: node tool/program.mjs badge — сверить: badge --check
• порог для конвейера: node tool/program.mjs doctor --run --min 1 — --min без --run не проваливается по вине упавших гейтов вообще: тишина неотличима от успеха, тот самый принцип, ради которого весь этот стандарт существует

Чего в этом проекте нет

• есть один посторонний пользователь и один его отзыв (2026-09-08), а не сложившееся пользование. Отзыв нашёл в комплекте два дефекта, невидимых девяноста нашим проверкам, — то есть посторонний работает как арбитр. Но пока за инструментом не вернулись второй раз, утверждения о стандарте практикой не проверены;
• модульными проверками покрыты только чистые функции: разбор манифеста, триггер, выбор рецепта, дедупликация, дописывание гейта. Команды, которые пишут на диск, проверяются прогоном на чистой папке — и то, что в них не покрыто, находится только живым запуском.