Свои ИИ-агенты: как создать и настроить агента под свой проект

Любой кодинг-агент из коробки работает одинаково: открыли репозиторий, дали задачу — он читает файлы, правит код, гоняет тесты. Через неделю в одном проекте тот же Claude Code начинает вести себя иначе, чем в соседнем: в одном он сам подсказывает, где расставить @decorators, в другом — пытается переписать всю архитектуру на свой вкус. Разница — не в модели, а в том, что вы положили рядом с кодом: файлы-инструкции, описания ролей, процедуры и правила.

Этот текст — каркас: как создать ИИ-агента под конкретный проект, где живут его инструкции, роли и права. Не про автономные ночные прогоны (им посвящена отдельная статья), не про личного оркестратора из многих агентов (разобрано здесь). Здесь по шагам: где живут инструкции проекта, как объявить сабэдженты, скиллы и плагины в Claude Code, OpenCode и Codex, как задать правила и границы доступа, подключить модель и MCP-серверы, а потом тестировать и улучшать конструкцию. Версии инструментов — на момент публикации, 08.09.2026.

Что такое «свой агент» и из чего он состоит

Своего агента не нужно писать с нуля. Это не отдельная программа и не своя модель — это обычный кодинг-агент (Claude Code, OpenCode, Codex, Cursor), который вы настроили под проект: отдали ему память о конвенциях кодовой базы, описали роли, которым он делегирует подзадачи, упаковали повторяемые процедуры и ограничили права.

Свой ИИ-агент — рабочий инструмент, а не витрина: каждый слой конструкции решает конкретную проблему, которая возникает при долгой работе агента в одной кодовой базе.

Собранный таким образом агент — четыре слоя поверх модели:

1. Контекст проекта — файлы CLAUDE.md / AGENTS.md: что это за код, как собрать, какие команды тестов, каких стилей придерживаться. Читается при старте каждой сессии.
2. Роли — сабэдженты: отдельные агенты со своим системным промптом, набором инструментов и даже своей моделью под конкретный тип задач (ревью, работа с базой, поиск).
3. Процедуры — скиллы: многошаговые инструкции, которые подгружаются только когда нужны.
4. Границы — правила и разрешения: какие инструменты доступны роли, что требует подтверждения, а что запрещено.

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

Кейс-якорь: 164 строки CLAUDE.md и скиллы для игры на 76 000 строк

Показательный пример настройки агента под один проект — игра по мотивам Mario Galaxy, которую разработчик под ником Supertommy собрал с Claude Code за 53 дня: 731 коммит, около 95% кода написал агент, но не сам по себе — автор вёл его через файлы проекта (страница проекта — supertommy.com, описание процесса — Show HN-тред от 1 апреля 2026). Кейс старше обычного трёхмесячного окна свежести, но остаётся одним из самых подробных публичных разборов такой настройки:

My process for every feature: braindump what I want, relevant technical details, and “does this make sense?” into the chat. Largely unorganized. I built custom Claude Code skills like /lets-build:plan that spawns sub-agents to research the codebase first, then asks me clarifying questions.

Мой процесс для каждой фичи: выгрузить в чат, что я хочу, релевантные технические детали и «так ли это работает». В основном без структуры. Я собрал собственные скиллы Claude Code вроде /lets-build:plan, которые сначала спавнят сабэджентов для исследования кодовой базы, а потом задают мне уточняющие вопросы.

— Supertommy, Show HN

Ключевое в его описании — не сами промпты, а то, что к концу проекта сложилось в репозитории:

• файл CLAUDE.md на 164 строки, в который он сносил жёсткие ограничения, выстраданные на отладке («каждое ограничение стоит токен-массакры», описывает он процесс);
• отдельные скиллы под каждый тип работы: /lets-build:plan — планирование с исследованием кодовой базы, /review-plan и /code-review — ревью планов и кода, /ecs-plan и /ecs-review — борьба с конкретной ошибкой модели (агент упорно писал ООП-стиль там, где проект требовал data-oriented ECS);
• 87 файлов планов по 2–3 страницы, чтобы сессия оставалась «перезапускаемой».

Это и есть собственный агент в действии: модель одна, а поведение на 90% определяется файлами в репозитории. Ниже — как собрать такой же каркас с нуля, от первого CLAUDE.md до теста готовой конструкции.

Шаг 1. Положите контекст проекта в файл-конвенции

Первый слой — файл-конвенции, который агент читает при старте каждой сессии. Без него агент каждый раз начинает с нуля и угадывает правила по коду.

Какие файлы читает какой инструмент, на момент публикации:

