Дай своему ИИ-агенту операционную систему Give your AI agent an operating system Дай своєму ШІ-агенту операційну систему

ИИ-ассистент быстрый, но дрейфует. Он угадывает пути к файлам, придумывает API, который изменился две версии назад, пишет правдоподобный мусор, который компилируется и тихо гниёт, забывает всё между сессиями и либо спрашивает разрешения на каждый чих, либо молча делает не то. По сути - гениальный стажёр с амнезией: печатает быстрее тебя, но к обеду уже не помнит, как тебя зовут.

Помогает не очередной инструмент, а простой порядок работы: короткие правила, готовые сценарии для частых задач и несколько полезных заметок. Он просит агента сначала разобраться, а потом менять файлы; говорить, когда чего-то не знает; и сохранять важный контекст между сессиями.

Здесь показано, из чего всё состоит. Метод вырос из реального проекта, но не привязан к языку, модели или инструменту. Скачай kit и положи его рядом со своим проектом - хоть это личная папка на компьютере без Git, хоть рабочий репозиторий.

Кому это всё

• Тем, кто уже живёт с ИИ-агентом и устал в третий раз объяснять одно и то же.
• Тем, кто хочет, чтобы агент проверял, а не угадывал - и сам признавался, где не уверен.
• Тем, кто делает личный проект в локальной папке, соло-разработчикам и маленьким командам: порядок работы вместо набора привычек в голове одного человека.
• Не только программистам. Если ваша работа - это файлы, которые кто-то потом читает (аналитика, документация, договоры, регламенты), метод ложится целиком, кроме слоя про код. Раздел 02 переводит его словарь на пять видов проектов и честно говорит, где границы.
• Любому стеку и почти любому инструменту. Claude Code - из коробки; Cursor, Cline, Codex, Aider - с лёгкой адаптацией.

Чего тут нет - серебряной пули. Метод не делает агента умнее; он лишь мешает ему выстрелить себе в ногу и тут же забыть, что нога была.

И где он кусается. У метода свои острые края: навесишь церемонию на правку в одну строку - сам себе придумал работу; устаревший индекс или карта сбивает с пути хуже, чем их отсутствие; параллельные писатели тихо затирают друг друга; память гниёт, когда её никто не подрезает. Почти всё это - провалы избытка метода, а не нехватки: лекарство - самая нижняя ступень, которая доказывает изменение, и уход за индексами и памятью, которые ты держишь.

Метод вырос из разработки, и примеры в нём острее всего именно там. Но держится он не на компиляторе, а на пяти вещах: рабочая папка с историей, артефакты - то, что работа производит и кто-то потом читает, единицы работы с честным статусом, проверки - вопрос к артефакту, на который отвечают без чьего-либо мнения, - и агент, который умеет читать и писать ваши файлы. Есть четыре из пяти - метод работает, и дырку вы почувствуете ровно там, где должна была быть пятая.

Ниже - словарь метода на пяти видах проектов. Вся остальная статья написана в первой колонке; найдите свою и читайте через неё.

И что стоит удалить, а не приспосабливать. Правило, оставленное «на всякий случай» в проекте, к которому оно неприменимо, - это шум, который приучает всех пролистывать. Если у вас ничто ничего не импортирует, удалите слои и направление зависимостей. Если ваши артефакты не оставляют следа выполнения, удалите метки верификации. Ступень «компиляция» просто исчезает, и лестница проверок начинается на одну выше. Полная таблица перевода, вместе с честными границами метода, лежит в ките: docs/PROJECT_SHAPES.md.

Где метод честно не поможет: там, где механически не проверить вообще ничего, он вырождается в чек-лист с хорошими манерами - разделение «что» и «как», статус из реальности и запрет на слово «должно работать» остаются, но принуждения больше нет. Там, где артефакт - один сплошной документ с одним автором, тикет-машинерия это накладные расходы: возьмите правила, /quick, /fix и память. А там, где работа вообще не в файлах - разговор, переговоры, решение, которое нигде не записано, - методу сказать нечего. Запишите сначала; тогда это станет проектом.

В портале: Внедрение и адаптация

Это один короткий файл, который агент читает в начале работы. В нём: как с тобой общаться, где искать код, как проверять результат и когда спрашивать, а не угадывать. Остальные материалы могут ссылаться на него.

Главное - держать его коротким. Это не энциклопедия: подробности лежат в docs/, а здесь только нужные ориентиры и подсказка, какой готовый промпт выбрать для задачи. В kit'е это AGENTS.md: его читает большинство инструментов, а CLAUDE.md у Claude Code лишь подключает его. Где нужно своё имя - правило Cursor, GEMINI.md - суть та же.

Плейсхолдеров в нём два яруса: десять нужны любому проекту (включая тот самый <CHECK_CMD> - команду, которая доказывает, что правка не сломана), и шесть - только тем, что собираются или запускаются. Если ваш не собирается, правила с этими шестью удаляются, а не заполняются наугад.

В портале: Правила, по которым работает агент

Навык - это сохранённый промпт для повторяющейся задачи. Пишешь /spec - и агент следует понятному сценарию, а не каждый раз придумывает его заново. Если в твоём инструменте нет slash-команд, это может быть обычный текстовый файл, который ты прикладываешь или на который ссылаешься.

Основной набор ведёт идею к готовому и проверенному результату:

/research   собрать доказательства, сохранить       (до всего нетривиального)
/spec       стратегическое что/зачем                Draft → Approved
/spec-tech  фазовый проверяемый план                Approved → Tactical
/spec-dev   выполнять по шагу, проверять каждый      Tactical → Implemented
/spec-check аудит против спеки                       → Verified / Partial / Broken
/spec-fix   механический ремонт после аудита         Partial / Broken → переаудит
/spec-all   прогнать весь пайплайн целиком           idea → verified

$ /spec-check T0207
T0207: auditing the strategic spec + 3 phases against the repo..
  PASS    file exists          export/CsvWriter
  PASS    symbol declared      writeRows(rows)
  PASS    no forbidden call    grep raw-logger -> 0 hits
  WARN    dead weight          old ExportHelper still wired in the container
  MANUAL  export writes a valid file on a real run
  PASS    changelog            an entry for every touched file
verdict: BlockNeedUserTest     (PASS 6 / WARN 1 / FAIL 0)
  was "Implemented" -> downgraded: the build is sound, but the headline
  behaviour is unproven until a human runs the export once.
  next -> /spec-fix drops the orphaned ExportHelper binding, then re-audits.

Под пайплайном - дешёвые пути: /quick (опечатка), /fix (узкий баг). Перед всем пользовательским - /ui-clarify. Для краткости - /caveman. Плюс /git, /prove, /critique.

Рядом с пайплайном, но не внутри него, живут две дисциплины:

• Паркуй, не гоняйся (/park). Наткнулся посреди задачи на реальную проблему вне рамок задачи - крупнее правки в одну строку, требует отдельного взгляда? Запиши её заглушкой, отсей дубликаты против уже заведённого, отчитайся одной строкой и вернись к задаче. Никогда не переключай активную задачу, чтобы гоняться за припаркованной находкой; тривиальное чини на месте, косметические придирки выбрасывай.
• Разгребай бэклог (/backlog). Автопилот по бэклогу: бери тикет с наивысшим приоритетом из подходящих, гоняй пайплайн, повторяй - пока не останется ничего, что агент может продвинуть сам. Две защиты не дают ему сорваться: skip-кэш, чтобы непродвигаемый тикет не выбирался снова на следующем витке, и никаких вопросов посреди цикла - каждый требующий человека тикет попадает в один отчёт по итогу прогона.

И правило для самих вопросов к человеку: отсортируй развилку, прежде чем выносить её. Если её решает внешняя конвенция - исследуй её и рекомендуй; если её решает архитектура - изложи это как производное следствие. Реальные вопросы оставь для продуктовых решений, вкуса без опоры и необратимых действий. «Лучше спросить, чем угадывать» не работает, когда исследование или код уже отвечают - вынести решённую развилку как выбор значит расписаться в том, что не проработал вопрос.

В портале: Навыки: сценарии как slash-команды

Это дополнительные помощники с узкой задачей. Один ведёт работу от запроса до проверки, другой только изучает проект и пишет выводы, третий вносит изменения по плану, четвёртый занимается текстами для людей. Они полезны для больших задач; в небольшом личном проекте можно обойтись и одним агентом.

• Зачем ограничивать инструменты: ресёрчер, который не умеет писать, не испортит файлы случайно.
• Параллелизм: несколько агентов одновременно копают независимые вопросы - локальный код и внешние доки в один заход.
• Каждому - своя память: заметки ресёрчера не засоряют индекс имплементера.

Параллелизм - чистый выигрыш для читателей; параллельные писатели требуют осторожности:

• Писатели затирают друг друга через общее VCS-состояние. Операция одного агента над всем деревом - stash, checkout, reset, restore - откатывает незакоммиченные правки всех остальных писателей, даже по непересекающимся файлам. VCS и сборка между волнами - на оркестраторе, либо у каждого писателя свой checkout.
• Отчёт субагента - это утверждение, а не вердикт. Перепроверяй из собственного чистого состояния оркестратора. Сообщённый отказ часто - фантом устаревшей инкрементальной сборки; сообщённое «компилируется в изоляции» так же не доказано.
• У делегирования есть перекос к хвосту. Субагент тратит бюджет на тяжёлые ранние фазы и обрезает последнюю - доки, проводку, чистку, - а в отчёте пишет «готово». Проверь, что каждый артефакт существует и запускается.
• Изоляция - ещё и рычаг бюджета: гоняй задачу с громоздкими доказательствами в одноразовом агенте, который возвращает один компактный вердикт, - артефакты остаются в дочернем.

В портале: Ролевые агенты

Для заметной задачи полезно записать две разные вещи, не смешивая их:

• Что и зачем: проблема, цель, ограничения и открытые вопросы. Без технических деталей. Если идея не подходит, это станет ясно до лишней работы.
• Как сделать: какие файлы менять, в каком порядке и как проверить результат. Если следующий шаг неясен, агент спрашивает, а не угадывает.

