Universal Agent Kit. Скачать kit (.zip)Download kit (.zip)Завантажити kit (.zip)

ПрактикаPracticeПрактика Правила, по которым работает агентRules the agent followsПравила, за якими працює агент

Не дать сгенерированному коду сгнитьKeep generated code from rottingНе дати згенерованому коду згнити

docs/CODE_QUALITY.md перечисляет семь шаблонов, которые ИИ-ассистент или уставший человек склонен выдавать и которые тихо гноят кодовую базу. Правило не в том, чтобы «потом проверить на них»: их не пишут с самого начала, а в ревью отмечают с первого взгляда. Каждый шаблон ищется grep'ом, поэтому проверка может быть частью «готово», а не частью «когда-нибудь».docs/CODE_QUALITY.md lists seven patterns that an AI assistant, or a tired human, tends to emit and that quietly rot a codebase. The rule is not "review for these later": it is to not write them in the first place, and to flag them on sight in review. Each pattern is greppable, so the check can be part of "done" rather than part of "someday".docs/CODE_QUALITY.md перелічує сім шаблонів, які ШІ-асистент чи втомлена людина схильні видавати і які тихо гноять кодову базу. Правило не в тому, щоб «потім перевірити на них»: їх не пишуть із самого початку, а в рев'ю позначають з першого погляду. Кожен шаблон шукається grep'ом, тому перевірка може бути частиною «готово», а не частиною «колись».

Когда это нужноWhen to reach for itКоли це потрібно

Вы пишете или ревьюите код вместе с агентом, вводите эти правила в кодовой базе, которая уже нарушает часть из них, либо один и тот же дефект раз за разом всплывает в ревью.You are writing or reviewing code with an agent, you are adopting the rules on a codebase that already breaks some of them, or the same defect keeps turning up in review.Ви пишете чи рев'юїте код разом з агентом, вводите ці правила в кодовій базі, що вже порушує частину з них, або той самий дефект раз у раз спливає в рев'ю.

ТребованияRequirementsВимоги

Где доступноAvailable inДе доступно
Каждая загрузка kitEvery download of the kitКожне завантаження kit
К чему обращаетсяWhat it touchesДо чого звертається
  • Читает файлы проектаReads the files of your projectЧитає файли проєкту
Работает сWorks withПрацює з
Любой агент, который читает и пишет ваши файлыAny agent that reads and writes your filesБудь-який агент, що читає й пише ваші файли
Где выполняются шагиWhere the steps happenДе виконуються кроки
Чат вашего агента и ваши собственные файлы. Ни то ни другое не интерфейс этого сайта, поэтому шаги описаны текстом, а не скриншотами.Your agent's chat and your own files. Neither is an interface of this site, so the steps are text and not screenshots.Чат вашого агента і ваші власні файли. Ні те, ні інше не є інтерфейсом цього сайту, тому кроки описано текстом, а не скриншотами.
Где это лежит в kitWhere it lives in the kitДе це лежить у kit
docs/CODE_QUALITY.md
Прежде чем начатьBefore you startПерш ніж почати

Прежде чем удалять файл, ресурс или ключ, на который ничто не ссылается, убедитесь, что это не временный каркас, на котором держится тикет в работе. А «убрано из сборки» проверяйте на настоящей цели или релизном артефакте, а не на отладочной сборке.Before you delete a file, resource or key that nothing references, check that it is not active scaffolding for an in-flight ticket. And verify "removed from the build" on the real target or release artifact, not on a debug build.Перш ніж видаляти файл, ресурс чи ключ, на який ніщо не посилається, переконайтеся, що це не тимчасові риштування, на яких тримається тікет у роботі. А «прибрано зі збірки» перевіряйте на справжній цілі чи релізному артефакті, а не на налагоджувальній збірці.