Инструмент	Файл проекта	Примечание
Claude Code	CLAUDE.md	AGENTS.md нативно не читает — подключается импортом
OpenCode	AGENTS.md	при отсутствии — fallback на CLAUDE.md
Codex CLI	AGENTS.md	нативная поддержка
Cursor	AGENTS.md, .cursor/rules/*.mdc	оба механизма, плюс командные правила
Gemini CLI, Windsurf, Aider	AGENTS.md	настраивается

Подробный разбор формата и матрица по всем инструментам — в статье «AGENTS.md: файл-конвенций». Здесь — практика: что положить в файл, чтобы агент стал «своим».

Стартовый файл проще всего сгенерировать: /init в Claude Code и OpenCode анализирует репозиторий и создаёт файл с командами сборки, тестами и конвенциями, которые нашёл в коде. Дальше файл дорабатывается руками — туда добавляется то, что агент из кода не выведет.

Три правила из документации Claude Code, которые работают на практике (memory):

• Цель — до 200 строк на файл. Файл читается в контекст в начале каждой сессии и занимает токены. Всё, что выросло в многошаговую процедуру, переезжает в скилл.
• Пишите проверяемое. «Используй отступы в 2 пробела» работает, «форматируй код аккуратно» — нет. «Запусти npm test перед коммитом» работает, «тестируй изменения» — нет.
• Держите инструкции конкретными. Путь «API-обработчики живут в src/api/handlers/» надёжнее, чем «держи файлы в порядке».

Например, так выглядит файл проекта, который уже делает агента «своим»:

# CLAUDE.md

## Команды
- Установка зависимостей: pnpm install
- Запуск dev-сервера: pnpm dev
- Тесты: pnpm test (без флагов)

## Структура
- packages/core/ — разделяемый код, экспорты через workspace-имена (@my-app/core/example)
- infra/ — инфраструктура: storage.ts, api.ts, web.ts

## Стиль
- TypeScript strict mode
- Одинарные кавычки, без точек с запятой
- Функциональные паттерны вместо классов

Если в проекте уже есть AGENTS.md, а вы работаете в Claude Code — подключите его импортом: первая строка CLAUDE.md вида @AGENTS.md разворачивает общий файл при старте. Так конвенции не приходится держать в двух экземплярах (механика импорта разобрана в статье про AGENTS.md).

Шаг 2. Соберите роли: сабэдженты и агенты

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

Subagents are specialized AI assistants that handle specific types of tasks. […] Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.

Сабэдженты — это специализированные ИИ-ассистенты под конкретные типы задач. […] Каждый сабэджент работает в собственном контекстном окне со своим системным промптом, доступом к инструментам и независимыми разрешениями.

— Документация Claude Code: Create custom subagents

Зачем выносить работу в отдельные роли: результаты поиска, логи и ревью не засоряют основную сессию — сабэджент делает работу в своём контексте и возвращает только итог. Плюс каждой роли можно ограничить инструменты и назначить свою модель (дешёвую Haiku для поиска, флагман для реализации).

Как объявить сабэджента в Claude Code

Сабэджент — это обычный Markdown-файл с YAML-фронтматтером в папке .claude/agents/ (для одного проекта) или ~/.claude/agents/ (для всех проектов на машине). Файл такого вида:

# .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for correctness and security. Use after a feature is implemented or when the user asks for a review.
tools: Read, Grep, Glob
model: sonnet
---

You are a code reviewer for this project. Check the diff for:
- logic errors and missing edge cases
- security issues (unvalidated input, hardcoded secrets)
- tests that would catch the change
Report findings as a numbered list. Do not edit files.

Поля, которые чаще всего задают (документация):

• name — имя, по которому агента вызывает основная сессия или вы (@code-reviewer);
• description — то, по чему модель решает, делегировать ли задачу; описания держите короткими — при суммарном объёме описаний сабэджентов свыше 15 000 токенов Claude Code покажет предупреждение при старте;
• tools — ограничение доступа (например, ревьюеру не нужны Write и Edit);
• model — модель роли, если она отличается от модели основной сессии;
• системный промпт после фронтматтера — сама инструкция, которая грузится только при запуске роли.

Встроенные роли Claude Code — Explore (только чтение, поиск по коду), Plan (исследование в plan-режиме) и общего назначения. Своя роль с именем Explore перекроет встроенную. Управлять сабэджентами в старой версии можно было через /agents, но начиная с v2.1.198 мастер удалён — файлы редактируются напрямую, попросить создать файл можно и самого Claude.

Роли в OpenCode: primary-агенты и субагенты

OpenCode разделяет агентов на два типа (документация): primary-агенты, с которыми вы общаетесь напрямую (по умолчанию их два — Build со всеми инструментами и Plan без права правок), и субагенты — специализированные ассистенты, которых primary-агент вызывает автоматически или вы — через @упоминание. Встроенные субагенты: General (многошаговые задачи с инструментами), Explore (быстрый read-only поиск) и Scout (чтение внешних документаций).

Свой агент объявляется в opencode.json или отдельным Markdown-файлом:

# .opencode/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on:
- code quality and best practices
- potential bugs and edge cases
- security considerations
Report findings without editing files.

Имя файла становится именем агента (review.md → агент review). Для быстрого старта есть интерактивная команда opencode agent create: она спросит, куда сохранить агента (глобально или в проект), что он должен делать, и соберёт системный промпт и список разрешений.

Codex: без отдельных файлов-ролей

У Codex CLI нет отдельного механизма файлов-ролей в духе .claude/agents/. Роли и контекст задаются иначе: AGENTS.md — постоянный контекст проекта (нативная поддержка, документация), скиллы — для повторяемых процедур (документация), а персональные настройки — в ~/.codex/config.toml. Репозиторий самого Codex открыт (Apache-2.0), и его README — хорошая точка отсчёта: инструмент позиционируется как «лёгкий кодинг-агент, который живёт в терминале».

Если сравнивать подходы: Claude Code и OpenCode дают вам гранулярные роли с собственными промптами и моделями, Codex — более плоскую модель «контекст (AGENTS.md) + процедуры (скиллы) + разрешения в конфиге». Для одного проекта это не проблема, о чём ниже.

Шаг 3. Упакуйте повторяемые процедуры в скиллы

Когда раздел CLAUDE.md разрастается из факта («проект на TypeScript») в процедуру («как собрать релиз: прогнать тесты, поднять версию, собрать changelog из merged PR»), его пора выносить в скилл. Документация Claude Code объясняет разницу так:

Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md content, a skill’s body loads only when it’s used.

Создайте скилл, когда снова и снова вставляете одни и те же инструкции, чек-листы или многошаговые процедуры в чат, или когда раздел CLAUDE.md вырос в процедуру, а не остался фактом. В отличие от содержимого CLAUDE.md, тело скилла загружается только при использовании.

— Документация Claude Code: Extend Claude with skills

Это ключевое преимущество скиллов: описание скилла (имя + короткое описание) висит в контексте постоянно, а само тело из десятков строк подгружается только когда скилл реально вызывается. Длинный справочный материал почти ничего не стоит, пока он не понадобился.

Скилл — это папка с файлом SKILL.md:

# .claude/skills/summarize-changes/SKILL.md

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed or wants a commit message.
---

## Current changes
!`git diff HEAD`

## Instructions
Summarize the changes above in two or three bullet points, then list risks:
missing error handling, hardcoded values, tests that need updating.

Строка !git diff HEAD` подставляет живой вывод команды в промпт до того, как модель увидит содержимое скилла (в документации это называется dynamic context injection). Вызывается скилл по имени —/summarize-changes`, либо модель сама загрузит его, когда описание подойдёт к задаче.

Раскладка скиллов в разных инструментах на момент публикации:

Инструмент	Папка скиллов	Особенность
Claude Code	.claude/skills/<имя>/SKILL.md (проект), ~/.claude/skills/ (пользователь)	старые /commands работают как скиллы
OpenCode	.opencode/skills/, .claude/skills/, .agents/skills/	ищет в нескольких совместимых папках
Codex CLI	скиллы по документации	поддерживает скиллы Cursor
Cursor	нет скиллов в этом смысле	повторяемые процедуры — правила .mdc

Формат SKILL.md следует открытому стандарту Agent Skills, который поддерживают несколько инструментов сразу — поэтому скилл, написанный для Claude Code, во многом работает и в OpenCode (последний ищет .claude/skills/ как одну из совместимых папок).

Шаг 4. Задайте границы: правила, инструменты и разрешения

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

В Claude Code границы задаются полем tools в файле сабэджента (ревьюеру — только Read, Grep, Glob) и permission-режимами основной сессии. В OpenCode — полем permission с тремя значениями на инструмент: allow (разрешено без вопросов), ask (спросить) и deny (запрещено):

# .opencode/agents/review.md
---
description: Reviews code without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
---
Only analyze code and suggest changes.

Разрешения в OpenCode можно задавать не только на инструменты, но и на конкретные bash-команды, и на скиллы (паттерны internal-*: deny), и на целые MCP-серверы (mymcp_*: deny — запрет всех инструментов сервера). Правила в Cursor работают похоже, но через другой механизм: файлы .cursor/rules/*.mdc с фронтматтером, который определяет, когда правило применяется (документация):

# .cursor/rules/backend.mdc

---
globs: src/services/**/*.ts
alwaysApply: false
description: Conventions for backend services
---