Draft ─► Approved ─► Tactical ─► In Progress ─► Implemented ─► Verified
   │                                                │
   └─ черновик может быть сырым                     └─ аудит может дать вместо этого:
                                                       Partial (предупреждения)
                                                       Broken  (есть отказ)
плюс явные блок-статусы: BlockNeedUserTest, BlockQuestions, BlockExternal, ..

Перед фазами - гейт сложности - градуированная лестница, а не выключатель. Опечатка - это /quick; узкий баг - /fix; мелкая детерминированная правка (≤3 файлов, без новых публичных типов, без миграций и DI) идёт как примитив в три секции; всё остальное - полный пайплайн. Бери самую нижнюю ступень, которая всё ещё доказывает изменение, - и церемония останется пропорциональна работе.

Граф фаз проектируется тремя проходами: инвентарь покрытия (каждая цель ложится в фазу или помечается как вне рамок), топология «производит/потребляет» (ни одна фаза не потребляет то, что произведёт более поздняя), фильтр реальной работы (шаг меняет код, а не текст плана). Каждый шаг кончается статической проверкой.

Статус - из реальности, и это бьёт уже на входе: тикет доходит до «ожидает теста» только когда его основное поведение уже работает от начала до конца. Скомпилированный каркас, который лишь логирует или показывает заглушку, - это веха, а не результат: не зови человека тестировать пустышку.

У блок-статусов есть определённый выход, а не только вход: разблокируй тикет, застрявший на вопросе, решив то, что код уже определяет, спрашивая владельца только о настоящих суждениях (с исследованным дефолтом) и продвигая на один уровень. И жизненный цикл где-то кончается - мягкое удаление Archived убирает отменённый тикет из активного набора, но сохраняет его запись, так что ничто не удаляется жёстко.

Защиты делятся по тому, что они проверяют: механический инвариант жёстко стопорит; суждение лишь информирует и оставляет go/no-go агенту - жёсткая блокировка на эвристике лишь плодит обходы. А деструктивный шаг, который план уже подстраховывает, - не повод выдумывать гейт подтверждения.

В портале: Жизненный цикл спеки

Рантайм забывает всё между сессиями. Код, спеки и git остаются - а вот как ты любишь работать, почему прошлое решение было таким и какие правки ты уже давал - нет. Переучивать это каждую сессию - главный скрытый налог: как каждое утро заново знакомиться с коллегой, который вчера с тобой переписал полпроекта.

Лечение - маленькая файловая память в memory/ под контролем версий: всегда загруженный индекс MEMORY.md плюс по файлу на запись. Четыре типа:

user       кто человек: роль, опыт, что уже знает    → как объяснять
feedback   как работать здесь - из правок И похвал    → не повторять подсказку дважды
project    живой контекст: кто, что, зачем, к сроку    → быстро устаревает
reference  указатель во внешнюю систему и зачем        → где искать

Тонкость - сдержанность. Не храни то, что выводится из репозитория, git-истории или рецепты починки - это уже в коде и коммитах. И проверяй перед советом: память, называющая функцию или путь, - это утверждение «так было, когда записали». Перед действием - грепни, существует ли оно сейчас.

Долговечная память - для фактов, которые стоит хранить; промежуточное состояние одной прерванной задачи - нет, держи их раздельно. Для задачи, которая переживает перерыв, обрамляй её: на каждой границе фазы пиши короткую передачу (цель, что изменилось, решения, открытые блокеры, единственный следующий шаг), а при возобновлении читай последнюю передачу, прежде чем что-то трогать.

Одна оговорка, которую прячет слово «постоянный»: авторитет того, что сделано сейчас, - рабочее дерево, а не git-история. git log, blame и diff отвечают на «как мы сюда пришли» и активно вводят в заблуждение, когда один файл несёт сразу несколько задач. Возобновляй, читая живые файлы, потом правь трекеры - никогда не выводи текущее состояние из диффа.

В портале: Постоянная память

Самое дорогое, что делает ассистент, - угадывает. Догадка выглядит как прогресс и стоит целой неверной реализации. Лекарство - фиксированный порядок поиска: карта → спека → индекс кода/греп → код → внешние доки. Останавливаешься, как только источник ответил.

Одно правило под всем: если ты назвал путь, символ или API - ты их проверил. Для большого репозитория держат запрашиваемый индекс единиц кода: спрашиваешь индекс до грепа и регенерируешь его после правок. Устаревший индекс хуже отсутствующего.

Две дешёвые защиты расширяют порядок. Держи инвентарь того, что проект уже умеет - запрашиваемый список возможностей - и просматривай его, прежде чем проектировать фичу, чтобы агент не пересобирал под новым именем то, что уже существует. И сама карта - артефакт, который ты ведёшь: указатель «фича → местоположение». Держи его в согласии со структурой, которую он описывает, и назначь ответственного за свежесть - та же дисциплина, что и у индекса кода.

Одно уточнение к «проверяй, не угадывай»: имя - это не поведение. Прежде чем рассуждать, что флаг или константа делает, подтверди живое место чтения/вызова - комментарий или упоминание в доках это попадание, а не использование. Символы умирают, переименовываются по смыслу или вообще не подключаются.

В портале: Постоянная память

Шаг не сделан, когда ты хотел, чтобы он работал. Он сделан, когда проверка прошла в этом прогоне. Уровень доказательства подбирается под тип изменения:

греп  <  запуск скрипта  <  компиляция  <  точечный тест  <  полная сборка  <  запуск-и-наблюдение
док        скрипт            правка типов     логика           конфиг/ресурсы      пользовательское поведение

Бери самую нижнюю ступень, которая реально доказывает это изменение, и не выше. Для каждой проверки записывай ожидал: X | получил: Y - предсказание до чтения результата ловит проверку, которая вернула 0, но напечатала не то. «Работает на моей машине» - не ступень этой лестницы, а суеверие.

Два режима отказа, которые одна лестница не ловит. «Готово» лучше всего как одна fail-closed команда, которая собирает проверки под тип изменения, - любой провалившийся гейт обрывает весь прогон с ненулевым кодом, так что «закончено» означает «все применимые гейты прошли», а не «я их все вспомнил». И зелёное может врать: когда команды сцеплены, в пайпе или ушли в фон, агрегатный код выхода часто отражает хвостовую обёртку, а не ту сборку или тест, что тебе важны. Читай конкретную строку вердикта - проверка, прошедшая по неверной причине, хуже отсутствия проверки.

У проверки четыре ответа, а не два. «Прошло» и «нашла дефект» очевидны; третий - не смогла проверить, четвёртый - неприменимо в этой конфигурации. Проверка, которая не умеет сказать последние два, скажет один из первых двух, и с этого момента она врёт. Отсюда два следствия. Первое: сначала проверяй прибор, а потом предмет - физически невозможное показание означает, что сломан измеритель, а не подопытный (на одном прогоне так родились 5 «дефектов» из 5 и 18 «недостижимых» пунктов из 28, все ложные). Второе: ложная находка стоит столько же, сколько пропущенная, но громче - когда ложных восемнадцать, настоящая становится одной строкой среди них, и отчёт перестают читать.

Перед необратимым шагом - релизом, публикацией, подачей, отправкой - письменный вердикт это вход этого шага, а не отчёт где-то рядом. Отсутствие вердикта не считается за «прошло», и ломается этот гейт ровно так: никто не нарушил правило, ничего не покраснело, а месяцы уехали непроверенными. Вердикт обязан называть, что именно он оценивал (вердикт от прошлого раза - ровно то, за чем тянется рука в спешке), и висеть на той команде, которая отгружает, а не на соседней: в одном проекте гейт существовал, работал и был описан, а в инструкции по релизу его имя встречалось ноль раз.

Веди журнал на уровне логического изменения, а не тронутого файла: одна запись на изменение с пакетом его файлов, и любой индекс регенерируй раз на изменение, а не раз на правку. Предоставленный сам себе, агент пишет пофайловый шум, который хоронит сюжет.

В портале: Правила, по которым работает агент

Семь паттернов, которые ИИ (и уставший человек) выдаёт легко, а они выглядят нормально и тихо гниют - как забытый в глубине холодильника контейнер: снаружи порядок, пока не откроешь. Правило - не писать их с самого начала и ловить на ревью. Все семь - греп-проверяемые:

Каждый можно механически просканировать в диффе. Сделай проверку частью «готово», а не «когда-нибудь». Если в стеке есть линтер - закодируй паттерны как правила, чтобы гейт был автоматическим.

Две вещи замыкают петлю. Первое: как внедрить правило на коде, который его уже нарушает? Ставь гейт на новые нарушения, а не на все: заморозь сегодняшнее число как закоммиченную базовую линию, проваливай только при росте и дай базовой линии опускаться по мере уборки, как трещотке, - но не подниматься. Правило кусает сразу, без уборки большим взрывом. Это и есть недостающее звено между «закодируй паттерн» и реальной легаси-базой.

Второе: детектор - лишь половина починки. Линтер останавливает человека один раз; агент переиздаёт тот же паттерн каждое поколение. Так что закрой источник - добавь соответствующий DON'T во всегда загруженный свод правил и подкрепи его в навыках, генерирующих код, чтобы агент перестал производить дефект, а не просто помечал его постфактум.

И отдельно - то, что читает другой проект, живёт в одном месте и меняется первым. Формат файла, выгрузка, константы алгоритма, от которых зависит соседний проект, - это контракт между проектами. Он лежит в одном месте вне обоих, а каждый проект держит только указатель, не копию: копия расходится с оригиналом после первой же правки. Сначала контракт (новая версия и датированная запись), потом код; не согласен - исправь контракт или запиши исключение с датой окончания. Тихого дрейфа не бывает.

Пользовательские доки - часть изменения, которое меняет поведение, а не довесок: то же изменение обновляет док, и проверка проваливается, когда поведение и его описание расходятся. Держи пополняемый (append-only) лог «что выпущено» отдельно от выверенной сводки, которую регенерируешь на релизе.

