# ICM на практике: структура папок, которая делает ИИ-агента управляемым

> AI Release · @ai_release1 · https://ai-release.org/guides/icm-praktika-struktura-papok-agenta.html

## TL;DR
- Время выполнения: 30 минут
- Уровень сложности: Intermediate
- Понадобится: macOS или Linux с bash/zsh, текстовый редактор, ИИ-агент с доступом к локальным файлам (в кейсе TravelLine использовали OpenCode и модель GPT-5.5; также подойдут Claude Code или Codex CLI), утилита `tree` (или `find`), права на запись в домашнюю директорию.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/icm-praktika-struktura-papok-agenta-ru-1.jpg?v=1793609395)

- ОС: macOS или Linux. Примеры команд — для bash/zsh; в Windows используйте WSL.
- Агент должен уметь читать файлы внутри рабочей папки и записывать результат. Точные флаги запуска сверьте с документацией вашего CLI.
- Если данные лежат во внешней системе, понадобится MCP-сервер — протокол, через который агент подключает внешние инструменты и данные. В кейсе TravelLine агент тянул данные из TestIT через MCP-сервер.
- ICM (Interpretable Context Methodology) — методология, где оркестрация агента переносится в структуру файловой системы: markdown-файлы содержат промпты и контекст для каждого шага пайплайна. Подход рассчитан на последовательные процессы с проверкой человеком; для сложных многозадачных систем это ограничение.
- Если вы только переходите от обычного чата к агенту, см. [Как превратить обычный чат с LLM в полноценного AI-агента](https://ai-release.org/guides/kak-prevratit-obychnyy-chat-s-llm-v-polnotsennogo-ai-ag.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Шаг 1. Спроектируйте пайплайн и создайте каркас папок
**Что сделать:** разбейте задачу на последовательные шаги и создайте директории под контекст, шаги, навыки и результаты.

**Зачем:** ICM заменяет оркестрацию на уровне фреймворка оркестрацией через файловую систему. Агенту не нужно угадывать порядок действий — он читает `plan.md` и файлы шагов.

**Пример:**
```bash
mkdir -p icm-agent/{context,steps,skills,out}
cd icm-agent
touch AGENTS.md plan.md
```

Структура после команды:
```
icm-agent/
├── AGENTS.md
├── plan.md
├── context/
│   ├── 00-role.md
│   ├── 01-input.md
│   └── 02-constraints.md
├── steps/
│   ├── 01-extract.md
│   ├── 02-validate.md
│   └── 03-report.md
├── skills/
│   └── threat-model/
└── out/
    └── run-2026-10-22/
```

**Как проверить:**
```bash
tree -L 3
```
Если `tree` не установлена:
```bash
find . -maxdepth 2 -type d | sort
```
На экране должны появиться папки `context`, `steps`, `skills`, `out`. Если папок нет — команда `mkdir` не выполнилась или вы находитесь не в той директории.

Для длинных задач используйте `plan.md`: в посте про Tiel-Coder-35B-A3B-MTP контекст 65 535 токенов, поэтому задачи дробят через `plan.md` и лёгкий агент Pi вместо Codex или Claude Code.

## Шаг 2. Заполните контекст, план и шаги
![Иллюстрация к разделу «Шаг 2. Заполните контекст, план и шаги»](https://ai-release.org/guides/img/icm-praktika-struktura-papok-agenta-ru-2.jpg?v=1793609399)

**Что сделать:** в каждом markdown-файле опишите роль, вход, ограничения и ожидаемый выход. В `AGENTS.md` задайте общие правила, в `plan.md` — последовательность шагов.

**Зачем:** агент читает эти файлы как инструкции. В кейсе TravelLine условие входа было жёстким: без полного контекста и вылизанной инструкции агент путает suites и секции и отдаёт неполный список тестов.

**Пример `plan.md`:**
```markdown
# План пайплайна
1. steps/01-extract.md — извлечь список E2E-тестов из TestIT через MCP.
2. steps/02-validate.md — сверить список с локальным репозиторием автотестов.
3. steps/03-report.md — собрать отчёт в out/run-2026-10-22/report.md.
```

**Пример `AGENTS.md`:**
```markdown
# Правила агента
- Читай только файлы внутри icm-agent/.
- Перед каждым шагом перечитай plan.md.
- Не переходи к следующему шагу, пока не запишешь результат в out/.
- Если данных не хватает, остановись и задай вопрос человеку.
```

**Пример `steps/01-extract.md`:**
```markdown
# Шаг 1. Извлечение тестов
Роль: QA-инженер.
Вход: данные из TestIT через MCP-сервер.
Выход: out/run-2026-10-22/tests.json — список E2E-тестов.
Ограничение: не менять репозиторий.
```

| Файл | Что внутри | Зачем |
|---|---|---|
| `AGENTS.md` | общие правила для агента | задаёт границы поведения |
| `plan.md` | последовательность шагов | не даёт агенту перескакивать этапы |
| `context/01-input.md` | входные данные и scope | снижает риск неполного ответа |
| `steps/*.md` | промпт и ожидаемый выход шага | делает шаг воспроизводимым |

Если ваш агент ищет навыки в `~/.claude/skills`, папку можно подключить симлинком. Пример из grim-prompter:
```bash
ln -s "$(pwd)/skills/threat-model" ~/.claude/skills/threat-model
```
Проверка:
```bash
ls -l ~/.claude/skills/threat-model
```
В выводе должна быть стрелка на вашу папку `skills/threat-model`.

Если контекст разрастается, см. [Как экономить токены LLM: кэш, роутинг и prompt caching на практике](https://ai-release.org/guides/kak-sekonomit-tokeny-llm.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

**Как проверить:**
```bash
grep -R "Выход:" steps/
```
У каждого шага должна быть строка `Выход:`. Если её нет, агент может выполнить шаг и не сохранить артефакт.

## Шаг 3. Запустите агента и проверьте артефакты
**Что сделать:** запустите агента в корне `icm-agent` и дайте ему инструкцию следовать `plan.md`. Результаты должны появиться в `out/run-2026-10-22/`.

**Зачем:** так вы проверяете, что структура папок работает как оркестратор, а агент не придумывает шаги заново.

**Пример:**
```bash
cd icm-agent
<agent-cli> "Прочитай plan.md и выполни шаг 1. Результат запиши в out/run-2026-10-22/"
```
Замените `<agent-cli>` на CLI вашего агента: OpenCode, Claude Code, Codex CLI. Точные флаги запуска сверьте с документацией.

**Как проверить:**
```bash
tree out/
cat out/run-2026-10-22/tests.json | head
```
Ожидаемый результат: в `out/run-2026-10-22/` появились `tests.json`, затем `validation.md` и `report.md`. В `tests.json` — список тестов, а не пустой файл.

Чек-лист приёмки:
- [ ] `plan.md` содержит все шаги пайплайна.
- [ ] У каждого файла в `steps/` есть вход и выход.
- [ ] `AGENTS.md` запрещает переход к следующему шагу без записи в `out/`.
- [ ] После шага 1 в `out/run-2026-10-22/` лежит `tests.json`.
- [ ] После шага 3 отчёт открывается и содержит выводы, а не только заголовок.

Для формальной проверки агента прогоните [Аудит ИИ-агента за 120 секунд: 32 проверки и оценка A–F (iFixAi)](https://ai-release.org/guides/audit-ii-agenta-za-120-sekund-ifixai.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Возможные проблемы и решения
**Проблема. Агент путает suites и секции, отдаёт неполный список тестов**
- Ошибка: `агент путает suites и секции и отдаёт неполный список тестов`
- Причина: в контексте нет явного перечня suites и секций, а инструкция шага не задаёт критерий полноты.
- Решение: добавьте scope в `context/01-input.md` и перезапустите шаг.
```bash
cat >> context/01-input.md <<'EOF'
## Scope
![Иллюстрация к разделу «Scope»](https://ai-release.org/guides/img/icm-praktika-struktura-papok-agenta-ru-3.jpg?v=1793609416)

- suites: <список suite>
- sections: <список секций>
EOF
grep -n "suite\|section" context/01-input.md
```
После этого выполните шаг 1 заново и проверьте, что в `tests.json` попали все suites из scope.

**Проблема. Симлинк для навыка не создаётся**
- Ошибка: `ln: failed to create symbolic link '/home/user/.claude/skills/threat-model': No such file or directory`
- Причина: родительская папка `~/.claude/skills` ещё не существует.
- Решение: создайте папку и повторите команду.
```bash
mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/threat-model" ~/.claude/skills/threat-model
ls -l ~/.claude/skills/threat-model
```
В выводе `ls -l` должна быть строка со стрелкой на `skills/threat-model`.

**Проблема. Агент завершил шаг, но файла результата нет**
- Ошибка: `cat: out/run-2026-10-22/tests.json: No such file or directory`
- Причина: в файле шага не был явно указан путь выхода, поэтому агент не сохранил артефакт.
- Решение: добавьте строку выхода и перезапустите шаг.
```bash
cat >> steps/01-extract.md <<'EOF'
Выход: out/run-2026-10-22/tests.json
EOF
cat out/run-2026-10-22/tests.json | head
```
Если файл появился, шаг 1 можно считать завершённым.

## Резюме и следующие шаги
Вы создали файловую структуру, где каждый шаг пайплайна описан markdown-файлом, а агент читает `plan.md` и складывает результат в `out/`. Дальше добавьте проверку человеком на каждом шаге и протестируйте пайплайн на одном небольшом наборе данных.

## FAQ
**Чем ICM отличается от фреймворка для агентов?**
ICM переносит оркестрацию в структуру файловой системы: markdown-файлы содержат промпты и контекст для каждого шага пайплайна, вместо того чтобы логика выбора шагов жила в коде фреймворка.

**Подходит ли ICM для сложных многозадачных систем?**
Ограничение подхода: он рассчитан на последовательные процессы с проверкой человеком. Для сложных многозадачных систем это ограничение нужно учитывать.

**Нужен ли MCP?**
Не обязателен. В кейсе TravelLine агент тянул данные из TestIT через MCP-сервер, но ICM работает и с локальными файлами, если весь контекст лежит в папке `context/`.

**Можно ли использовать ICM с локальной моделью?**
Да. В посте про Tiel-Coder-35B-A3B-MTP в кванте Q2_K_XL указано 125 токенов/с на RTX 4070 Ti SUPER с 16 ГБ памяти и контекст 65 535 токенов; задачи дробят через `plan.md`, чтобы не выходить за лимит.