- Валидируйте входные данные на границе сервиса
- Возвращайте структурированные ошибки с code и message

Три способа применения в Cursor: alwaysApply: true — всегда, globs — только для файлов под паттерном, «умное» — по описанию, когда агент сам решит, что правило релевантно. Командные правила (Team Rules) на тарифах Team/Enterprise принудительно применяются ко всей команде и имеют приоритет над проектными.

Шаг 5. Подключите модель, MCP-серверы и плагины

Собранный каркас — это ещё не агент, а обвязка. Работает он на модели и инструментах, которые вы подключили.

Модель на роль. Роли можно развести по моделям: быстрая и дешёвая для поиска и чернового анализа, флагман — для сложной реализации. В Claude Code это поле model в файле сабэджента; в OpenCode — model в конфиге агента с форматом провайдер/модель (anthropic/claude-sonnet-4-20250514, opencode/gpt-5.1-codex и т.д.). Один и тот же конфиг роли переносится между провайдерами, если формат модели совпадает.

MCP-серверы подключают агента к внешним инструментам и данным — браузеру, базе, внутреннему API. Это отдельная тема (старт — в статье «Что такое MCP», подборка — «Лучшие MCP-серверы»). Для своего агента важно одно: MCP-серверы можно ограничивать по ролям. Claude Code умеет скоупить MCP-сервер на конкретного сабэджента, OpenCode — запрещать целый сервер через wildcard в permissions. Не подключайте к роли-исследователю MCP-сервер с записью в базу, если ему нужен только поиск по ней.

