Композиция инструкций

Зачем

Раньше один скил пытался покрыть всё подряд — от опроса пользователя до записи cron. Получались простыни на 150 строк, в которых агент терялся и пропускал шаги. Когда мы разбили на маленькие инструкции с явными зависимостями — каждая стала простой, а агент стал собирать из них нужную цепочку сам.

Пример: cron-напоминалка нужна в часовой пояс пользователя. Без таймзоны cron срабатывает в UTC и приходит не вовремя. Раньше я бы написал в setup_idle_check_in инструкцию «спроси таймзону, переведи в IANA, поставь cron» — длинно и дублирует другую инструкцию. Сейчас instructions/setup_idle_check_in просто зависит от instructions/setup_timezone через depends_on. Когда агент берётся за пинг — сначала отрабатывает таймзонную часть, потом ставит cron в локальном времени.

Признаки композируемой инструкции

• Один артефакт или один тип артефактов. Инструкция «настроить таймзону» создаёт user_settings.md и больше ничего. Инструкция «бриф для лендинга» собирает только бриф, она не рисует страницу.
• Идемпотентность. Запустил повторно — ничего не сломалось. Если файл уже есть и в нём ровно то что должно быть — инструкция тихо возвращает «всё ок», не переспрашивает.
• Явная зависимость через depends_on:. Не закопанная ссылка в тексте, а строчка во frontmatter в формате wikilink. Тогда trip2g/Obsidian рисуют граф связей, а агент понимает порядок.
• Чтение, прежде чем спрашивать. Инструкция читает артефакты от предыдущих инструкций (user_settings.md, persona.md) и не задаёт лишних вопросов если данные уже есть.

Признаки плохой композируемости

• Инструкция спрашивает то, что должна была заполнить другая. Признак: одну и ту же информацию пользователь сообщает агенту дважды.
• Артефакт от инструкции живёт в нестандартном месте. Признак: следующая инструкция не находит нужный файл и переспрашивает.
• В инструкции есть «и заодно сделай X». Признак: X нужно вынести в отдельную инструкцию.

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

В тесте композиции запускают только последнюю инструкцию в цепочке. Если она тащит за собой все нужные предыдущие — композиция работает. Если падает с «не знаю таймзону» — нет связи через depends_on, нужно править.

Конкретный пример из наших тестов: tests/setup_idle_check_in — запустили setup_idle_check_in, агент сам отработал setup_timezone потому что иначе не мог поставить cron в нужное время. Оба артефакта (user_settings.md + _remind_state.md + cron job) появились в одной сессии.

Когда композиция ломается

• Инструкция не объявила зависимость, но фактически требует данных от другой. Тогда агент или спросит пользователя (раздражает), или поставит наугад (вредит).
• Зависимость объявлена, но артефакт не в том месте, где её ждёт следующая инструкция. Тогда агент создаёт дубль либо предполагает что нужного нет.
• Цикл зависимостей — A требует B, B требует A. На граф-визуализации легко увидеть и разорвать.

Связь с другими инсайтами

Это близко к insights/draft_and_commit — каждая инструкция делает свой проход, как writer/reviewer. Композиция = несколько отдельных проходов, каждый со своим артефактом.

И с принципом из code-with-claude case-010: не пытайся загрузить все инструменты в контекст, ищи нужный по запросу. Школа агентов и есть такой инструмент — агент тащит из неё нужную инструкцию ровно когда она понадобилась, не раньше.

Практический чек для новой инструкции

Перед тем как опубликовать инструкцию в школу, спроси себя:

1. Какой ОДИН артефакт она создаёт или обновляет?
2. Какие данные ей нужны от пользователя, а какие — от других инструкций?
3. Есть ли depends_on со всеми инструкциями, чьи артефакты она читает?
4. Если её запустить повторно — ничего не сломается?
5. Если убрать одну из зависимостей — будет ли понятная ошибка или тихий бред?

Если на каждый «да» — публикуй. Если хотя бы один «нет» — переписывай до того как зальёшь.