ШагиStepsКроки

  1. Положите правило туда, где его читает агент. Раздел 9 файла правил, AGENTS.md, перечисляет запрещённое для любого артефакта и для слоя кода и сообщает, что ревьюер это отмечает; канонический список из семи шаблонов лежит в docs/CODE_QUALITY.md. Подстройте конкретный синтаксис под свой язык: смысл у правил универсальный.Put the rule where the agent reads it. Section 9 of the rules file, AGENTS.md, lists what is forbidden, for any artifact and for the code layer, and says a reviewer flags it; docs/CODE_QUALITY.md holds the canonical list of seven. Adapt the concrete syntax to your language, since the intent is universal.Покладіть правило туди, де його читає агент. Розділ 9 файлу правил, AGENTS.md, перелічує заборонене для будь-якого артефакту й для шару коду та повідомляє, що рев'юер це позначає; канонічний список із семи шаблонів лежить у docs/CODE_QUALITY.md. Підлаштуйте конкретний синтаксис під свою мову: сенс у правил універсальний.
  2. Комментарии и перехваты. Комментируйте «почему», а не «что», и только там, где код сам этого не скажет: неочевидное бизнес-правило, обработанный краевой случай, обходной путь, инвариант. Каждый перехват должен восстановить работу, вернуть документированное безопасное значение или записать в лог деградацию простым языком. Ловите самый узкий тип, а если ошибку действительно игнорируете, объясните почему одним комментарием.Comments and catches. Comment why, not what, and only where the code cannot say it: a non-obvious business rule, a handled edge case, a workaround, an invariant. Every catch must recover, return a documented safe default, or log a plain-language degradation. Catch the narrowest type you can, and if you truly ignore an error, say why in one comment.Коментарі та перехоплення. Коментуйте «чому», а не «що», і лише там, де код сам цього не скаже: неочевидне бізнес-правило, оброблений крайній випадок, обхідний шлях, інваріант. Кожне перехоплення має відновити роботу, повернути документоване безпечне значення або записати в лог деградацію простою мовою. Ловіть найвужчий тип, а якщо помилку справді ігноруєте, поясніть чому одним коментарем.
  3. Значения и логирование. Ссылайтесь на атрибут темы, константу или запись конфигурации вместо вписанного в код цвета, размера, URL или магического числа; если такой записи нет, а значение повторяется, заведите её. Логируйте через фасад проекта (<LOGGER>), а не через print, console.log или System.out в поставляемом коде.Values and logging. Reference the theme attribute, constant or config entry instead of an inlined colour, dimension, URL or magic number; if none exists and the value recurs, create one. Route logging through the project's facade (<LOGGER>), never print, console.log or System.out in shipped code.Значення та логування. Посилайтеся на атрибут теми, константу чи запис конфігурації замість вписаного в код кольору, розміру, URL або магічного числа; якщо такого запису немає, а значення повторюється, заведіть його. Логуйте через фасад проєкту (<LOGGER>), а не через print, console.log чи System.out у поставному коді.
  4. Жизненный цикл и заглушки. Используйте ограниченную область конкурентности проекта и сбор данных с учётом жизненного цикла, а глобальную область не берите только потому, что она короче. Не поставляйте TODO() или raise NotImplementedError на пути, который выполняется: реализуйте его либо закройте так, чтобы до него нельзя было дойти, а пробел заведите тикетом.Lifecycle and stubs. Use the project's scoped concurrency and lifecycle-aware collection, never a global scope because it is shorter. Do not ship TODO() or raise NotImplementedError on a path that runs: implement it, or gate it so it cannot be reached, and track the gap in a ticket.Життєвий цикл і заглушки. Використовуйте обмежену область конкурентності проєкту та збір даних з урахуванням життєвого циклу, а глобальну область не беріть лише тому, що вона коротша. Не постачайте TODO() чи raise NotImplementedError на шляху, що виконується: реалізуйте його або закрийте так, щоб до нього не можна було дійти, а прогалину заведіть тікетом.
  5. Мёртвый груз. В том же изменении, что заменяет код, ресурсы или конфигурацию, удалите старую версию, осиротевший ключ и правило сохранения в сборке, которое называет удалённый символ.Dead weight. In the same change that supersedes code, resources or config, delete the old version, the orphaned key and the build keep-rule that names a deleted symbol.Мертвий вантаж. У тій самій зміні, що замінює код, ресурси чи конфігурацію, видаліть стару версію, осиротілий ключ і правило збереження в збірці, яке називає видалений символ.
  6. Держите дифф на заказанном. Никакого попутного рефакторинга, уборки несвязанных импортов и переформатирования мимоходом: они топят настоящий дифф и ломают git blame. Соблюдайте направление зависимостей из <ARCH_LAYERS>, держите точки входа тонкими, делите файл, переваливший за ~<SIZE_BUDGET> строк, и точно повторяйте существующие имена.Keep the diff on the thing asked. No opportunistic refactor, no unrelated import cleanup, no drive-by reformatting: they drown the real diff and break git blame. Respect the dependency direction of <ARCH_LAYERS>, keep entry points thin, split a file past ~<SIZE_BUDGET> lines, and match the existing naming exactly.Тримайте діф на замовленому. Жодного попутного рефакторингу, прибирання непов'язаних імпортів і переформатування мимохідь: вони топлять справжній діф і ламають git blame. Дотримуйтеся напрямку залежностей з <ARCH_LAYERS>, тримайте точки входу тонкими, діліть файл, що перевалив за ~<SIZE_BUDGET> рядків, і точно повторюйте наявні назви.
  7. В кодовой базе, которая уже нарушает правило, блокируйте только новые нарушения. Зафиксируйте текущее число нарушений как закоммиченную базовую линию: гейт падает, лишь когда число превышает её. Инструмент может снижать базовую линию по мере уборки, но обязан отказываться её поднимать, так что долг движется только вниз, как на храповике.On a codebase that already breaks a rule, gate on new violations only. Freeze the current violation count as a checked-in baseline; the gate fails only when the count rises above it. Tooling may lower the baseline as you clean up but must refuse to raise it, so the debt only ratchets down.У кодовій базі, що вже порушує правило, блокуйте лише нові порушення. Зафіксуйте поточну кількість порушень як закомічену базову лінію: гейт падає, лише коли кількість перевищує її. Інструмент може знижувати базову лінію в міру прибирання, але мусить відмовлятися її піднімати, тож борг рухається лише вниз, як на храповику.
  8. Когда проверка раз за разом ловит один и тот же дефект, закройте источник. Добавьте соответствующий запрет в постоянно загружаемый файл правил, AGENTS.md, и подкрепите его в навыках, которые генерируют код: суть в каноническом правиле, а навыки - короткие ссылки на него. Тогда агент перестанет производить дефект, а не только отмечать его постфактум.When a check keeps catching the same defect, close the source. Add the matching DON'T to the always-loaded rules file, AGENTS.md, and reinforce it in the code-generating skills, with the substance in the canonical rule and the skills as short pointers, so the agent stops producing the defect and not only flagging it afterwards.Коли перевірка раз у раз ловить той самий дефект, закрийте джерело. Додайте відповідну заборону у завжди завантажуваний файл правил, AGENTS.md, і підкріпіть її в навичках, що генерують код: суть у канонічному правилі, а навички - короткі посилання на нього. Тоді агент перестане виробляти дефект, а не лише позначати його постфактум.
