Разработка с помощью агентов: гайд для новичков

Этот гайд для тех, кто уже поставил себе агента (Claude Code, Pi, opencode — без разницы), погонял его по запросам «сделай красиво» и понял, что между «вау» и «рабочий проект» есть дистанция. Она заполняется устройством контекста: agents.md, доки, скиллы. Ниже — как это всё работает, какая вокруг этого выросла индустрия мусора, и как строить свой сетап, чтобы в него не влипнуть.

Главный принцип, который проходит через весь текст, один: если агент что-то игнорирует, делает не так, срёт лишним — почти всегда виновато окружение. Лучше — переформулировать то, что уже есть.

1. Как всё работает: agents.md и скиллы

1.1 agents.md — это препромпт

agents.md — файл, который агент видит всегда, в каждой сессии, ещё до твоего первого сообщения. Это прямой предшественник твоего промпта, и писать его надо соответственно: коротко, по делу, списком.

Что туда кладётся:

• суть проекта в 2–3 предложениях — чтобы агент понимал, вокруг чего крутится работа;
• гайдлайны списком;
• ссылки на доки — не содержимое, а именно ссылки. Агент сам решит, когда раскрыть;
• факты об окружении: какие тулы установлены.

С фактами об окружении отдельная история, потому что это самый дешёвый выигрыш во всём сетапе. Если у тебя стоит pandoc — одна строка в agents.md, и агент перестанет разархивировать вордовские файлы говнокодом на питоне. Он не знал, что pandoc существует в твоём окружении, — теперь знает и просто им пользуется.

Про игнорирование доков. Аргумент «он всё равно их не читает, как карта ляжет» — правда, но вывод из него делают неправильный. Если модель стабильно не читает док, который для задачи нужен, — у дока неверное описание: формулировка не зацепила семантику таски. Останавливаешь модель и просишь её же переформулировать. Дальше читает. Это работает везде: у доков, у скиллов, у гайдлайнов — объём не лечит, лечит формулировка.

1.2 Доки: сетка мелких файлов

Схема простая:

1
2
3