Плагины — самый «продуктовый» способ распространять настройку: плагин может содержать сабэджентов, скиллы, хуки и правила одним пакетом. У Claude Code есть каталог плагинов и команда их установки; сабэджент, оформленный как плагин, легко раздать команде через marketplace. Codex поддерживает переносимые плагины (с 0.147.0) и импорт скиллов из Cursor.

Сравнительная таблица: как объявляются агенты и инструкции

Свести все механики в одну картину сложно, потому что каждый инструмент называет одно и то же по-своему. Таблица ниже — по официальной документации на момент публикации:

Механизм	Claude Code	OpenCode	Codex CLI	Cursor
Контекст проекта	CLAUDE.md (импорт @AGENTS.md)	AGENTS.md (+fallback CLAUDE.md)	AGENTS.md	AGENTS.md, .cursor/rules/*.mdc
Свои роли/агенты	.claude/agents/*.md (YAML frontmatter)	opencode.json или .opencode/agents/*.md	нет отдельных файлов-ролей: AGENTS.md + скиллы + конфиг	один агент; поведение сужается правилами
Процедуры	.claude/skills/<имя>/SKILL.md	.opencode/skills/, .claude/skills/	скиллы (отдельный документ)	правила .mdc с alwaysApply/globs
Ограничение доступа	tools в сабэдженте, permission-режимы	permission: allow/ask/deny по инструментам, командам, MCP	политики в конфиге	alwaysApply/globs, Team Rules
MCP	своя команда подключения; скоуп на сабэджента	конфиг MCP; deny-паттерны на серверы	конфиг MCP	настройки MCP в приложении
Модель на роль	model: в файле сабэджента	model: в конфиге агента	модель в config.toml	выбор в правилах/промпте

Механики быстро меняются: перед тем как собирать каркас под команду, сверьтесь с актуальной документацией вашего инструмента.

Как тестировать и итерировать

Собранный агент проверяется не «в теории», а на реальных задачах проекта. Простой цикл итераций, который сходится на практике:

1. Начните с малого. Один CLAUDE.md с командами и структурой + одна роль под вашу самую частую задачу (ревью, тесты или работа с базой). Не стройте каркас из десяти сабэджентов за вечер.
2. Дайте агенту задачу, у которой есть объективный критерий. «Проверь, что тесты проходят и покрытие не упало» — критерий есть; «посмотри код и предложи улучшения» — нет.
3. Правило одной ошибки. Увидели, что агент повторяет одну и ту же ошибку второй раз — запишите правило в CLAUDE.md или в описание роли. Поймали ошибку на ревью кода — туда же. Так файл-конвенции растёт от реальных промахов, а не от «всякого полезного, что пришло в голову».
4. Проверяйте, что инструкции читаются. В Claude Code — команда /context, в выводе которой видно список загруженных Memory files. Скилл не подхватился, агент его не видит — ищите ошибку в фронтматтере (name и description обязательны, имя должно совпадать с именем папки).
5. Следите за контекстом. Скиллы должны вытеснять из CLAUDE.md процедуры, а не дополнять их. Документация рекомендует держать CLAUDE.md в пределах ~200 строк: файл читается каждую сессию, и каждая лишняя строка — это токены и снижение точности следования инструкциям.

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

Российские реалии

Собирать своего агента из России можно, но каждый инструмент вносит свои ограничения. По состоянию на 08.09.2026:

Claude Code. Россия отсутствует в списке поддерживаемых стран Anthropic (supported countries): нужен VPN, аккаунт с номером поддерживаемой страны, оплата — зарубежная карта, крипта или посредник. Настройка файлов CLAUDE.md, сабэджентов и скиллов при этом ничем не отличается — она локальная и в конфигурацию не упирается. Детали установки и оплаты — в статье «Как установить Claude Code».

Codex CLI. Ставится из РФ штатно, но вход через ChatGPT требует VPN (OpenAI ограничила российские IP ещё в декабре 2022 года — подробности на Habr). Бесплатный план не требует карты; платные лимиты — через зарубежную карту или посредника (реальный опыт оплаты ChatGPT из России — Habr, компания Tehrevizor). Русскоязычных разработчиков, которые подключают к Codex не OpenAI, а российских провайдеров, тоже хватает: разбор подключения Codex CLI к инференсу Яндекса — Habr.

OpenCode. Работает из РФ без VPN, бесплатные модели — из коробки (реальный опыт — в статье «Как стать вайбкодером»). Это самый беспроблемный путь собрать своего агента из России, если не нужны именно флагманские модели Claude или GPT.

Cursor. Сайт и приложение доступны из РФ без VPN, но оплата платных тарифов картами РФ невозможна; бесплатного Hobby-плана для знакомства достаточно.

Честное предупреждение: разборов именно настройки своих сабэджентов и скиллов на русском на момент публикации почти нет — тема свежая, а основная масса RU-материалов про агентный кодинг останавливается на установке и первых промптах. Общие вводные — в статье «Что такое агентный кодинг», практика контекста — «Контекст ИИ-агента».

Честные ограничения

Каркас из файлов решает многое, но не всё. Что важно держать в голове:

• Инструкции — это контекст, а не принуждение. CLAUDE.md и системный промпт роли влияют на модель, но не гарантируют поведение. Если действие нужно заблокировать железно (например, запрет push в прод), файла мало — нужен хук (PreToolUse в Claude Code) или политика исполнения.
• Описания ролей съедают контекст. У Claude Code предупреждение начинается при суммарных описаниях сабэджентов свыше 15 000 токенов. Каждая новая роль увеличивает постоянную нагрузку на контекст — за это и приходится платить «удобством».
• Файлы не чинят слабую модель или размытую задачу. Агент-ревьюер на дешёвой модели найдёт меньше, чем основная сессия на флагмане. Свой агент усиливает дисциплину процесса, а не магически поднимает качество ответов.
• Кейс Mario Galaxy — это экстремальный сценарий. 164 строки правил и десятки скиллов для одной игры — результат месяцев отладки, а не стартовый шаблон. Копировать его объём ради объёма не стоит.
• Механики быстро меняются. Стандарт AGENTS.md и формат скиллов консолидируются (к этому идёт agents.md и Agent Skills), но конкретные команды и поля у каждого инструмента свои и обновляются часто. Проверяйте документацию перед настройкой команды.

Вывод

Собственный ИИ-агент — это не новая модель и не самописный инструмент, а ваш кодинг-агент, которому вы отдали память о проекте, роли, процедуры и границы. Сборка укладывается в пять шагов: файл-конвенции с командами и структурой, пара сабэджентов под самые частые задачи, скиллы для повторяемых процедур, ограничение доступа и подключение модели с MCP-серверами. Дальше — цикл: заметили повторяющуюся ошибку, записали правило, проверили на задаче с объективным критерием.

Начать стоит с одного файла и одной роли — этого достаточно, чтобы почувствовать разницу между «агентом из коробки» и агентом, который знает ваш проект.

Дальше по теме: AGENTS.md — файл-конвенций, что такое агентный кодинг, контекст ИИ-агента, сабэдженты и @mentions в Claude Code, мультиагентные workflow, что такое MCP.

---