Что вы должны увидетьWhat you should seeЩо ви маєте побачити

Дифф без семи шаблонов: комментарии объясняют «почему», перехваты восстанавливают работу, вместо литералов токены, асинхронная работа в ограниченной области, логирование через фасад, никаких заглушек на живых путях и никаких остатков. В устаревшем коде есть закоммиченная базовая линия, которая может только снижаться.A diff without the seven patterns: comments that explain why, catches that recover, tokens instead of literals, scoped async work, logging through the facade, no stubs on live paths and no leftovers. On legacy code, a checked-in baseline count that can only go down.Діф без семи шаблонів: коментарі пояснюють «чому», перехоплення відновлюють роботу, замість літералів токени, асинхронна робота в обмеженій області, логування через фасад, жодних заглушок на живих шляхах і жодних залишків. У застарілому коді є закомічена базова лінія, що може лише знижуватися.

СоветыTipsПоради

  • Базовая линия, привязанная к файлу и строке или к хешу «правило плюс место», заново отмечает уже принятый долг, когда переименование, смена сигнатуры или переформатирование сдвигают якорь. Где инструмент позволяет, берите базовую линию по содержимому или по счёту и принимайте всплывший пункт заново, а не гоняйте код ради гейта.A baseline keyed by file and line, or by a rule-plus-location hash, re-flags debt you already accepted when a rename, a signature change or a reformat moves the anchor. Prefer a content- or count-based baseline where the tool allows it, and re-accept the resurfaced item instead of churning code to satisfy the gate.Базова лінія, прив'язана до файлу й рядка або до хеша «правило плюс місце», заново позначає вже прийнятий борг, коли перейменування, зміна сигнатури чи переформатування зсувають якір. Де інструмент дозволяє, беріть базову лінію за вмістом або за лічбою й приймайте випливлий пункт заново, а не ганяйте код заради гейта.
  • Точечная правка общего контракта - это полправки. Если дефект в том, что код не выполнил требование платформы, API или шаблона, пройдите по всем местам этого контракта в том же тикете: найдите grep'ом интерфейс, аннотацию, базовый класс или ключ схемы.A point fix on a shared contract is half a fix. If the defect is that the code did not pay what the platform, API or template demands, sweep every site of that contract in the same ticket: grep the interface, annotation, base class or schema key.Точкова правка спільного контракту - це пів правки. Якщо дефект у тому, що код не виконав вимогу платформи, API чи шаблону, пройдіть по всіх місцях цього контракту в тому самому тікеті: знайдіть grep'ом інтерфейс, анотацію, базовий клас або ключ схеми.
  • Переопределение, сужающее общее значение по умолчанию, молча отключает механизм: расширение списка добавляет обрабатываемые случаи, сужение убирает те, на которые механизм рассчитывал, и ничего не становится красным, ведь короткий список тоже верен. В измеренном случае очередь пять раз подряд выдала один тикет. Записывайте причину каждого сужающего переопределения.An override that narrows a shared default disables the mechanism silently: widening a list adds cases it handles, narrowing one removes cases it counted on, and nothing goes red because a shorter list is a valid list. In the measured case a queue re-issued one ticket five times in a row. Record a reason for every narrowing override.Перевизначення, що звужує спільне значення за замовчуванням, мовчки вимикає механізм: розширення списку додає випадки, які механізм обробляє, звуження прибирає випадки, на які він розраховував, і ніщо не стає червоним, бо коротший список - теж слушний список. У виміряному випадку черга п'ять разів поспіль видала один і той самий тікет. Записуйте причину для кожного звужувального перевизначення.
  • То, что читает другой проект, имеет один дом и меняется первым. Формат, полезная нагрузка или поведение, от которых зависит второй проект, живут в одном месте вне обоих; каждый проект хранит указатель, а не копию. Сначала версия и датированная заметка, потом код. Нашли в контракте ошибку: исправьте её в доме или запишите датированное исключение со сроком; локальный обход - ни то, ни другое.What another project reads has one home, and it changes first. A format, payload or behaviour a second project depends on lives in one place outside both; each project keeps a pointer, never a copy. Bump the version and add a dated note before the code. If you find the contract wrong, amend it at the home or record a dated exception with an expiry date; a local workaround is neither.Те, що читає інший проєкт, має один дім і змінюється першим. Формат, корисне навантаження чи поведінка, від яких залежить другий проєкт, живуть в одному місці поза обома; кожен проєкт тримає покажчик, а не копію. Спершу версія й датована нотатка, потім код. Знайшли в контракті помилку: виправте її в домі або запишіть датований виняток зі строком; локальний обхід - ні те, ні інше.
  • Ломающее изменение определяйте по самому старому читателю в ходу, а не по размеру диффа: если он на новом выводе поведёт себя неверно, молча или частично, изменение ломающее, нужна новая мажорная версия, объявленная до выпуска. Читатель сопоставляет поля по имени, игнорирует неизвестные, пропускает добавки новой минорной версии и чисто отказывает на новой мажорной, называя контракт.Judge a breaking change by the oldest reader still in use, never by diff size: if that reader would act wrongly, silently or partially on the new output, it is breaking, so a new major version, announced before it ships. A reader matches fields by name, ignores unknown fields, skips a newer minor version's additions and refuses a newer major version cleanly, naming the contract.Несумісну зміну визначайте за найстарішим читачем в ужитку, а не за розміром діфа: якщо він на новому виводі поведеться хибно, мовчки чи частково, зміна несумісна, потрібна нова мажорна версія, оголошена до випуску. Читач зіставляє поля за назвою, ігнорує невідомі, пропускає додатки нової мінорної версії й чисто відмовляє на новій мажорній, називаючи контракт.
  • Пользовательские справочные документы принадлежат изменению, которое меняет поведение, а не последующей доработке. Если стек умеет порождать документ из источника истины, блокируйте по перегенерированному результату; иначе блокируйте по тому, что документ тронут всякий раз, когда тронуто соответствующее поведение, и держите зеркальные документы в лад.User-facing reference docs belong to the change that alters behaviour, not to a follow-up. Where the stack can generate the doc from the source of truth, gate on the regenerated output; otherwise gate that the doc was touched whenever the matching behaviour was, and keep mirrored docs in lockstep.Користувацькі довідкові документи належать зміні, що змінює поведінку, а не подальшому доопрацюванню. Якщо стек уміє породжувати документ із джерела істини, блокуйте за перегенерованим результатом; інакше блокуйте за тим, що документ зачеплено щоразу, коли зачеплено відповідну поведінку, і тримайте дзеркальні документи в ладу.
  • Если в вашем стеке есть линтер, закодируйте как можно больше из семи шаблонов правилами: тогда гейт срабатывает сам, а ассистент быстро получает обратную связь.If your stack has a linter, encode as many of the seven as rules, so the gate is automatic and the assistant gets fast feedback.Якщо у вашому стеку є лінтер, закодуйте якомога більше з семи шаблонів правилами: тоді гейт спрацьовує сам, а асистент швидко отримує зворотний зв'язок.
  • Эти семь относятся к слою кода. У документов, датасетов, контрактов и процедур есть свои аналоги: см. формы проектов и составьте собственный список из того, что вы реально поймали в ревью.The seven are the code layer. For documents, datasets, contracts or procedures they have analogues: see project shapes, and write your own list from what you actually caught in review.Ці сім належать до шару коду. У документів, датасетів, контрактів і процедур є свої аналоги: див. форми проєктів і складіть власний список із того, що ви справді впіймали в рев'ю.

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

Поиск по порталуSearch the portalПошук по порталу