В портале: Правила, по которым работает агент

Метод не привязан ни к инструменту, ни к модели. Ниже три ситуации - выбери свою.

A · Новый или почти пустой проект

Сначала дай агенту собрать карту кода его штатной командой - /init в Claude Code (или аналог в твоём инструменте). Потом отдай этот промпт, чтобы он поднял проект сразу по методу:

This is a fresh or mostly empty project folder. It may be a personal local
project without Git. First run your codebase-init
command (/init in Claude Code, or the equivalent in your tool) so you have a
rules file and a basic map of the project. Then download
https://github.com/SerZhyAle/universal-agent-kit/raw/main/universal-agent-kit.zip
into a temp or scratch directory and unpack it locally; it extracts to a
`universal-agent-kit/` folder that contains `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
read `universal-agent-kit/docs/PROJECT_SHAPES.md` to see which rules apply to work
like mine, then use `universal-agent-kit/AGENTS.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`,
`universal-agent-kit/examples/` (to see a filled result), and
`universal-agent-kit/merge-prompt.txt`. Do not use the article page as the
primary source. If you
cannot download files in this environment, stop and ask me to place the
archive in the workspace. Set this project up on the method from those files:

1. Write the rules file my tool reads (AGENTS.md; CLAUDE.md only imports it for
   Claude Code / a Cursor rule / GEMINI.md - whatever applies) adopting the kit's structure: communication,
   research order, skill routing, the spec lifecycle, strict rules, anti-slop,
   post-change discipline. Fill in what already exists; use sensible defaults
   otherwise.
2. Create the skill files and the role briefs from the kit that fit a
   project of this kind.
3. Set up the plan directory, the scratch directory, and the memory folder with
   its index.
4. Name THE CHECK COMMAND that proves a change is sound here. If this project is code,
   also pick the build / test / lint / run commands for the stack I name - or propose
   a stack if none exists yet.

Show me the plan first; create nothing until I approve.

B · Существующий или личный локальный проект

За минуту. Подходит, если проект уже есть - даже если это просто папка на твоём компьютере без Git. Попроси агента скачать архив, распаковать его рядом с проектом и выбрать самое полезное:

Download
https://github.com/SerZhyAle/universal-agent-kit/raw/main/universal-agent-kit.zip
into a temp or scratch directory and unpack it locally; it extracts to a
`universal-agent-kit/` folder that contains `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
read `universal-agent-kit/docs/PROJECT_SHAPES.md` to see which rules apply to work
like mine, then use `universal-agent-kit/AGENTS.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`,
`universal-agent-kit/examples/` (to see a filled result), and
`universal-agent-kit/merge-prompt.txt`. Do not use the article page as the
primary source. If you
cannot download files in this environment, stop and ask me to place the
archive in the workspace.

Then study THIS project folder and import what fits it. It may be a local personal
project without Git; do not require Git or create a repository:

1. Draft an AGENTS.md (or merge into my existing rules file) that adopts the method, with every
   tier-1 placeholder filled from this project: project name, chat language, artifact language,
   map document, work root, THE CHECK COMMAND that proves a change is sound, plan directory,
   scratch directory, size budget, read-only zones, and a simple way to name tasks (the ticket-id
   scheme). Fill the code-layer ones
   (architecture layers, build / test / lint / run, logger) only if this project builds or runs.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /prove, /critique) and which role agents are worth adding here, and say why.
   Consider /git only if this project already uses Git.
3. Tell me whether my runtime supports persistent agent memory and, if so, how to wire it up.

Do not change anything yet. Show me the plan first; on any conflict, my existing files win.

Быстрый способ начать. Агент сначала покажет план и ничего не изменит без твоего подтверждения.

C · Существующий проект - подробный путь

Скачай kit, отдай агенту папку вместе с merge-prompt.txt и скажи: «Добавь Universal Agent Kit в мой проект». Это работает и с обычной локальной папкой. Агент сначала составит список: что уже есть, что можно добавить и где возможен конфликт. Затем покажет план и остановится: ничего не перезаписывается молча. После твоего подтверждения он внесёт выбранные части и заполнит <PLACEHOLDER> по материалам проекта.

Любой инструмент

Две из трёх частей теперь переезжают сами: файл правил - это AGENTS.md, который нативно читает большинство агентских инструментов, а навыки лежат в открытом формате Agent Skills (папка с SKILL.md). Адаптации требуют только агенты-роли. Каждый инструмент называет папки по-своему:

• Claude Code - CLAUDE.md (подключает AGENTS.md) + .claude/skills/* (готовые /spec, /research..) + .claude/agents/* как субагенты.
• Codex, Cursor, Copilot, Gemini CLI, Cline, Windsurf - AGENTS.md как файл правил (у Gemini CLI - GEMINI.md или AGENTS.md, названный в настройках); навыки - в собственной папке навыков инструмента или в .claude/skills/, где инструмент её читает; роли вставляются как системные промпты, режимы или пресеты. Точные папки - в таблице README.md внутри kit'а.
• Методология в docs/ вообще не зависит от инструмента - это просто Markdown.

Любая модель - от сильной до слабой

Метод не зависит и от мощности модели - меняется не он, а несколько ручек:

• Сильная (фронтир, большой контекст): держит больше в голове. Шаги крупнее, автономии больше; спеки и проверки оставляешь ради корректности, а не чтобы вести за руку.
• Средняя: золотая середина метода - спеки, мелкие проверяемые шаги и порядок исследования окупаются максимально.
• Слабая, маленькая или локальная: опираешься на правила сильнее всего - крошечные шаги, проверка после каждого, короткий контекст, меньше автономии. Метод - это то, что вообще делает слабую модель пригодной для работы.

В портале: Внедрение и адаптация

Этот kit - не единственная истина, а один связный набор привычек. Сами привычки общие - их же советуют команды, которые эти инструменты и делают:

• Держи контекст коротким. Окно контекста забивается быстро, и качество падает по мере заполнения. Между несвязанными задачами начинай свежий чат.
• Сначала план, потом код. Попроси подход и план, утверди - и только потом разрешай править файлы.
• Два агента в петле. Один пишет, другой ревьюит или гоняет тесты; либо сначала тесты, потом код до зелёного.
• Делай точки возврата. С Git это коммит до и после задачи. Без Git - копия изменяемых файлов или папки проекта, чтобы можно было спокойно отменить неудачный эксперимент.
• Если используешь Git - работай в отдельной ветке. Перед правками проверь, где находишься, и не коммить прямо в защищённую или основную ветку.
• Записывай повторяемое. Часто повторяемый промпт сохрани в команду или файл правил. В команде положи его в общий проект; в личной папке он просто останется рядом с кодом.
• Скриптуй релиз. Зашей версию один раз в каждый артефакт - тег, заметки, сборку, - чтобы они не разъехались; пиши заметки к релизу из выверенного списка видимых пользователю изменений, а не из сырого лога коммитов.
• Читай дифф. Агент быстрый, но не непогрешимый - не вливай то, что сам не прочитал.

Kit превращает эти советы из «хорошо бы» в записанный процесс. Первоисточники стоит прочитать целиком:

Официальные гайды «ИИ для разработки»

• Anthropic · Claude: Claude Code best practices · Effective context engineering
• OpenAI · Codex: Codex docs и quickstart
• Google · Antigravity: antigravity.google · Docs (агентная IDE от Google)

Ссылки ведут на официальные ресурсы вендоров и открываются в новой вкладке. Метод из этой статьи работает поверх любого из этих инструментов.

Держи его живым. Метод требует ухода: регенерируй индекс после изменений, подрезай память, которая устарела, опускай базовые линии трещотки по мере уборки и пересматривай маршруты навыков по мере роста проекта. Запущенный индекс или память хуже, чем их отсутствие, - заложи немного ухода, иначе kit потихоньку начнёт тебе врать.

Адаптировано из .claude/-сетапа реального Android-проекта FastMediaSorter. Android-, PowerShell- и локаль-специфичная машинерия удалена; переносимый метод оставлен и переписан нейтрально. С тех пор это же ядро сверено с остальным портфелем автора - Android-приложение, десктопные приложения для Windows, Go-утилиты командной строки, браузерное расширение - и в kit вошли правила, пережившие все эти формы. Исходного кода и проприетарного содержимого здесь нет - только рабочий метод.

Kit - под MIT. Текст этой статьи - под CC BY 4.0. Бери, ремиксуй, адаптируй под свои проекты.

An AI assistant is fast, but it drifts. It guesses file paths, invents an API that changed two versions ago, writes plausible slop that compiles and quietly rots, forgets everything between sessions, and either asks permission for every keystroke or silently does the wrong thing. Essentially a brilliant intern with amnesia: types faster than you, but by lunch can't recall your name.

What helps is not another tool, but a simple way of working: short rules, ready-made flows for common tasks, and a few useful notes. It asks the agent to understand first, then change files; to say when it is unsure; and to keep important context between sessions.

This page shows what is inside. The method grew out of a real project, but is not tied to a language, model, or tool. Download the kit and place it next to your project - whether that is a personal folder on your computer without Git or a shared repository.

Who it's for

• Anyone already living with an AI agent and tired of explaining the same thing a third time.
• Anyone who wants the agent to verify, not guess - and to admit where it isn't sure.
• People building a personal project in a local folder, solo developers, and small teams: a working routine instead of habits that live in one person's head.
• Not only programmers. If your work is files someone later reads - analysis, documentation, contracts, procedures - the method fits in full, minus the code layer. Section 02 translates its vocabulary into five kinds of project and says plainly where the limits are.
• Any stack, almost any tool. Claude Code works out of the box; Cursor, Cline, Codex, Aider take light adaptation.

What it isn't - a silver bullet. The method doesn't make the agent smarter; it just keeps it from shooting itself in the foot and forgetting it had one.

And where it bites. The method has sharp edges of its own: pile ceremony onto a one-line change and you've made work; a stale index or map misdirects worse than none; parallel writers quietly clobber each other; memory rots when no one prunes it. Most of these are failures of too much method, not too little - the fix is the lowest rung that proves the change, and tending the indexes and memory you keep.

The method grew out of software work, and that is where its examples are sharpest. What it rests on is not a compiler but five things: a workspace with history, artifacts - what the work produces and someone later reads, work items with an honest status, checks - a question about an artifact that gets answered without anyone's opinion - and an agent that can read and write your files. With four of the five it still works, and you will feel the gap exactly where the fifth should have been.

Below is the method's vocabulary in five kinds of project. The rest of the article is written in the first column; find yours and read through it.

And what to delete rather than adapt. A rule kept "just in case" on a project it cannot apply to is noise, and noise trains everyone to skim. If nothing here imports anything, delete the layering and the dependency direction. If your artifacts leave no execution trace, delete the verification tags. The compile rung simply disappears and your ladder starts one rung higher. The full translation table, with the method's honest limits, ships in the kit: docs/PROJECT_SHAPES.md.

Where it honestly will not help: where nothing at all can be checked mechanically it degrades into a checklist with good manners - the what/how split, status from reality and the ban on "should work" all survive, but the enforcement is gone. Where the artifact is one flowing document with one author, the ticket machinery is overhead: take the rules, /quick, /fix and the memory. And where the work is not files at all - a conversation, a negotiation, a decision nobody wrote down - the method has nothing to say. Write it down first; then it is a project.

In the portal: Adopt and adapt

This is one short file the agent reads at the start of work. It says how to communicate with you, where to look for code, how to check results, and when to ask rather than guess. Other materials can point to it.

The important part is to keep it short. It is not an encyclopedia: details live in docs/, while this file has only the essentials and a hint about which ready-made prompt to use. In the kit it is AGENTS.md, which most tools read; Claude Code's CLAUDE.md only imports it. Where a tool wants its own name - a Cursor rule, GEMINI.md - the purpose is the same.

Its placeholders come in two tiers: ten that any project needs (including <CHECK_CMD> - the command that proves a change is sound), and six only for projects that build or run. If yours does not, the rules using those six get deleted rather than filled with guesses.

In the portal: Rules the agent follows

A skill is a reusable prompt that encodes a workflow. Type /spec and the assistant follows a written procedure instead of improvising it again. The good procedure is written down once, not re-derived each time. In tools without slash commands, the same skill is a prompt file you point at.

The spine is a pipeline that carries an idea to verified code:

/research   gather evidence, persist it             (before anything non-trivial)
/spec       the strategic what/why                  Draft → Approved
/spec-tech  a phased, verifiable plan               Approved → Tactical
/spec-dev   execute one step, check each            Tactical → Implemented
/spec-check audit the build against the spec        → Verified / Partial / Broken
/spec-fix   mechanical repair after an audit        Partial / Broken → re-audit
/spec-all   drive the whole pipeline at once        idea → verified

$ /spec-check T0207
T0207: auditing the strategic spec + 3 phases against the repo..
  PASS    file exists          export/CsvWriter
  PASS    symbol declared      writeRows(rows)
  PASS    no forbidden call    grep raw-logger -> 0 hits
  WARN    dead weight          old ExportHelper still wired in the container
  MANUAL  export writes a valid file on a real run
  PASS    changelog            an entry for every touched file
verdict: BlockNeedUserTest     (PASS 6 / WARN 1 / FAIL 0)
  was "Implemented" -> downgraded: the build is sound, but the headline
  behaviour is unproven until a human runs the export once.
  next -> /spec-fix drops the orphaned ExportHelper binding, then re-audits.

Below the pipeline sit the cheap paths: /quick (typo), /fix (narrow bug). Before anything user-facing, /ui-clarify. For brevity, /caveman. Plus /git, /prove, /critique.

Two disciplines live beside the pipeline, not inside it:

• Park, don't chase (/park). Hit a real but out-of-scope problem mid-task - bigger than a one-line fix, needs its own look? Record it as a stub, dedup against what's already filed, report it in one line, and return to the task. Never switch the active task to chase a parked finding; fix trivial things inline, drop cosmetic nitpicks.
• Drain the backlog (/backlog). A zero-input driver: pick the highest-priority eligible ticket, run the pipeline, repeat - until nothing is left the agent can advance alone. Two guards keep it safe: a skip-cache so an un-advanceable ticket isn't re-picked next loop, and no mid-loop questions - every human-gated ticket lands in one end-of-run report.

And a rule for the human questions themselves: triage a fork before surfacing it. If an external convention settles it, research that and recommend; if the architecture settles it, state it as a derived consequence. Reserve real questions for product scope, taste with no anchor, and irreversible actions. "Better to ask than guess" doesn't apply when research or the code already answers - surfacing a settled fork as a choice reads as not having done the homework.

In the portal: Skills: workflows as slash commands

These are role briefs with a trimmed tool set. An orchestrator carries a request to verified code; a researcher only reads and returns a report; an implementer writes code to a plan; a doc-writer produces human prose and UI copy.

• Why restrict tools: a researcher that cannot write cannot corrupt files by accident.
• Parallelism: several agents dig independent questions at once - local code and external docs in a single pass.
• Each role gets its own memory: a researcher's notes don't crowd an implementer's index.

Parallelism is a pure win for readers; parallel writers need care:

• Writers clobber through shared VCS state. One agent's whole-tree op - stash, checkout, reset, restore - reverts every other writer's uncommitted edits, even on disjoint files. The orchestrator owns VCS and build between waves, or each writer gets its own checkout.
• A subagent's report is a claim, not a verdict. Re-validate from the orchestrator's own clean state. A reported failure is often a phantom of a stale incremental build; a reported "compiles in isolation" is just as unproven.
• Delegation has a tail bias. A subagent spends its budget on the heavy early phases and truncates the last one - docs, wiring, cleanup - while its report says "done". Verify each deliverable exists and runs.
• Isolation is also a budget lever: run a bulky-evidence task in a throwaway agent that returns one compact verdict, so the artifacts stay in the child.

In the portal: Role agents

A spec answers two different questions that must not be muddled:

• Strategy (what/why): the problem, goals, constraints, open questions. No class names, no paths. If a reviewer disagrees here, you saved an implementation.
• Tactics (how): the exact files, symbols, and order, each step ending in a check. If a step is ambiguous, the executor stops instead of guessing.

Draft ─► Approved ─► Tactical ─► In Progress ─► Implemented ─► Verified
   │                                                │
   └─ rough is fine here                            └─ an audit may yield instead:
                                                       Partial (warnings)
                                                       Broken  (a failure)
plus explicit block states: BlockNeedUserTest, BlockQuestions, BlockExternal, ..

Before phases comes a complexity gate - a graded ladder, not a switch. A typo is /quick; a narrow bug is /fix; a small deterministic change (≤3 files, no new public types, no migration or DI wiring) ships as a three-section primitive; everything else runs the full pipeline. Pick the lowest rung that still proves the change, and ceremony stays proportional to the work.

The phase graph is designed in three passes: a coverage inventory (every goal maps to a phase or is marked out-of-scope), a produces/consumes topology (no phase consumes what a later phase produces), and a real-work filter (a step changes code, not plan text). Every step ends in a static check.

Status comes from reality, and that bites at entry too: a ticket reaches "awaiting test" only when its headline behaviour already works end-to-end. A compiled scaffold that only logs or shows a placeholder is a milestone, not a deliverable - don't invite a human to test a no-op.

Block states get a defined exit, not just an entrance: clear a question-blocked ticket by settling what the code already determines, asking the owner only the genuine judgment calls (with a researched default), and advancing one level. And the lifecycle ends somewhere - an Archived soft-delete moves a cancelled ticket out of the active set but keeps its record, so nothing is ever hard-deleted.

Guards split by what they check: a mechanical invariant hard-stops; a judgment call only informs and leaves go/no-go to the agent - hard-blocking on a heuristic just breeds bypasses. And a destructive step the plan already safeguards is no reason to invent a confirmation gate.

In the portal: Spec lifecycle

The runtime forgets everything between sessions. Code, specs, and git persist - but how you like to work, why a past decision went the way it did, and which corrections you already gave do not. Re-teaching that every session is the biggest hidden tax - like re-introducing yourself every morning to a colleague who rewrote half the project with you yesterday.

The fix is a small, file-based memory in memory/ under version control: an always-loaded MEMORY.md index plus one file per entry. Four types:

user       who the person is: role, expertise        → how to explain
feedback   how to work here - corrections AND praise  → never give the same tip twice
project    living context: who, what, why, by when    → decays fast
reference  a pointer to an external system + purpose  → where to look

The hard part is restraint. Don't store what is derivable from the repo or from git history, or that is just a fix recipe - those already live in the code and commits. And verify before recommending: a memory naming a function or path is a claim that it was true when written. Before acting on it, grep whether it still exists.

Durable memory is for facts worth keeping; the in-flight state of one interrupted task is not - keep them apart. For a task that spans a break, bookend it: at each phase boundary write a short handoff (goal, what changed, decisions, open blockers, the single next step), and on resume read the latest handoff before touching anything.

One caveat the word "persist" hides: the working tree, not git history, is the authority for what's done now. git log, blame, and diff answer "how did we get here", and they actively mislead when one file carries several tasks at once. Resume by reading the live files, then correct the trackers - never infer present state from a diff.

In the portal: Persistent memory

The most expensive thing the assistant does is guess. A guess looks like progress and costs a full wrong implementation. The cure is a fixed search order: map → spec → code index/grep → code → external docs. Stop as soon as a source answers.

One rule under all of it: if you state a path, a symbol, or an API, you have verified it. For a large repo, keep a queryable index of code units: query the index before you grep and regenerate it after you change code. A stale index is worse than none.

Two cheap guards extend the order. Keep an inventory of what the project already ships - a queryable list of capabilities - and scan it before designing a feature, so the agent doesn't rebuild under a new name something that already exists. And the map itself is an artifact you maintain: a feature-to-location lookup kept in step with the structure it describes, with someone owning its freshness - the same discipline the code index gets.

One sharpening of "verify, don't guess": a name is not behaviour. Before reasoning about what a flag or constant does, confirm a live read/call site - a comment or a doc mention is a hit, not a usage. Symbols go dead, get renamed in meaning, or never get wired up.

In the portal: Persistent memory

A step is not done when you intended it to work. It is done when a check passed in this run. The evidence is matched to the kind of change:

grep  <  run script  <  compile  <  targeted test  <  full build  <  run-and-observe
doc       script         type change  logic           config/resources  user-visible behaviour

Take the lowest rung that actually proves this change, and no higher. For every check, record expected: X | actual: Y - predicting the result before reading it catches the check that exited 0 while printing the wrong thing. "Works on my machine" is not a rung on this ladder - it's a superstition.

Two failure modes the ladder alone won't catch. "Done" is best as one fail-closed command that bundles the checks for the change kind - any one gate failing aborts the whole run non-zero, so "finished" means "all applicable gates passed", not "I remembered them all". And a green can lie: when commands are chained, piped, or backgrounded, the aggregate exit code often reflects a trailing wrapper, not the build or test you care about. Read the specific verdict line - a check that passes for the wrong reason is worse than no check.

A check has four answers, not two. Pass and found-a-defect are obvious; the third is could not verify, the fourth is not applicable in this configuration. A check with no way to say the last two will report one of the first two instead, and from then on it is lying. Two consequences. Validate the instrument before the subject: a physically impossible reading means the meter is broken, not that the subject failed - on one sweep that produced 5 "defects" out of 5 and 18 "unreachable" rows out of 28, every one of them false. And a false finding costs as much as a miss but is louder: once eighteen of them ship, a real defect is one row among them and nobody reads the report any more.

Before an irreversible step - a release, a publication, a filing, a send - the written verdict is that step's input, not a report filed beside it. The absence of a verdict is not a pass, and that is exactly how this gate fails: nobody breaks the rule, nothing ever goes red, and months ship unverified. The verdict must name what it judged (last time's verdict is precisely what a hurried hand reaches for) and must hang on the command that ships, not on a neighbouring one: in one project the gate existed, worked and was documented, while its own name appeared zero times in the release runbook.

Journal at the grain of the logical change, not the touched file: one entry per change, batching its files, and regenerate any index once per change - not once per edit. Left alone, an agent writes per-file noise that buries the story.

In the portal: Rules the agent follows

Seven patterns an AI (or a tired human) emits easily that look fine and quietly rot - like a container forgotten at the back of the fridge: fine from the outside, until someone opens it. The rule is to not write them in the first place and flag them on sight. All seven are greppable:

Each is mechanically scannable in a diff. Make the check part of "done", not part of "someday". If your stack has a linter, encode the patterns as rules so the gate is automatic.

Two things finish the loop. First, how do you adopt a rule on code that already breaks it? Gate on new violations, not all of them: freeze today's count as a checked-in baseline, fail only when it rises, and let the baseline ratchet down as you clean up - never up. The rule bites immediately, with no big-bang cleanup. That's the missing piece between "encode the pattern" and a real legacy codebase.

Second, a detector is only half the fix. A linter stops a human once; an agent re-emits the same pattern every generation. So close the source - add the matching DON'T to the always-loaded rulebook and reinforce it in the code-generating skills, so the agent stops producing the defect, not just flagging it after the fact.

And separately, what another project reads has one home, and it changes first. A file format, an export, an algorithm's constants that a neighbouring project depends on - that is a contract between projects. It lives in one place outside both, and each project keeps a pointer, never a copy: a copy drifts from the original at the first local edit. The contract changes before the code (a new version and a dated note); disagree, and you either amend the contract or record an exception with an expiry date. Silent drift is not an option.

User-facing docs are part of the change that alters behaviour, not a follow-up: the same change updates the doc, and a check fails when behaviour and its description drift. Keep an always-append "what shipped" log separate from the curated summary you regenerate at release.

In the portal: Rules the agent follows

The method is tied to neither a tool nor a model. Three situations below - pick yours.

A · A new or near-empty project

First let the agent build a map of the code with its built-in command - /init in Claude Code (or the equivalent in your tool). Then hand it this prompt to stand the project up on the method directly:

This is a fresh or mostly empty project folder. It may be a personal local
project without Git. First run your codebase-init
command (/init in Claude Code, or the equivalent in your tool) so you have a
rules file and a basic map of the project. Then download
https://github.com/SerZhyAle/universal-agent-kit/raw/main/universal-agent-kit.zip
into a temp or scratch directory and unpack it locally; it extracts to a
`universal-agent-kit/` folder that contains `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
read `universal-agent-kit/docs/PROJECT_SHAPES.md` to see which rules apply to work
like mine, then use `universal-agent-kit/AGENTS.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`,
`universal-agent-kit/examples/` (to see a filled result), and
`universal-agent-kit/merge-prompt.txt`. Do not use the article page as the
primary source. If you
cannot download files in this environment, stop and ask me to place the
archive in the workspace. Set this project up on the method from those files:

1. Write the rules file my tool reads (AGENTS.md; CLAUDE.md only imports it for
   Claude Code / a Cursor rule / GEMINI.md - whatever applies) adopting the kit's structure: communication,
   research order, skill routing, the spec lifecycle, strict rules, anti-slop,
   post-change discipline. Fill in what already exists; use sensible defaults
   otherwise.
2. Create the skill files and the role briefs from the kit that fit a
   project of this kind.
3. Set up the plan directory, the scratch directory, and the memory folder with
   its index.
4. Name THE CHECK COMMAND that proves a change is sound here. If this project is code,
   also pick the build / test / lint / run commands for the stack I name - or propose
   a stack if none exists yet.

Show me the plan first; create nothing until I approve.

B · An existing or personal local project

Takes a minute. This works even if the project is just a folder on your computer without Git. Ask your agent to download the archive, unpack it next to the project, and choose the most useful parts:

Download
https://github.com/SerZhyAle/universal-agent-kit/raw/main/universal-agent-kit.zip
into a temp or scratch directory and unpack it locally; it extracts to a
`universal-agent-kit/` folder that contains `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
read `universal-agent-kit/docs/PROJECT_SHAPES.md` to see which rules apply to work
like mine, then use `universal-agent-kit/AGENTS.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`,
`universal-agent-kit/examples/` (to see a filled result), and
`universal-agent-kit/merge-prompt.txt`. Do not use the article page as the
primary source. If you
cannot download files in this environment, stop and ask me to place the
archive in the workspace.

Then study THIS project folder and import what fits it. It may be a local personal
project without Git; do not require Git or create a repository:

1. Draft an AGENTS.md (or merge into my existing rules file) that adopts the method, with every
   tier-1 placeholder filled from this project: project name, chat language, artifact language,
   map document, work root, THE CHECK COMMAND that proves a change is sound, plan directory,
   scratch directory, size budget, read-only zones, and a simple way to name tasks (the ticket-id
   scheme). Fill the code-layer ones
   (architecture layers, build / test / lint / run, logger) only if this project builds or runs.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /prove, /critique) and which role agents are worth adding here, and say why.
   Consider /git only if this project already uses Git.
3. Tell me whether my runtime supports persistent agent memory and, if so, how to wire it up.

Do not change anything yet. Show me the plan first; on any conflict, my existing files win.

A quick way to start. The agent shows a plan first and changes nothing without your approval.

C · An existing project - the detailed path

Download the kit, give the agent its folder together with merge-prompt.txt, and say: "Add Universal Agent Kit to my project." This also works with an ordinary local folder. The agent first makes a list of what is already there, what it can add, and where conflicts may happen. It then shows a plan and stops: nothing is silently overwritten. After you approve, it adds the chosen parts and fills the <PLACEHOLDER>s from the project.

Any tool

Two of the three pieces now travel on their own: the rules file is AGENTS.md, which most agent tools read natively, and the skills are in the open Agent Skills format (a folder with a SKILL.md). Only the role agents are an adaptation. Each tool names its folders its own way:

• Claude Code - CLAUDE.md (imports AGENTS.md) + .claude/skills/* (ready-made /spec, /research..) + .claude/agents/* as subagents.
• Codex, Cursor, Copilot, Gemini CLI, Cline, Windsurf - AGENTS.md as the rules file (Gemini CLI: GEMINI.md, or AGENTS.md named in its settings); the skills in the tool's own skills folder, or in .claude/skills/ where the tool reads it; roles paste in as system prompts, modes or presets. The exact folders are in the table of the README.md inside the kit.
• The methodology in docs/ doesn't depend on the tool at all - it's just Markdown.

Any model - from strong to weak

The method doesn't depend on the model's power either - what changes is a few knobs, not the method:

• Strong (frontier, large context): holds more in its head. Bigger steps, more autonomy; you keep specs and checks for correctness, not to hold its hand.
• Regular: the method's sweet spot - specs, small verifiable steps, and the research order pay off the most.
• Weak, small, or local: you lean on the rules hardest - tiny steps, a check after each, short context, less autonomy. The method is what makes a weak model usable at all.

In the portal: Adopt and adapt

This kit isn't the only truth - it's one coherent set of habits. The habits themselves are common, and the teams who build these tools recommend the same ones:

• Keep the context lean. The context window fills fast and quality degrades as it fills. Start a fresh chat between unrelated tasks.
• Plan before code. Ask for an approach and a plan, approve it, and only then let the agent touch files.
• Two agents in a loop. One writes, another reviews or runs the tests; or tests first, then code to green.
• Make restore points. With Git, commit before and after a task. Without Git, copy the files or project folder you are changing, so an unsuccessful experiment is easy to undo.
• If you use Git, work in a separate branch. Check where you are before editing; do not commit straight to the protected or default branch.
• Write down repetition. Save a prompt you repeat often as a command or rules file. In a team, keep it in the shared project; for a personal folder, keep it next to the code.
• Script the release. Pin the version once into every artifact - tag, notes, build - so they can't drift; write release notes from a curated list of user-visible changes, not the raw commit log.
• Read the diff. The agent is fast, not infallible - don't merge what you didn't read.

The kit turns these from "nice to have" into a written process. The primary sources are worth reading in full:

Official "AI for development" guides

• Anthropic · Claude: Claude Code best practices · Effective context engineering
• OpenAI · Codex: Codex docs & quickstart
• Google · Antigravity: antigravity.google · Docs (Google's agentic IDE)

Links go to the vendors' official resources and open in a new tab. The method in this article works on top of any of these tools.

Keep it alive. The method needs upkeep: regenerate the index after changes, prune memory that's gone stale, lower ratchet baselines as you clean up, and revisit the skill routes as the project grows. An unmaintained index or memory is worse than none - budget a little tending, or the kit slowly starts to lie to you.

Adapted from the .claude/ setup of a real Android project, FastMediaSorter. Android-, PowerShell-, and locale-specific machinery was removed; the transferable method was kept and rewritten to be neutral. Since then the same core has been reconciled against the author's wider portfolio - an Android app, Windows desktop apps, Go command-line tools, a browser extension - and the rules that survived every shape are the ones the kit carries. No source code or proprietary content is included - only the working method.

The kit is MIT. This article's prose is CC BY 4.0. Take it, remix it, adapt it to your projects.

ШІ-асистент швидкий, але дрейфує. Він вгадує шляхи до файлів, вигадує API, що змінився дві версії тому, пише правдоподібне сміття, яке компілюється і тихо гниє, забуває все між сесіями і або питає дозволу на кожен чих, або мовчки робить не те. По суті - геніальний стажер з амнезією: друкує швидше за тебе, але до обіду вже не пам'ятає, як тебе звати.

Допомагає не черговий інструмент, а простий порядок роботи: короткі правила, готові сценарії для частих задач і кілька корисних нотаток. Він просить агента спершу розібратися, а потім змінювати файли; казати, коли чогось не знає; і зберігати важливий контекст між сесіями.

Тут показано, з чого все складається. Метод виріс із реального проєкту, але не прив'язаний до мови, моделі чи інструмента. Завантаж kit і поклади його поруч зі своїм проєктом - хоч це особиста папка на комп'ютері без Git, хоч спільний репозиторій.

Кому це все

• Тим, хто вже живе з ШІ-агентом і втомився втретє пояснювати те саме.
• Тим, хто хоче, щоб агент перевіряв, а не вгадував - і сам зізнавався, де не впевнений.
• Соло-розробникам і малим командам: одна спільна «операційка» замість набору звичок у голові однієї людини.
• Не лише програмістам. Якщо ваша робота - це файли, які хтось потім читає (аналітика, документація, договори, регламенти), метод лягає повністю, окрім шару про код. Розділ 02 перекладає його словник на п'ять видів проєктів і чесно каже, де межі.
• Будь-якому стеку й майже будь-якому інструменту. Claude Code - з коробки; Cursor, Cline, Codex, Aider - з легкою адаптацією.

Чого тут немає - срібної кулі. Метод не робить агента розумнішим; він лише заважає йому вистрілити собі в ногу й одразу забути, що нога була.

І де він кусає. У методу свої гострі краї: навали церемоній на однорядкову правку - і ти створив роботу на пустому місці; протухлий індекс чи карта збивають зі шляху гірше, ніж їх відсутність; паралельні писарі тихо затирають одне одного; пам'ять гниє, коли її ніхто не чистить. Більшість цих бід - від надлишку методу, а не від нестачі - лікує найнижчий щабель, що доводить зміну, та догляд за індексами й пам'яттю, які ти тримаєш.

Метод виріс із розробки, і приклади в ньому найгостріші саме там. Але тримається він не на компіляторі, а на п'яти речах: робоча тека з історією, артефакти - те, що робота виробляє і хтось потім читає, одиниці роботи з чесним статусом, перевірки - питання до артефакту, на яке відповідають без чиєїсь думки, - і агент, який уміє читати й писати ваші файли. Є чотири з п'яти - метод працює, і дірку ви відчуєте рівно там, де мала бути п'ята.

Нижче - словник методу на п'яти видах проєктів. Уся решта статті написана в першій колонці; знайдіть свою й читайте через неї.

І що варто видалити, а не пристосовувати. Правило, лишене «про всяк випадок» у проєкті, до якого воно не застосовне, - це шум, який привчає всіх гортати. Якщо у вас ніщо нічого не імпортує, видаліть шари й напрям залежностей. Якщо ваші артефакти не лишають сліду виконання, видаліть мітки верифікації. Щабель «компіляція» просто зникає, і драбина перевірок починається на один вище. Повна таблиця перекладу, разом із чесними межами методу, лежить у кіті: docs/PROJECT_SHAPES.md.

Де метод чесно не допоможе: там, де механічно не перевірити взагалі нічого, він вироджується в чек-лист із гарними манерами - поділ «що» і «як», статус із реальності й заборона на слово «має працювати» лишаються, але примусу більше немає. Там, де артефакт - один суцільний документ з одним автором, тикет-машинерія це накладні витрати: візьміть правила, /quick, /fix і пам'ять. А там, де робота взагалі не у файлах - розмова, перемовини, рішення, яке ніде не записане, - методу сказати нічого. Запишіть спершу; тоді це стане проєктом.

У порталі: Впровадження й адаптація

Це один короткий файл, який агент читає на початку роботи. У ньому: як із тобою спілкуватися, де шукати код, як перевіряти результат і коли питати, а не вгадувати. Інші матеріали можуть на нього посилатися.

Головне - тримати його коротким. Це не енциклопедія: подробиці лежать у docs/, а тут лише потрібні орієнтири й підказка, який готовий промпт вибрати для задачі. У kit'і це AGENTS.md: його читає більшість інструментів, а CLAUDE.md у Claude Code лише підключає його. Де потрібне власне ім'я - правило Cursor, GEMINI.md - суть та сама.

Плейсхолдерів у ньому два яруси: десять потрібні будь-якому проєкту (разом із тим самим <CHECK_CMD> - командою, яка доводить, що правка не зламана), і шість - лише тим, що збираються або запускаються. Якщо ваш не збирається, правила з цими шістьма видаляються, а не заповнюються навмання.

У порталі: Правила, за якими працює агент

Навичка - це багаторазовий промпт, що кодує робочий процес. Пишеш /spec - асистент іде записаною процедурою, а не імпровізує заново. Гарна практика записана один раз, а не виводиться щоразу з нуля. В інструментах без slash-команд та сама навичка - це файл-промпт, на який ти посилаєшся.

Хребет - пайплайн, що веде ідею до перевіреної реалізації:

/research   зібрати докази, зберегти               (до всього нетривіального)
/spec       стратегічне що/навіщо                   Draft → Approved
/spec-tech  фазовий перевірюваний план             Approved → Tactical
/spec-dev   виконувати покроково, перевіряти кожен  Tactical → Implemented
/spec-check аудит проти спеки                       → Verified / Partial / Broken
/spec-fix   механічний ремонт після аудиту         Partial / Broken → переаудит
/spec-all   прогнати весь пайплайн цілком           idea → verified

$ /spec-check T0207
T0207: auditing the strategic spec + 3 phases against the repo..
  PASS    file exists          export/CsvWriter
  PASS    symbol declared      writeRows(rows)
  PASS    no forbidden call    grep raw-logger -> 0 hits
  WARN    dead weight          old ExportHelper still wired in the container
  MANUAL  export writes a valid file on a real run
  PASS    changelog            an entry for every touched file
verdict: BlockNeedUserTest     (PASS 6 / WARN 1 / FAIL 0)
  was "Implemented" -> downgraded: the build is sound, but the headline
  behaviour is unproven until a human runs the export once.
  next -> /spec-fix drops the orphaned ExportHelper binding, then re-audits.

Під пайплайном - дешеві шляхи: /quick (одрук), /fix (вузький баг). Перед усім користувацьким - /ui-clarify. Для стислості - /caveman. Плюс /git, /prove, /critique.

Поряд із пайплайном - а не всередині нього - живуть дві дисципліни:

• Паркуй, а не женися (/park). Натрапив посеред задачі на реальну, але поза-обсягову проблему - більшу за однорядкову правку, що потребує окремого погляду? Запиши її заглушкою, відсій дублі проти вже заведеного, відзвітуй одним рядком і повернися до задачі. Ніколи не перемикай активну задачу, щоб гнатися за запаркованою знахідкою; дрібниці лагодь на місці, косметичні причіпки відкидай.
• Вичерпуй беклог (/backlog). Драйвер без вхідних даних: бери придатний тикет із найвищим пріоритетом, ганяй пайплайн, повторюй - доки не лишиться нічого, що агент може просунути сам. Безпеку тримають два запобіжники: кеш пропусків, щоб непросувний тикет не вибирався знову наступним колом, і жодних питань посеред циклу - кожен тикет з людським гейтом потрапляє в один звіт по завершенні прогону.

І правило для самих людських питань: розсортуй розвилку, перш ніж виносити її. Якщо її вирішує зовнішня конвенція - дослідь це й порекомендуй; якщо її вирішує архітектура - сформулюй як похідний наслідок. Справжні питання прибережи для обсягу продукту, смаку без опори та незворотних дій. «Краще спитати, ніж вгадати» не діє, коли дослідження чи сам код уже відповідають - винесена як вибір вирішена розвилка читається як невиконане домашнє завдання.

У порталі: Навички: сценарії як slash-команди

Це роль-брифи з урізаним набором інструментів. Оркестратор веде задачу від запиту до перевіреного коду; ресерчер лише читає й видає звіт; імплементер пише код за планом; докрайтер - людські тексти та UI-копірайт.

• Навіщо обмежувати інструменти: ресерчер, який не вміє писати, не зіпсує файли випадково.
• Паралелізм: кілька агентів одночасно копають незалежні питання - локальний код і зовнішні доки за один захід.
• Кожному - своя пам'ять: нотатки ресерчера не засмічують індекс імплементера.

Паралелізм - чистий виграш для читачів; паралельні писарі потребують обережності:

• Писарі затирають одне одного через спільний стан VCS. Операція одного агента над усім деревом - stash, checkout, reset, restore - відкочує незакомічені правки кожного іншого писаря, навіть у неперетинних файлах. VCS і збіркою між хвилями володіє оркестратор, або кожен писар отримує власний checkout.
• Звіт субагента - це твердження, а не вирок. Перевір наново з власного чистого стану оркестратора. Звітований провал часто - фантом застарілої інкрементальної збірки; звітоване «компілюється ізольовано» так само недоведене.
• У делегування є зсув до хвоста. Субагент витрачає бюджет на важкі ранні фази й обрізає останню - доки, проводку, прибирання, - а звіт каже «готово». Перевір, що кожен результат існує й запускається.
• Ізоляція - це ще й важіль бюджету: ганяй задачу з громіздкими доказами в одноразовому агенті, що повертає один компактний вирок, - так артефакти лишаються в дочірньому.

У порталі: Рольові агенти

Спека відповідає на два різні питання, які не можна плутати:

• Стратегія (що/навіщо): проблема, цілі, обмеження, відкриті питання. Без імен класів і шляхів. Якщо рев'юер не згоден тут - ти заощадив реалізацію.
• Тактика (як): точні файли, символи та порядок, кожен крок закінчується перевіркою. Якщо крок неоднозначний - виконавець зупиняється, а не вгадує.

Draft ─► Approved ─► Tactical ─► In Progress ─► Implemented ─► Verified
   │                                                │
   └─ чернетка може бути сирою                      └─ аудит може дати натомість:
                                                       Partial (попередження)
                                                       Broken  (є відмова)
плюс явні блок-статуси: BlockNeedUserTest, BlockQuestions, BlockExternal, ..

Перед фазами - гейт складності - градуйована драбина, а не вимикач. Одрук - це /quick; вузький баг - /fix; дрібна детермінована правка (≤3 файлів, без нових публічних типів, без міграцій і DI) йде як примітив у три секції; усе інше - повний пайплайн. Бери найнижчий щабель, що все ще доводить зміну, - і церемонія лишається пропорційною роботі.

Граф фаз проєктується трьома проходами: інвентар покриття (кожна ціль лягає у фазу або позначається поза-обсягом), топологія «виробляє/споживає» (жодна фаза не споживає те, що зробить пізніша), фільтр реальної роботи (крок змінює код, а не текст плану). Кожен крок закінчується статичною перевіркою.

Статус - з реальності, і це б'є вже на вході: тикет доходить до «очікує тесту» лише тоді, коли його ключова поведінка вже працює наскрізно. Скомпільований каркас, що лише логує чи показує заглушку, - це віха, а не результат: не клич людину тестувати порожню дію.

Блок-статуси мають визначений вихід, а не лише вхід: розблокуй тикет, заблокований питанням, - вирішивши те, що код уже визначає, спитавши власника лише про справжні судження (із дослідженим дефолтом) і просунувши на один рівень. І життєвий цикл десь закінчується - Archived, м'яке видалення, виносить скасований тикет з активного набору, але зберігає його запис, тож нічого ніколи не видаляється остаточно.

Запобіжники діляться за тим, що перевіряють: механічний інваріант жорстко зупиняє; судження лише інформує й лишає рішення «йти/не йти» агенту - жорсткий блок на евристиці лише плодить обходи. А руйнівний крок, який план уже убезпечив, - не привід вигадувати гейт підтвердження.

У порталі: Життєвий цикл спеки

Рантайм забуває все між сесіями. Код, спеки та git лишаються - а от як ти любиш працювати, чому минуле рішення було таким і які правки ти вже давав - ні. Переучувати це щосесії - головний прихований податок: як щоранку наново знайомитися з колегою, що вчора з тобою переписав пів проєкту.

Лікування - маленька файлова пам'ять у memory/ під контролем версій: завжди-завантажений індекс MEMORY.md плюс по файлу на запис. Чотири типи:

user       хто людина: роль, досвід, що вже знає     → як пояснювати
feedback   як працювати тут - з правок І похвал      → не повторювати підказку двічі
project    живий контекст: хто, що, навіщо, до коли   → швидко застаріває
reference  вказівник у зовнішню систему та навіщо    → де шукати

Тонкість - стриманість. Не зберігай те, що виводиться з репозиторію, git-історії, чи рецепти лагодження - це вже в коді та комітах. І перевіряй перед порадою: пам'ять, що називає функцію чи шлях, - це твердження «так було, коли записали». Перед дією - грепни, чи існує воно зараз.

Постійна пам'ять - для фактів, що варті збереження; для летючого стану однієї перерваної задачі - ні, тримай їх окремо. Задачу, що переживає перерву, обрамляй з двох боків: на кожній межі фази пиши коротку передачу (ціль, що змінилося, рішення, відкриті блокери, єдиний наступний крок), а на відновленні читай останню передачу, перш ніж чогось торкатися.

Одне застереження, яке ховає слово «постійний»: авторитет того, що зроблено зараз, - це робоче дерево, а не git-історія. git log, blame і diff відповідають на «як ми сюди дійшли» й активно вводять в оману, коли один файл несе кілька задач одночасно. Відновлюйся, читаючи живі файли, потім виправляй трекери - ніколи не виводь поточний стан із диффа.

У порталі: Постійна пам'ять

Найдорожче, що робить асистент, - вгадує. Вгадка має вигляд прогресу й коштує цілої хибної реалізації. Ліки - фіксований порядок пошуку: карта → спека → індекс коду/греп → код → зовнішні доки. Зупиняєшся, щойно джерело відповіло.

Одне правило під усім: якщо ти назвав шлях, символ чи API - ти їх перевірив. Для великого репозиторію тримають запитуваний індекс одиниць коду: питаєш індекс до грепу й регенеруєш його після правок. Застарілий індекс гірший за відсутній.

Порядок розширюють два дешеві запобіжники. Тримай інвентар того, що проєкт уже має - запитуваний список можливостей - і скануй його перед проєктуванням фічі, щоб агент не переписував під новим іменем те, що вже існує. І сама карта - це артефакт, який ти підтримуєш: довідник «фіча → розташування», що тримається в кроці зі структурою, яку описує, і за чию свіжість хтось відповідає, - та сама дисципліна, що й для індексу коду.

Одне загострення «перевіряй, не вгадуй»: ім'я - це не поведінка. Перш ніж міркувати, що флаг чи константа робить, підтверди живе місце читання/виклику - коментар чи згадка в доках - це збіг, а не використання. Символи відмирають, змінюють сенс під час перейменування або взагалі не підключені.

У порталі: Постійна пам'ять

Крок не зроблено, коли ти хотів, щоб він працював. Він зроблений, коли перевірка пройшла в цьому прогоні. Рівень доказу підбирається під тип зміни:

греп  <  запуск скрипту  <  компіляція  <  точковий тест  <  повна збірка  <  запуск-і-спостереження
док        скрипт            правка типів     логіка          конфіг/ресурси      користувацька поведінка

Бери найнижчий щабель, що реально доводить цю зміну, і не вище. Для кожної перевірки записуй очікував: X | отримав: Y - передбачення до читання результату ловить перевірку, що повернула 0, але надрукувала не те. «Працює на моїй машині» - не щабель цієї драбини, а забобон.

Два режими провалу, яких сама драбина не зловить. «Готово» найкраще оформити як одну fail-closed команду, що збирає перевірки під тип зміни - провал будь-якого гейта валить увесь прогін ненульовим кодом, тож «завершено» означає «всі застосовні гейти пройдено», а не «я всі їх пам'ятав». І зелене може брехати: коли команди зчеплено, спайплайнено чи виведено у фон, сукупний код виходу часто відображає кінцеву обгортку, а не ту збірку чи тест, що тобі важливі. Читай конкретний рядок вироку - перевірка, що проходить з хибної причини, гірша за відсутність перевірки.

У перевірки чотири відповіді, а не дві. «Пройшло» і «знайшла дефект» очевидні; третя - не змогла перевірити, четверта - незастосовно в цій конфігурації. Перевірка, яка не вміє сказати останні дві, скаже одну з перших двох, і відтоді вона бреше. Звідси два наслідки. Спершу перевіряй прилад, а не предмет: фізично неможливе показання означає, що зламаний вимірювач, а не піддослідний - на одному прогоні так народилися 5 «дефектів» із 5 і 18 «недосяжних» пунктів із 28, усі хибні. І хибна знахідка коштує стільки ж, скільки пропущена, але гучніше: коли хибних вісімнадцять, справжня стає одним рядком серед них, і звіт перестають читати.

Перед незворотним кроком - релізом, публікацією, поданням, відправленням - письмовий вирок це вхід цього кроку, а не звіт десь поруч. Відсутність вироку не рахується за «пройшло», і ламається цей гейт саме так: ніхто не порушив правило, нічого не почервоніло, а місяці поїхали неперевіреними. Вирок мусить називати, що саме він оцінював (вирок від минулого разу - рівно те, за чим тягнеться рука в поспіху), і висіти на тій команді, яка відвантажує, а не на сусідній: в одному проєкті гейт існував, працював і був описаний, а в інструкції з релізу його ім'я траплялося нуль разів.

Веди журнал на гранулярності логічної зміни, а не зачепленого файлу: один запис на зміну, що пакує її файли, і регенеруй будь-який індекс раз на зміну - а не раз на правку. Залишений сам по собі, агент пише пофайловий шум, що ховає сюжет.

У порталі: Правила, за якими працює агент

Сім патернів, які ШІ (і втомлена людина) видає легко, а вони мають вигляд нормальних і тихо гниють - як забутий у глибині холодильника контейнер: ззовні лад, доки не відкриєш. Правило - не писати їх від самого початку й ловити на рев'ю. Усі сім - греп-перевірювані:

Кожен можна механічно просканувати в дифі. Зроби перевірку частиною «готово», а не «колись». Якщо у стеку є лінтер - закодуй патерни як правила, щоб гейт був автоматичним.

Дві речі замикають петлю. Перше, як ввести правило на коді, що вже його порушує? Гейтуй нові порушення, а не всі: заморозь сьогоднішню кількість як закомічену базову лінію, валі лише коли вона зростає, і дай базовій лінії спускатися, поки прибираєш, як тріскачці, - ніколи не вгору. Правило кусає одразу, без прибирання великим вибухом. Це і є відсутня ланка між «закодуй патерн» і реальним легасі-кодом.

Друге, детектор - це лише пів ліків. Лінтер зупиняє людину один раз; агент видає той самий патерн щогенерації. Тож закрий джерело - додай відповідне DON'T у завжди-завантажений звід правил і підкріпи в навичках, що генерують код, щоб агент перестав виробляти дефект, а не лише позначати його постфактум.

І окремо - те, що читає інший проєкт, живе в одному місці й змінюється першим. Формат файлу, вивантаження, константи алгоритму, від яких залежить сусідній проєкт, - це контракт між проєктами. Він лежить в одному місці поза обома, а кожен проєкт тримає лише вказівник, не копію: копія розходиться з оригіналом після першої ж правки. Спершу контракт (нова версія й датований запис), потім код; не згоден - виправ контракт або запиши виняток із датою закінчення. Тихого дрейфу не буває.

Користувацькі доки - частина зміни, що змінює поведінку, а не післядія: та сама зміна оновлює док, а перевірка валиться, коли поведінка та її опис розходяться. Тримай завжди-доповнюваний лог «що вийшло» окремо від кураторського зведення, яке регенеруєш на релізі.

У порталі: Правила, за якими працює агент

Метод не прив'язаний ні до інструмента, ні до моделі. Нижче три ситуації - обери свою.

A · Новий або майже порожній проєкт

Спершу дай агенту зібрати карту коду його штатною командою - /init у Claude Code (або аналог у твоєму інструменті). Потім віддай цей промпт, щоб він підняв проєкт одразу за методом:

This is a fresh or mostly empty project folder. It may be a personal local
project without Git. First run your codebase-init
command (/init in Claude Code, or the equivalent in your tool) so you have a
rules file and a basic map of the project. Then download
https://github.com/SerZhyAle/universal-agent-kit/raw/main/universal-agent-kit.zip
into a temp or scratch directory and unpack it locally; it extracts to a
`universal-agent-kit/` folder that contains `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
read `universal-agent-kit/docs/PROJECT_SHAPES.md` to see which rules apply to work
like mine, then use `universal-agent-kit/AGENTS.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`,
`universal-agent-kit/examples/` (to see a filled result), and
`universal-agent-kit/merge-prompt.txt`. Do not use the article page as the
primary source. If you
cannot download files in this environment, stop and ask me to place the
archive in the workspace. Set this project up on the method from those files:

1. Write the rules file my tool reads (AGENTS.md; CLAUDE.md only imports it for
   Claude Code / a Cursor rule / GEMINI.md - whatever applies) adopting the kit's structure: communication,
   research order, skill routing, the spec lifecycle, strict rules, anti-slop,
   post-change discipline. Fill in what already exists; use sensible defaults
   otherwise.
2. Create the skill files and the role briefs from the kit that fit a
   project of this kind.
3. Set up the plan directory, the scratch directory, and the memory folder with
   its index.
4. Name THE CHECK COMMAND that proves a change is sound here. If this project is code,
   also pick the build / test / lint / run commands for the stack I name - or propose
   a stack if none exists yet.

Show me the plan first; create nothing until I approve.

B · Наявний або особистий локальний проєкт

За хвилину. Підходить, навіть якщо проєкт - це просто папка на твоєму комп'ютері без Git. Попроси агента завантажити архів, розпакувати його поруч із проєктом і вибрати найкорисніше:

Download
https://github.com/SerZhyAle/universal-agent-kit/raw/main/universal-agent-kit.zip
into a temp or scratch directory and unpack it locally; it extracts to a
`universal-agent-kit/` folder that contains `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
read `universal-agent-kit/docs/PROJECT_SHAPES.md` to see which rules apply to work
like mine, then use `universal-agent-kit/AGENTS.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`,
`universal-agent-kit/examples/` (to see a filled result), and
`universal-agent-kit/merge-prompt.txt`. Do not use the article page as the
primary source. If you
cannot download files in this environment, stop and ask me to place the
archive in the workspace.

Then study THIS project folder and import what fits it. It may be a local personal
project without Git; do not require Git or create a repository:

1. Draft an AGENTS.md (or merge into my existing rules file) that adopts the method, with every
   tier-1 placeholder filled from this project: project name, chat language, artifact language,
   map document, work root, THE CHECK COMMAND that proves a change is sound, plan directory,
   scratch directory, size budget, read-only zones, and a simple way to name tasks (the ticket-id
   scheme). Fill the code-layer ones
   (architecture layers, build / test / lint / run, logger) only if this project builds or runs.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /prove, /critique) and which role agents are worth adding here, and say why.
   Consider /git only if this project already uses Git.
3. Tell me whether my runtime supports persistent agent memory and, if so, how to wire it up.

Do not change anything yet. Show me the plan first; on any conflict, my existing files win.

Швидкий спосіб почати. Агент спершу покаже план і нічого не змінить без твого підтвердження.

C · Наявний проєкт - докладний шлях

Завантаж kit, віддай агенту теку разом з merge-prompt.txt і скажи: «Додай Universal Agent Kit до мого проєкту». Це працює і зі звичайною локальною папкою. Агент спершу складе список: що вже є, що можна додати і де можливий конфлікт. Потім покаже план і зупиниться: нічого не перезаписується мовчки. Після твого підтвердження він додасть обрані частини й заповнить <PLACEHOLDER> за матеріалами проєкту.

Будь-який інструмент

Дві з трьох частин тепер переїжджають самі: файл правил - це AGENTS.md, який нативно читає більшість агентських інструментів, а навички лежать у відкритому форматі Agent Skills (тека з SKILL.md). Адаптації потребують лише агенти-ролі. Кожен інструмент називає теки по-своєму:

• Claude Code - CLAUDE.md (підключає AGENTS.md) + .claude/skills/* (готові /spec, /research..) + .claude/agents/* як субагенти.
• Codex, Cursor, Copilot, Gemini CLI, Cline, Windsurf - AGENTS.md як файл правил (у Gemini CLI - GEMINI.md або AGENTS.md, названий у налаштуваннях); навички - у власній теці навичок інструмента або в .claude/skills/, де інструмент її читає; ролі вставляються як системні промпти, режими чи пресети. Точні теки - у таблиці README.md усередині kit'а.
• Методологія в docs/ взагалі не залежить від інструмента - це просто Markdown.

Будь-яка модель - від сильної до слабкої

Метод не залежить і від потужності моделі - змінюється не він, а кілька ручок:

• Сильна (фронтир, великий контекст): тримає більше в голові. Кроки більші, автономії більше; спеки та перевірки лишаєш заради коректності, а не щоб вести за руку.
• Регулярна: золота середина методу - спеки, дрібні перевірювані кроки й порядок дослідження окупаються максимально.
• Слабка, маленька чи локальна: спираєшся на правила найсильніше - крихітні кроки, перевірка після кожного, короткий контекст, менше автономії. Метод - це те, що взагалі робить слабку модель придатною для роботи.

У порталі: Впровадження й адаптація

Цей kit - не єдина істина, а один зв'язний набір звичок. Самі звички загальні - їх же радять команди, що ці інструменти й роблять:

• Тримай контекст коротким. Вікно контексту забивається швидко, і якість падає із заповненням. Між незв'язаними задачами починай свіжий чат.
• Спершу план, потім код. Попроси підхід і план, затверди - і лише потім дозволяй правити файли.
• Два агенти в петлі. Один пише, інший рев'юить або ганяє тести; або спершу тести, потім код до зеленого.
• Роби точки повернення. З Git це коміт до і після задачі. Без Git - копія змінюваних файлів або папки проєкту, щоб невдалий експеримент можна було спокійно скасувати.
• Якщо користуєшся Git - працюй в окремій гілці. Перед правками перевір, де ти, і не коміть прямо в захищену чи основну гілку.
• Записуй повторюване. Часто повторюваний промпт збережи в команду або файл правил. У команді поклади його у спільний проєкт; в особистій папці тримай поруч із кодом.
• Заскриптуй реліз. Пропиши версію один раз в усі артефакти - тег, нотатки, збірку, - щоб вони не розходилися; нотатки релізу пиши з кураторського списку видимих користувачу змін, а не з сирого журналу комітів.
• Читай дифф. Агент швидкий, але не безпомильний - не вливай те, що сам не прочитав.

Kit перетворює ці поради з «добре б» на записаний процес. Першоджерела варто прочитати повністю:

Офіційні гайди «ШІ для розробки»

• Anthropic · Claude: Claude Code best practices · Effective context engineering
• OpenAI · Codex: Codex docs і quickstart
• Google · Antigravity: antigravity.google · Docs (агентна IDE від Google)

Посилання ведуть на офіційні ресурси вендорів і відкриваються в новій вкладці. Метод із цієї статті працює поверх будь-якого з цих інструментів.

Тримай це живим. Метод потребує догляду: перегенеруй індекс після змін, чисть пам'ять, що протухла, опускай базові лінії тріскачки в міру прибирання й переглядай маршрути навичок у міру того, як проєкт росте. Недоглянутий індекс чи пам'ять гірші за їх відсутність - заклади трохи догляду, інакше kit потроху почне тобі брехати.

Адаптовано з .claude/-сетапу реального Android-проєкту FastMediaSorter. Android-, PowerShell- і локаль-специфічна машинерія видалена; переносний метод лишено й переписано нейтрально. Відтоді це ж ядро звірено з рештою портфеля автора - Android-застосунок, десктопні застосунки для Windows, Go-утиліти командного рядка, браузерне розширення - і в kit увійшли правила, що пережили всі ці форми. Вихідного коду та пропрієтарного вмісту тут немає - лише робочий метод.

Kit - під MIT. Текст цієї статті - під CC BY 4.0. Бери, реміксуй, адаптуй під свої проєкти.