Что такое Interpretable Context Methodology и какую проблему она решает
Interpretable Context Methodology (ICM) переносит оркестрацию AI-агентов из кода в структуру файловой системы. Вместо того чтобы писать на Python координацию шагов, передачу состояния между вызовами модели и обработку ошибок, вы раскладываете пайплайн по папкам и markdown-файлам. Агент читает каталог, определяет текущий шаг и загружает ровно тот контекст, который нужен на этом шаге.
Классический путь устроен иначе. Оркестрационный фреймворк (CrewAI, LangChain, AutoGen) руководит передачей контекста, памятью, обработкой ошибок и координацией шагов решения задачи. Для сложных многозадачных систем это оправдано, но для линейного процесса с проверкой результата человеком такой слой даёт огромный инженерный overhead, о чём прямо говорят авторы первоисточника: разбор статьи Jake Van Clief и David McDermott на Хабре.
Методология держится на трёх решениях. Markdown-файлы содержат промпты и контекст, которые говорят агенту, какую роль взять на каждом шаге пайплайна. Задачи, не требующие LLM, описываются локальными скриптами. Оркестрацию ведёт один агент, а не команда взаимодействующих агентов.
Почему фреймворки оркестрации не всегда оправданы
Фреймворк хорошо работает там, где система ветвится: параллельные задачи, динамическое планирование, разные роли агентов, обмен сообщениями между ними. Линейный конвейер из пяти шагов, где человек проверяет результат после третьего, таких возможностей не требует.
Что приходится писать во фреймворке для паузы под ручную проверку: сериализацию состояния сессии, логику остановки и возобновления, передачу контекста между узлами, повторные вызовы после правок, обработку таймаутов и тесты ко всему этому. В ICM тот же контроль описывается папкой шага и файлом-чеклистом: агент не идёт дальше, пока в каталоге артефактов нет проверенного результата. Кода оркестрации нет вообще, есть структура и markdown-инструкции.
Ключевая идея: файловая система как оркестратор
Структура директорий говорит агенту, что делать на каждом шаге процесса. Та же структура определяет контекст для sub-агентов, если задачу нужно делегировать: sub-агент получает не весь проект, а содержимое своей папки. Отдельная команда агентов с менеджером и обменом сообщениями не нужна, оркестрацией занимается один агент.
Как устроена структура директорий в ICM
Сразу оговорка: точные названия пяти слоёв иерархии в доступных материалах не раскрыты, поэтому ниже логика слоёв, а не канонические имена. Слои разделяются по назначению: корень пайплайна, папки шагов, общий контекст и знания, локальные скрипты, каталог артефактов.
pipeline/
01_collect/
step.md
script.py
02_analyze/
prompt.md
context.md
03_review/
check.md
04_report/
prompt.md
shared/
glossary.md
artifacts/
01_collect.json
02_analyze.md
Каждый шаг это папка с markdown-файлами, которые агент читает перед работой. Артефакты лежат отдельно и накапливаются по ходу процесса, поэтому результат любого шага можно открыть и посмотреть глазами, не запуская отладчик фреймворка.
Markdown-файлы как носители промптов и контекста
В файлах шага лежат промпты, инструкции и данные, нужные именно этому шагу. Поведение становится прозрачным: открываете prompt.md и видите ровно то, что получил агент, без скрытых системных промптов и служебных сообщений, которые фреймворк подмешивает сам. Второй эффект касается контекстного окна: загружаются файлы текущего шага, а не весь проект целиком. Для длинных пайплайнов это заметная экономия токенов.
Локальные скрипты для задач без LLM
Конвертация формата, переименование файлов, проверка JSON по схеме, выгрузка данных по API: операции детерминированные, модели там решать нечего. Они описываются локальным скриптом, а агент вызывает его как шаг пайплайна. Экономия двойная: токены не тратятся на то, что и так считается точно, и результат одинаков при одинаковом входе. Меньше вариативности означает меньше поводов разбираться, почему вчерашний прогон дал другой ответ.
Роль одного агента-оркестратора
Агент читает структуру директорий, определяет текущий шаг, подгружает контекст, выполняет шаг сам или передаёт работу sub-агенту, если нужна узкая специализация. Обмена сообщениями между агентами нет, ролей в одном процессе тоже нет: одна сессия, один набор инструкций на шаг. Для сравнения, схема с оркестратором, памятью и инструментами внутри обычного кода разобрана в материале про самописного AI-агента на Python: там видно, сколько обвязки требуется, когда логика шагов живёт в программе, а не в файлах.
Философия подхода: Unix-pipeline и принцип разделения зависимостей Дейкстры
Основа ICM описана её авторами как два проверенных инженерных принципа. Первый: Unix-pipeline. Система декомпозирована так, что модули скрывают детали друг от друга, и это позволяет менять логику отдельного модуля, не нарушая работу программы. Второй: предложенный Дейкстрой принцип разделения зависимостей, при котором модуль отвечает за единственную задачу, а разработчику остаётся определить порядок выполнения задач. Оба принципа названы в первоисточнике.
Практический смысл простой. Шаг 02_analyze можно переписать целиком, заменив prompt.md, и остальные шаги этого не заметят, потому что общаются они через артефакты, а не через общий код. Интерпретируемость появляется как побочный эффект: у каждого шага явный вход, явное назначение и явный результат. Цена такой ясности это дисциплина проектирования, знакомая по обычной разработке: архитектурное мышление остаётся узким местом, даже когда код пишет агент.
ICM против CrewAI, LangChain и AutoGen: сравнение
Фреймворки не плохие и не устаревшие, они решают другой класс задач. Ниже сравнение по критериям, которые чаще всего важны при выборе.
| Критерий | ICM | CrewAI, LangChain, AutoGen |
|---|---|---|
| Порог входа | Каталоги, markdown и скрипты; знать API фреймворка не нужно | Нужно освоить API, модели данных и абстракции конкретной библиотеки |
| Объём контекста | Загружаются файлы текущего шага | В контекст попадает то, что решил передать оркестратор, включая служебные сообщения |
| Прозрачность | Промпт шага лежит в файле, его видно целиком | Часть промптов и логики скрыта внутри библиотеки |
| Отладка | Проверка артефактов шаг за шагом вручную | Единый лог выполнения и трассировка вызовов |
| Гибкость планирования | Жёсткий порядок шагов | Ветвления, параллельные задачи, динамические планы |
| Многопользовательские сценарии | Плохо ложится: структура рассчитана на одного пользователя и одну сессию | Изоляцию сессий и состояние можно реализовать средствами фреймворка |
| Проверка человеком | Встроена в пайплайн как отдельный шаг с чеклистом | Требует явной логики пауз, остановок и возобновления |
| Зависимости проекта | Минимум: файловая система, скрипты, модель | Библиотека и её окружение, версии которых надо поддерживать |
Когда ICM выигрывает
Линейные пайплайны с понятными шагами: сбор данных, анализ, проверка, отчёт. Ситуации, где человек обязан посмотреть промежуточный результат, например выверка цифр перед публикацией или согласование черновика документа. Задачи с ограниченным контекстным окном, где нельзя позволить себе тащить весь проект в каждый запрос. Требования к аудиту и прозрачности, когда нужно показать, какой именно вход получил агент на каждом шаге.
Когда фреймворк остаётся лучшим выбором
Сложные многозадачные системы, где несколько агентов работают параллельно и результат одного влияет на план остальных. Динамическое планирование, когда состав шагов заранее неизвестен. Продукт с несколькими пользователями, где нужны изоляция сессий, права доступа и одновременные запуски. ICM такие сценарии не покрывает: он подходит для последовательных пайплайнов и плохо масштабируется на многопользовательские режимы.
Ограничения и подводные камни ICM
В исходной публикации ограничения подробно не разобраны, поэтому дальше выводы, которые следуют из устройства подхода. Они не отменяют его, но определяют границы применимости.
Проблемы отладки и трассировки
Единого лога оркестрации нет. Если ошибка возникла на втором шаге, а проявилась на пятом, искать причину придётся по артефактам: смотреть, какой файл отдал шаг, что прочитал агент на следующем, где данные разошлись. Во фреймворке такую цепочку видно в трейсе. Частично это лечится практикой: сохранять промежуточные артефакты в отдельный каталог и держать markdown-файлы под контролем версий, чтобы видеть, что менялось между прогонами.
Масштабирование на команду и многопользовательские сценарии
Структура директорий предполагает одного пользователя или одну сессию. Для нескольких пользователей понадобятся изоляция каталогов, разграничение доступа и управление параллельными запусками. Методология этого не описывает, инфраструктуру придётся строить отдельно. Показательный пример, где такая инфраструктура потребовалась, это оркестратор задач на git worktree и CLI-сессиях Claude Code: разделение рабочих каталогов там решается внешними инструментами, а не файловой структурой самого пайплайна.
Ещё один нюанс это дисциплина именования. Пайплайн из десяти шагов с десятками файлов быстро превращается в свалку, если нумерация и названия папок не подчинены правилу. Методология даёт свободу, а порядок в ней обеспечивает человек.
Практический пример: как выглядит пайплайн на ICM
Возьмём абстрактный конвейер из четырёх шагов: сбор данных, анализ, проверка человеком, генерация отчёта.
pipeline/
01_collect/
script.py
step.md
02_analyze/
prompt.md
context.md
03_review/
check.md
04_report/
prompt.md
shared/
glossary.md
artifacts/
01_collect.json
02_analyze.md
03_review.md
04_report.md
Работа идёт так. Агент начинает с папки 01_collect, читает step.md и запускает script.py, который выгружает данные в artifacts/01_collect.json. Модель в этом шаге не участвует. Дальше агент открывает 02_analyze, читает prompt.md и context.md, анализирует данные и пишет результат в artifacts/02_analyze.md. Шаг 03_review содержит check.md с критериями приёмки: агент останавливается и ждёт, пока человек посмотрит артефакт предыдущего шага и подтвердит его. После подтверждения шаг 04_report берёт проверенный анализ и собирает итоговый документ по своему prompt.md.
Что здесь важно: контекст для каждого шага ограничен его папкой, артефакты лежат отдельно и версионируются, а точка вмешательства человека это обычная папка, а не отдельный обработчик в коде. Требования к шагам стоит формулировать так же строго, как для любого ИИ-агента: измеримые критерии и список исключений дают проверяемые артефакты, а размытые формулировки нечего принимать.
Стоит ли переходить на ICM: итоговый вердикт
ICM не заменяет фреймворки оркестрации, это альтернатива для узкого класса задач. Проверить свою задачу можно по четырём вопросам. Пайплайн линейный? Человек проверяет результат на конкретных шагах? Контекстное окно ограничено или стоит дорого? Нужна прозрачность, то есть возможность открыть файл и увидеть, что получил агент? Если на все четыре ответ «да», подход стоит попробовать хотя бы на одном конвейере: структура директорий, markdown-промпты и скрипты собираются за вечер.
Если хотя бы один ответ «нет», смотрите в сторону фреймворка. Многопользовательский продукт, параллельные ветки, динамическое планирование по результатам шагов и потребность в единой трассировке это ровно те места, где ICM начинает мешать: состояние разъезжается по файлам, а причины ошибок приходится искать вручную. Разумная тактика это гибрид: оркестрация через директории там, где процесс последовательный, и фреймворк там, где нужна координация множества агентов.
Оригинальную статью с описанием методологии написали Jake Van Clief и David McDermott, русскоязычная выжимка опубликована на Хабре. Перед переносом своего пайплайна посчитайте, сколько кода оркестрации вы сейчас поддерживаете: если это несколько сотен строк ради пяти последовательных шагов, файловая структура сэкономит заметно больше, чем кажется.