Половина провалов первого агента случается до первого запроса - в момент, когда вы открываете папку с файлами и говорите «разберись». Эти десять приёмов про то, что сделать с папкой заранее, чтобы агент не путался: как разложить вход, что дописать к тяжёлым документам, где положить правила и эталон результата.
Павел Доронин · AI Community · разбор с офлайн-сессии
Первые три - с флипчарта офлайн-сессии, остальные семь добавлены из практики. У каждого хака - схема и готовая формулировка, которую можно продиктовать агенту как есть.
01
Разложи входные файлы по папкам до первого запроса
куча файлов → структура по смыслу
С флипчарта
Когда на входе десятки разных файлов в одной куче, агент тратит контекст на то, чтобы понять, что вообще перед ним. Пять минут раскладки экономят половину диалога: сгруппируй по смыслу - исходники, справочники, готовое - и назови папки так, чтобы название объясняло содержимое без пояснений.
Схема прокручивается вбок →
Что сказать агенту
Разложи файлы из этой папки по смысловым группам. Сначала предложи структуру списком и объясни логику - я подтвержу, потом раскладывай.
02
К каждому тяжёлому документу - короткое md-описание
PDF, XLSX, DB, архив → файл.md рядом
С флипчарта
Стостраничный PDF или выгрузка на 40 тысяч строк съедают контекст целиком, а нужны из них три абзаца. Попроси агента один раз пройти по тяжёлым файлам и сделать рядом с каждым короткое описание: о чём документ, какие разделы, где искать цифры, какие колонки что значат. Дальше он читает описание и лезет в сам файл только за нужным куском.
Схема прокручивается вбок →
Что сказать агенту
Для каждого файла в этой папке сделай рядом описание в .md: о чём документ, структура, что где искать, на какие вопросы отвечает. Сам документ в описание не копируй - только карта.
03
В каждой неочевидной папке - свой AGENTS.md
правила там, где они нужны
С флипчарта
Главный AGENTS.md описывает проект целиком, но если внутри есть папка, где легко ошибиться - входящие, черновики, справочники, - положи в неё отдельный AGENTS.md на несколько строк: что здесь лежит, что с этим делать, чего не делать. Агент, зайдя в папку, читает её правила и не тащит логику из соседней.
Схема прокручивается вбок →
Что сказать агенту
В каждой подпапке заведи свой AGENTS.md: что за файлы внутри, что с ними делать, чего делать нельзя. Коротко, 5-7 строк, без повторов главного файла.
04
Раздели вход и результат: исходники неприкосновенны
input/ только на чтение, output/ на запись
Плюс к базе
Самый частый испуг новичка - «агент испортил мой файл». Лечится структурой: оригиналы лежат в отдельной папке, и в инструкции написано, что писать в неё нельзя. Всё, что агент создаёт, уходит в папку результатов. Сломал результат - перегенерировал, исходник цел.
Схема прокручивается вбок →
Что сказать агенту
Правило проекта: файлы в input/ только читаешь, никогда не меняешь и не удаляешь. Всё созданное клади в output/. Запиши это в AGENTS.md первой строкой.
05
Положи один файл-эталон результата
образец вместо описания словами
Плюс к базе
«Сделай красиво» и «как мы обычно делаем» агент понимает по-своему каждый раз. Один готовый пример нужного результата - протокол, отчёт, письмо - в папке проекта заменяет страницу требований и убирает половину доработок. Если эталона нет, попроси сделать три варианта и выбери лучший - он и станет эталоном.
Схема прокручивается вбок →
Что сказать агенту
В output/ лежит _эталон - образец правильного результата. Ориентируйся на него: структура, тон, объём, оформление. Отклоняешься - объясни почему.
06
Секреты - в .env, и сразу красной линией в инструкции
.env + .env.example, ключи не в чат
Плюс к базе
Как только в задаче появляется доступ к почте, CRM или API, возникает соблазн вставить токен прямо в диалог. Заведи .env на старте, до первого ключа, и файл .env.example рядом - чтобы было видно, какие переменные нужны, без значений. В инструкции пропиши: ключи не запрашивать в чат, скрипты берут их из .env локально.
Схема прокручивается вбок →
Что сказать агенту
Секреты только в .env, в чат их не запрашивай и не выводи. Скрипты читают ключи из .env локально. Рядом держи .env.example без значений. Добавь .env в .gitignore.
07
Заведи NOTES.md - журнал решений проекта
память между сессиями
Плюс к базе
Контекст сессии обнуляется, и назавтра агент не помнит, почему вы отказались от первого варианта. Журнал решает это дешевле любых ухищрений с памятью: короткая запись после каждого значимого шага - что сделали, что решили, почему так. Новая сессия начинается не с нуля, а с чтения журнала.
Схема прокручивается вбок →
Что сказать агенту
После каждого значимого изменения дописывай запись в NOTES.md: дата, что сделали, какое решение приняли и почему. Новые записи сверху, коротко. В начале сессии прочитай журнал.
08
Повторяемое - в scripts/, а не в переписку
один запуск вместо объяснений заново
Плюс к базе
Если операция повторится хотя бы трижды - пусть агент сохранит её скриптом в папку scripts/, а не выполняет вручную каждый раз. Скрипт даёт одинаковый результат на новых данных и работает локально: сырые данные не уходят в сессию. Это и есть переход от «помощник ответил» к «процесс автоматизирован».
Схема прокручивается вбок →
Что сказать агенту
Всё, что повторяется, оформляй скриптом в scripts/ с понятным названием и комментарием, как запускать. Сырые данные обрабатывай локально скриптом, а не пересказывай в чат.
09
Сделай папке рабочий цикл: inbox → archive
агент живёт дальше первого запуска
Плюс к базе
Разовая задача - одна папка. Агент, которым пользуются каждую неделю, нуждается в цикле: новое падает в inbox, обработанное уезжает в archive с датой, результаты копятся в output. Через месяц видно, что уже обработано, а что ждёт - и агенту не приходится каждый раз объяснять, с чего начинать.
Схема прокручивается вбок →
Что сказать агенту
Рабочий цикл: новые файлы кладу в inbox/. Ты обрабатываешь всё, что там лежит, результат - в output/, обработанное переносишь в archive/ГГГГ-ММ/. Пустой inbox = всё сделано.
10
Спроси агента, где он запутается - до начала работы
ревизия структуры чужими глазами
Проверка сетапа
Последний шаг сетапа: попроси агента прочитать папку целиком и честно сказать, что ему непонятно и чего не хватает. Ответ - готовый список правок в AGENTS.md: где две папки неотличимы, где нет описания к данным, где не сказано, куда класть результат. Дешевле поправить сейчас, чем ловить это на десятом неверном ответе.
Схема прокручивается вбок →
Что сказать агенту
Прочитай папку проекта целиком и скажи: что тебе непонятно, где ты можешь ошибиться, каких описаний и правил не хватает. Не начинай задачу - сначала список вопросов.
02 · Итог
Как выглядит папка, где всё учтено
Не обязательно заводить всё сразу: начните с AGENTS.md, input и output, остальное дорастает по мере работы. Важен принцип - структура объясняет агенту проект раньше, чем вы напишете первый запрос.
проект-агента/
├── AGENTS.md # главные правила: роль, процесс, красные линии
├── NOTES.md # журнал решений - память между сессиями
├── .env # секреты (в git не попадает)
├── .env.example # какие переменные нужны, без значений
├── input/ # исходники как пришли - только чтение
│ ├── AGENTS.md # правила этой папки
│ ├── отчёт.pdf
│ └── отчёт.pdf.md # короткое описание тяжёлого файла
├── knowledge/ # справочники, база знаний, шаблоны
│ └── AGENTS.md
├── scripts/ # повторяемые операции
├── output/ # всё, что агент создаёт
│ └── _эталон.docx # образец правильного результата
├── inbox/ # новое на обработку
└── archive/2026-08/ # обработанное, по месяцам
ПОРЯДОК
Папка → разложить вход → описания к тяжёлым файлам → AGENTS.md главный и вложенные → эталон результата → и только потом первая задача. Последним шагом - попросить агента прочитать папку и сказать, где он запутается.