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

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

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

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

Кому это всё

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

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

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

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

Главное - держать его коротким. Это не энциклопедия: подробности лежат в docs/, а здесь только нужные ориентиры и подсказка, какой готовый промпт выбрать для задачи. Имя файла зависит от инструмента - CLAUDE.md, AGENTS.md, правило Cursor или GEMINI.md, - но смысл один.

Навык - это сохранённый промпт для повторяющейся задачи. Пишешь /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, /verify, /review.

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

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

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

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

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

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

• Писатели затирают друг друга через общее 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 команда, которая собирает проверки под тип изменения, - любой провалившийся гейт обрывает весь прогон с ненулевым кодом, так что «закончено» означает «все применимые гейты прошли», а не «я их все вспомнил». И зелёное может врать: когда команды сцеплены, в пайпе или ушли в фон, агрегатный код выхода часто отражает хвостовую обёртку, а не ту сборку или тест, что тебе важны. Читай конкретную строку вердикта - проверка, прошедшая по неверной причине, хуже отсутствия проверки.

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

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

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

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

Второе: детектор - лишь половина починки. Линтер останавливает человека один раз; агент переиздаёт тот же паттерн каждое поколение. Так что закрой источник - добавь соответствующий 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 beside a `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
use `universal-agent-kit/CLAUDE.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`, and
`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 (CLAUDE.md / AGENTS.md / 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 / command 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. 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 beside a `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
use `universal-agent-kit/CLAUDE.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`, and
`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 a CLAUDE.md (or my tool's equivalent rules file) that adopts the method, with every
   placeholder filled from this project: project name, chat language, source root, architecture
   layers, build / test / lint / run commands, logger, plan directory, scratch directory,
   file-size budget, read-only zones, and a simple way to name tasks if useful.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /verify, /review) 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> по материалам проекта.

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

Каждый агент читает свой файл правил - суть одна, отличается лишь имя:

• Claude Code - CLAUDE.md + .claude/commands/* (готовые /spec, /research..) + .claude/agents/* как субагенты.
• Cursor - .cursor/rules (или .cursorrules); команды становятся сохранёнными промптами.
• Codex, Gemini CLI / Antigravity, Aider, Cline, Windsurf - AGENTS.md (указатель уже лежит в kit'е, правила - в CLAUDE.md рядом) / GEMINI.md / свой аналог; роли вставляются как системные промпты, навыки - как файлы-промпты, на которые ссылаешься.
• Методология в 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.
• 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.

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. Its name depends on the tool - CLAUDE.md, AGENTS.md, a Cursor rule, or GEMINI.md - but the purpose is the same.

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, /verify, /review.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 beside a `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
use `universal-agent-kit/CLAUDE.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`, and
`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 (CLAUDE.md / AGENTS.md / 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 / command 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. 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 beside a `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
use `universal-agent-kit/CLAUDE.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`, and
`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 a CLAUDE.md (or my tool's equivalent rules file) that adopts the method, with every
   placeholder filled from this project: project name, chat language, source root, architecture
   layers, build / test / lint / run commands, logger, plan directory, scratch directory,
   file-size budget, read-only zones, and a simple way to name tasks if useful.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /verify, /review) 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

Every agent reads its own rules file - the idea is the same, only the name differs:

• Claude Code - CLAUDE.md + .claude/commands/* (ready-made /spec, /research..) + .claude/agents/* as subagents.
• Cursor - .cursor/rules (or .cursorrules); the commands become saved prompts.
• Codex, Gemini CLI / Antigravity, Aider, Cline, Windsurf - AGENTS.md (a pointer ships in the kit; the rules live in CLAUDE.md next to it) / GEMINI.md / their own equivalent; roles paste in as system prompts, skills as prompt files you point at.
• 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.

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, хоч спільний репозиторій.

Кому це все

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

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

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

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

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

Навичка - це багаторазовий промпт, що кодує робочий процес. Пишеш /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, /verify, /review.

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

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

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

Це роль-брифи з урізаним набором інструментів. Оркестратор веде задачу від запиту до перевіреного коду; ресерчер лише читає й видає звіт; імплементер пише код за планом; докрайтер - людські тексти та 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 команду, що збирає перевірки під тип зміни - провал будь-якого гейта валить увесь прогін ненульовим кодом, тож «завершено» означає «всі застосовні гейти пройдено», а не «я всі їх пам'ятав». І зелене може брехати: коли команди зчеплено, спайплайнено чи виведено у фон, сукупний код виходу часто відображає кінцеву обгортку, а не ту збірку чи тест, що тобі важливі. Читай конкретний рядок вироку - перевірка, що проходить з хибної причини, гірша за відсутність перевірки.

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

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

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

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

Друге, детектор - це лише пів ліків. Лінтер зупиняє людину один раз; агент видає той самий патерн щогенерації. Тож закрий джерело - додай відповідне 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 beside a `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
use `universal-agent-kit/CLAUDE.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`, and
`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 (CLAUDE.md / AGENTS.md / 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 / command 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. 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 beside a `merge-prompt.txt`. Use those extracted
files as the source of truth: read `universal-agent-kit/README.md` first, then
use `universal-agent-kit/CLAUDE.md`, `universal-agent-kit/.claude/`,
`universal-agent-kit/docs/`, `universal-agent-kit/memory/`, and
`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 a CLAUDE.md (or my tool's equivalent rules file) that adopts the method, with every
   placeholder filled from this project: project name, chat language, source root, architecture
   layers, build / test / lint / run commands, logger, plan directory, scratch directory,
   file-size budget, read-only zones, and a simple way to name tasks if useful.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /verify, /review) 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> за матеріалами проєкту.

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

Кожен агент читає свій файл правил - суть одна, відрізняється лише ім'я:

• Claude Code - CLAUDE.md + .claude/commands/* (готові /spec, /research..) + .claude/agents/* як субагенти.
• Cursor - .cursor/rules (або .cursorrules); команди стають збереженими промптами.
• Codex, Gemini CLI / Antigravity, Aider, Cline, Windsurf - AGENTS.md (вказівник вже лежить у kit'і, правила - у CLAUDE.md поруч) / GEMINI.md / свій аналог; ролі вставляються як системні промпти, навички - як файли-промпти, на які посилаєшся.
• Методологія в 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. Бери, реміксуй, адаптуй під свої проєкти.