Как устроена разработка с ИИ-агентами How AI-assisted development is wired Як влаштована розробка з ШІ-агентами

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

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

Эта страница показывает, как всё собрано - на примере одного реального проекта, но всё унифицировано и не привязано ни к языку, ни к задачам проекта - и ни к конкретному инструменту или модели. Внизу можно скачать kit и положить в свой git-репозиторий почти на любом стеке.

Кому это всё

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

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

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

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

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

Хребет - пайплайн, который ведёт идею до проверенной реализации:

/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

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

Это роль-брифы с урезанным набором инструментов. Оркестратор ведёт задачу от запроса к проверенному коду; ресёрчер только читает и выдаёт отчёт; имплементер пишет код по плану; докрайтер - человеческие тексты и UI-копирайт.

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

Спека отвечает на два разных вопроса, которые нельзя путать:

• Стратегия (что/зачем): проблема, цели, ограничения, открытые вопросы. Без имён классов и путей. Если ревьюер не согласен здесь - ты сэкономил реализацию.
• Тактика (как): точные файлы, символы и порядок, каждый шаг кончается проверкой. Если шаг неоднозначен - исполнитель останавливается, а не угадывает.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

This is a fresh or mostly empty repository. 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 · Существующий проект - быстрый путь

За минуту. Попроси агента прямо в чате скачать архив kit-а, распаковать его локально и импортировать самое полезное:

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 repository and import what fits it:

1. Draft a CLAUDE.md (or my tool's equivalent rules file) that adopts the method, with every
   placeholder filled from this repo: 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 ticket-id scheme.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /verify, /git, /review) and which role agents are worth adding here, and say
   why for each.
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: здесь нет явного merge-процесса с инвентарём и остановкой перед записью.

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 / GEMINI.md / свой аналог; роли вставляются как системные промпты, навыки - как файлы-промпты, на которые ссылаешься.
• Методология в docs/ вообще не зависит от инструмента - это просто Markdown.

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

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

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

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

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

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

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

• Anthropic · Claude: Claude Code best practices · Effective context engineering
• OpenAI · Codex: Codex docs и quickstart
• Google · Antigravity: antigravity.google · Docs (преемник Gemini CLI)

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

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

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.

The cure is not a tool - it is a method: a small operating system on top of the assistant. A rulebook, roles, a spec lifecycle, and memory. It makes the assistant research before it acts, split what from how, plan in verifiable steps, stay terse and honest, and accumulate knowledge across sessions.

This page shows how it is wired - using one real project as the example, but kept unified and tied to neither a language nor that project's goals - nor to a specific tool or model. At the bottom you can download the kit and drop it into most git-backed codebases, whatever the stack.

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.
• Solo developers and small teams: one shared "operating system" instead of a pile of habits 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.

One file the assistant loads at the start of every session, and which overrides its default behaviour. It is the contract everything else references. Layered: communication style, autonomy, research order, skill routing, spec rules, structure and build, strict rules, anti-slop, post-change discipline.

The core idea is always-loaded and short. It is not a wiki: long playbooks live in docs/, and the constitution only references them in a line. Inside it sits the routing table - which slash skill for which size of task. The filename depends on the tool - CLAUDE.md, AGENTS.md, a Cursor rule, GEMINI.md - but the idea is one.

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.

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

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.

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 its own memory: a researcher's notes don't crowd an implementer's index.

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 small deterministic change (≤3 files, no new public types, no migration or DI wiring) ships as a three-section primitive and is implemented directly; everything else runs the full pipeline. 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.

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, from git history, or fix recipes - 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.

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.

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.

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.

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 repository. 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 project - the quick path

In a minute. Ask your agent, right in the chat, to download the kit archive, unpack it locally, and import 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 repository and import what fits it:

1. Draft a CLAUDE.md (or my tool's equivalent rules file) that adopts the method, with every
   placeholder filled from this repo: 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 ticket-id scheme.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /verify, /git, /review) and which role agents are worth adding here, and say
   why for each.
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.

Quick and file-based, but less reproducible than path C: no explicit inventory/merge step with a stop before writing.

C · An existing project - the canonical path

Download the kit, hand your agent the folder together with merge-prompt.txt, and say "Merge the Universal Agent Kit into this repo". The prompt forces the agent to first take an inventory (what you already have, what's new, where it conflicts), present a merge plan, and stop - yours always wins, nothing is overwritten silently. You approve; it applies and fills <PLACEHOLDER> tokens from your repo.

Any tool

Every agent reads its own rules file - the idea is one, 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 / 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.
• Git checkpoints. Commit before and after a task so a revert is one move away.
• Encode the repeatable. Turn a recurring prompt into a slash command or a rules file and check it into the repo so the whole team has it.
• 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 (the successor to Gemini CLI)

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.

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. 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/, а конституція лише посилається на них одним рядком. Усередині ж - таблиця маршрутизації: яка slash-навичка на який розмір задачі. Ім'я файлу залежить від інструмента - CLAUDE.md, AGENTS.md, правило Cursor, GEMINI.md, - але ідея одна.

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

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

/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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

This is a fresh or mostly empty repository. 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 · Наявний проєкт - швидкий шлях

За хвилину. Попроси агента прямо в чаті завантажити архів kit-а, розпакувати його локально й імпортувати найкорисніше:

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 repository and import what fits it:

1. Draft a CLAUDE.md (or my tool's equivalent rules file) that adopts the method, with every
   placeholder filled from this repo: 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 ticket-id scheme.
2. Recommend which skills (/research, /spec, /spec-tech, /spec-dev, /spec-check, /spec-fix,
   /quick, /fix, /verify, /git, /review) and which role agents are worth adding here, and say
   why for each.
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: тут немає явного merge-процесу з інвентарем і зупинкою перед записом.

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 / GEMINI.md / свій аналог; ролі вставляються як системні промпти, навички - як файли-промпти, на які посилаєшся.
• Методологія в docs/ взагалі не залежить від інструмента - це просто Markdown.

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

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

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

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

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

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

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

• Anthropic · Claude: Claude Code best practices · Effective context engineering
• OpenAI · Codex: Codex docs і quickstart
• Google · Antigravity: antigravity.google · Docs (наступник Gemini CLI)

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

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

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