agents.md                # гайдлайны + ссылки + суть проекта
/docs/*.md               # специфичные доки, грузятся по необходимости
skills/<name>/SKILL.md   # скиллы (формат project-specific skill — см. доку харнеса)

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

Теперь про то, кто эти доки пишет. Писать руками с нуля — дорого и лень, поэтому генеришь агентом. Но готового с первого раза не жди: доки из агента крайне редко выходят хорошими сразу. У моделей устойчивый биас на объём вместо сути — вместо примеров usage (которых около нуля) они насирают технических деталей, которым в доке не место, истории изменений, пофикшенных багов и рассказов о том, как круто было это разрабатывать.

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

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

1.3 Скиллы

Со скиллами всё устроено иначе: в контекст попадает только name + description. Тело грузится, когда агент решит его открыть. description — обоснование для агента, зачем читать тело скилла. Правило простое: description описывает, что это и когда его применять.

Такой description агент заигнорит и пойдёт городить своё барахло — соберёт не туда, в неверном окружении:

1

description: Собрать проект скриптом build.py на C++ используя CMake 3.14

Такой работает:

1

description: Сборка проекта Megaclicker. Настраивает корректное окружение. Используй при любой сборке target'ов, проверке компиляции, подготовке к тестам, изменениях в коде

Первый — что делает скрипт. Второй — когда его звать, и почему.

Чаще всего скилл — это обёртка над скриптом или просто инструкция: как ходить во внешнюю систему, как правильно звать билд и тесты. Вот скрипт, который что-то делает — и описание, когда и как его применять.

Когда звать, с какими входами, в каком порядке — это usage, он живёт в теле скилла. Технические детали скрипта модели не нужны: она либо уже умеет пользоваться тулзой, либо прочтёт код и хелп.

Делать скиллы — у той же LLM, с которой работаешь: описал интенцию своими словами («железяка, хочу скилл, чтобы спека») — получил черновик. Но принять высер нельзя, и это не формальность: без пинка модель систематически насирает техдеталей вместо usage — история изменений, пофикшенные баги, инфа о переменных окружения, а ещё чаще — пересказ твоей текущей таски в контексте этого инструмента. Примеров применения при этом около нуля. Причём срёт в самое больное место — в description.

Поэтому читаешь, что получилось, и либо правишь сам, либо пинаешь: «кратко», «меньше шагов», «не добавляй воображаемые примеры», «use-cases, а не как оно работает». Дошлифовать черновик всегда дешевле, чем писать с нуля.

А если агент всё-таки не читает скилл там, где он нужен — фиксится так же, как всё в этом гайде: reword description, не расширять. Можно агентом.

И последнее — гигиена. Доверие к чужим скиллам должно быть на уровне доверия к warez-софту со стремных сайтов: открыл, прочитал, понял, что там и зачем, — потом ставишь. Причина простая: чужой скилл написан под чужие кейсы. Автор никогда не видел твой проект, но его скилл выставляет рандомные требования — как делай, что подключай, какие артефакты хранить и где. В итоге в проекте оказываются вещи, которые ты не закладывал — можно знатно удивиться, что твой /handoff потребовал сменить язык проекта на венгерский.

handoff/grill-me/spec-driven работают просто если попросить, скилл под них просто не нужен. Можешь почитать популярные реализации, там буквально сделай handoff + барахло от автора. (Все скиллы от mattpocock это буквально: сделай handoff, но сложи его в /tmp/, удали креды, перечисли скиллы которые использовать следующему агенту)

1.4 Память между сессиями

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

Единственное, что реально работает, — инструкции в доках на сложные кейсы: как сделать фичу, как деплоить, как устроена сериализация PDF, какие в проекте неочевидные места. Это знания о проекте — они переживают сессию и любой компакт.

Всё остальное из мира «памяти агентов» — варианты, которые люди пробуют, но которые не работают:

• спека и план с чекбоксами — чекбоксы жрут много внимания, а толку никакого: агент постоянно бегает смотреть галки, пока контекста мало, а когда его много — забивает;
• файл прогресса («где остановился, следующие шаги») — агент его не ведёт, а если ведёт — пишет не то и не про то; поддерживать руками дороже, чем заново рассказать;
• грабли и техдолг комментами в коде — комментарии не читаются в следующих сессиях и сами устаревают; если грабля важная — ей место в доке. Исключение — «почему мы так решили» внутри скриптов скиллов: скрипты агент редактирует чаще всего, и сохранившаяся причина решения не ебёт ему голову при каждой правке;
• инжекты и «журналы самонаблюдения» — переизобретение файла прогресса с механикой, которую надо поддерживать;
• векторные базы для кодинга — раг-сосательство: RAG настолько мёртв, что его удаляют из харнесов. Технология 25-го года, когда контекстные окна были 8к.
• hermess — хермесс из коробки ведет заметки о пользователе и подстраивается под него. Жаль, что он занимает позорное последнее место во всех бенчмарках, жрёт х4 токенов от других харнесс и буквально хуже чем vscode-extensions. Оказывается прошлые беседы почти никогда не несут полезный смысл для следующей.

2. Единственно верная методология по работе с агентами /s

Success-Oriented Software Architecture & Logic (SOSAL). Суть — насмешка над методологиями по названию и нагенерированными скиллами для разработки ПО, которые их автор даже не удосужился прочесть, но свято уверен, что они «в чём-то помогают». Безумные архитектуры, сложные дизайнеские системы которые никто не понимает (включая автора), но они точно делают заебись.

SOSAL — имя-пустышка. Под неё любая модель честно нагенерит 1200 слов — неотличимых от SOLID или FPF. Проверь сам: GLM 5.2 (https://rentry.co/sr7c2bf9) по одному имени «SOSAL» выдал методологию про failure path и fallback'и — неотличимую от авторских, получше многих «магазинных» скиллов с тысячами звёзд на ГХ. Любой может сесть и накидывать базворды в сетку строя свою методологию, в итоге получая 10 тысяч слов которые в сущности ни значат ничего.

Сосал-тест: если суть артефакта не сжимается в пару строк без потерь, а хозяин не может объяснить его своими словами — это сосал. И никакое «нахуя палить годноту» не решает.

И если всмотреться — аббревиатура тут симптом. Сосал — про извечную любовь людей к изобретению собственного ахуенного фреймворка. И чем меньше человек сделал, тем грандиознее методология. На выходе — оверинжинирная параша, которая красиво звучит и ничего не предписывает: IKEA, FIRST PRINCIPLES FRAMEWORK, NO HALLUCINATION PROTOCOL, spec-driven, SOLID, YAGNI, KISS, GRASP, SDD, TDD, DDD, чистый код — сосалы разной степени успешности. Даже KISS, «успешный сосал», держится только на трактовках: у каждого в голове своя. Люди точно так же, как нейросети, генерируют содержание по названию.

Отсюда SOLID — SOSAL своего времени. И практическое следствие: 250КБ скилла spec-driven с Гитхаба заменяются двумя предложениями — «сперва планируем правку, уточняем детали — потом исполняем. Если есть вопросы в процессе — задавай». Это и есть те 90% смысловой нагрузки, которые несут исторические справки в его теле. Бонус: от твоего кода больше не требуют (капсом, кстати) CLI-интерфейс.

• NEDOSOSAL — отдал ИИ все решения, которые должен был принять сам. Удивляешься, что по запросу «сделай игру» получаешь браузерку? Это оно.
• SOSAL — окружил работу размазанным на 20 КБ «хорошо делай, плохо не делай».
• PERESOSAL — слишком хорошо знаешь, как надо, и заставляешь модель читать простыни законов и инструкций. Продуктивность от этого падает.

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

Почему слоп процветает? Потому что модели сами натренированы считать объём за качество: VERBOSITY IS DILIGENCE. Типичный кейс: агент смотрит на чужую 13.7 МБ «методологию» и фанатеет от её крутости. Просишь его пересказать первые десять абзацев — и выясняется, что суть 250КБ текста в одном предложении: «рядом с цифрой в требованиях надо писать, почему такая цифра выбрана». То же происходит, когда модель генерит скилл: без явного пинка она пишет много и подробно, и это выглядит как добросовестность. Индустрия это и продаёт: объём, который маскируется под содержание.

Я топлю — за личные сосалы, разработанные и желательно прочитанные тобой, а не взятые из интернета.

3. Минимал-сосал: реальные рекомендации

Теперь соберём всё в подход. Он выглядит подозрительно просто:

1
2

agents.md -> /docs/SpecificGuide.md -> /docs/MoreSpecificGuide.md
skills/*

• В agents.md: гайдлайны списком, ссылки на доки, суть проекта.
• В /docs/: сетка мелких доков под конкретные темы — сериализация, деплой, окружение.
• В skills/: обёртки над скриптами для билда, тестирования, похода на сервак.

Гайдлайнов по стилю кода у меня нет. Вообще. Агенты из коробки пишут достаточно хорошо, чтобы ваши ценные сосалы только мешали. Пункты нужны под конкретную модель: deepseek4-pro, например, любит срать 4-строчными абзацами над геттерами — пишешь ему «не пиши очевидные комментарии», и он поумерит пыл. Но тот же совет для qwen3.8 уберёт комментарии из кода вовсе, что плохо. Поэтому и нет универсальных правил стиля.

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

Типичная секция Documentation:

1
2
3

- [Как обновлять доку](docs/update_docs.md)
- [Как заказать на Озоне](docs/OzonDocs.md)
- [Как читать и постить на дваче](docs/2ch-works.md)

3.1 Как писать гайдлайны

Гайдлайны — самое мелкое, но самое часто портящееся звено. Вот образец здорового agents.md в части гайдлайнов:

1
2
3
4
5

Guidelines:
- Не трогай гит если не просят
- Если есть вопросы уточняй у пользователя, а не доводи до конца одну из версий
- обновляй неактуальные документы (краткость - важна)
- по завершении работы позвони бабушке - она ждёт твой звонок

С таким набором до PERESOSAL быстро не докатишься. Реккомендации:

1. Пункт добавляется только после реального проёба. Агент сделал что-то не так -> формулируешь гайдлайн. Не пиши правила про ситуации, которые ещё не случались.
2. Калибруй слова, а не добавляй абзацы. Пункт «не сработал» почти никогда не означает «не услышан» — он означает «понят не так». Переформулируй существующее. Расширение объяснениями порождает вторую интерпретацию, потом третью — и вот у тебя в agents.md notarized PERESOSAL.
3. Никаких NO HALLUCINATION PROTOCOL. В 2026 году нормальная модель в нормальном агенте нормально делает сама. Скилл и гайдлайн оправданы, только когда ты хочешь, чтобы она делала ненормально — то есть отличаться от дефолтного поведения. Против галлюцинаций нет гайдлайна, есть тесты и проверка.
4. Не пиши того, что не можешь сформулировать. «Пиши чистый код» — пустое место. Если тейк не формулируется во что-то осмысленное, он не готов становиться правилом.
5. Финальная проверка: если твои гайдлайны можно сжать в «делай хорошо, а плохо не делай» без потери информации — они уже сжались. Режь.

Не превращай гайдлайны в док. Доки — в доках.

Reword, not expand — главный принцип.

4. Ре-клеймер

Всё выше — личный опыт. Не бенчмарки, не наука: у меня нет замеров, и, что важнее, их нет ни у кого из тех, кто продаёт методологии и скилл-пакеты. Особенно их нет у растущей звезды гитхаба на 350к звёзд, лучшей-на-свете-вовсе-не-SOSAL, с очередной говнометодологией на 2 мегабайта текста.

Я использую pi и доволен, но всё это применимо к любому харнесу. Структура папок зависит от харнес (папка скиллов для pi живёт соответственно в /.pi/skills, я туда же доки кладу и репо отдельный инициализирую отделяя комитты доков/скиллов/скриптов от реповских - но это мой личный подход)

Учти срок годности: «нормальная модель делает сама» — величина, меняющаяся от релиза к релизу. То, что в сентябре 2026 не требует скилла, год назад требовало трёх, а через год может стать анти-паттерном. Переоценивай свой сетап, когда переезжаешь на новую модель, — не таскай старые пункты на вере.