Инструкция для ИИ-агентов

ИИ-агент — очень быстрый помощник, который делает ровно то, что сказано в инструкции, и угадывает там, где она молчит. Эта страница и есть инструкция. Она делит работу над сайтом на четыре занятия — планирование, тексты, дизайн, сборку — и для каждого говорит, что читать, что сдать и чего никогда не трогать.

Зачем это вам. Дайте агенту ссылку на эту страницу (или heron docs --export), назовите роль — и он перестаёт угадывать: агент по текстам заполняет страницы и не правит тему, агент-дизайнер меняет только тему, а любая работа заканчивается одной и той же проверкой — строгой сборкой.

Пример задачи для агента: «Прочитай AGENTS.md. Работай в роли контента. Добавь страницу о ремонте крыши, скопировав content/ru/services/gutter.md, заполни title, h1 и description и запусти строгую сборку».

Эта страница нужна, когда вы передаёте работу агенту или человеку. Готовые задания для копирования — в разделе HERON для ИИ.

Нет клона репозитория — та же документация есть в образе, ровно той версии, что и сам HERON:

docker run --rm ghcr.io/fmstm/heron:prod docs                     # оглавление
docker run --rm ghcr.io/fmstm/heron:prod docs architect           # тема целиком
docker run --rm ghcr.io/fmstm/heron:prod docs --search "E023"     # поиск: файл, строка, контекст
docker run --rm -v "$PWD":/site -w /site --user $(id -u):$(id -g) \
  ghcr.io/fmstm/heron:prod docs --export .heron-docs              # папкой, ссылки работают

Ссылки в документации — пути в репозитории; в выгрузке --export они те же. Все команды для чтения документации — на странице Документация в терминале.

HERON — сборщик статических сайтов, образ ghcr.io/fmstm/heron:TAG (или pip-пакет, команда heron). Он создаёт папку сайта (new, init, page) и собирает её по контракту (build, check, serve).

Сайт — папка без кода HERON: site.yaml (единственный конфиг), content/ru/ и папки других языков (страницы в markdown), media/, data/, static/, theme/. Страница = файл, путь файла = адрес. Каждый файл начинается с SEO-блока из восьми групп, дальше — вступление и секции ## Заголовок {#якорь}. Тема ставит секции на места по якорям.

Если вы видите HERON впервые, прочитайте Понятия — семь понятий, на которых стоит всё остальное.

H="docker run --rm -v $PWD:/site -w /site --user $(id -u):$(id -g) ghcr.io/fmstm/heron:prod"
$H new мой-сайт --notes ru --name "Сайт" --domain example.com --lang en,ru -y   # без вопросов
$H check мой-сайт              # отчёт без сборки
$H build мой-сайт --env prod --strict

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

 Архитектор ──▶ структура, site.yaml, типы ──┬──▶ Дизайнер ──▶ тема ──────┐
                                             └──▶ Контент и SEO ──▶ страницы ┴──▶ Сборщик ──▶ сайт, образ, отчёт

Прежде чем предлагать доработку HERON, проверьте Что HERON уже умеет: почти всё, что нужно сайту, уже есть.

Цель. Структура сайта, по которой остальные роли работают без новых вопросов.

Вход. Отчёт о старом сайте, выгрузка, sitemap, Search Console; или описание задачи заказчика.

Выход.

1. документ «структура сайта» по форме templates/structure.md: дерево страниц, ключи, типы, секции по типам, языки;
2. черновик site.yaml (образец) и разделы types/links для theme.yaml (образец);
3. таблица переноса: старый адрес → ключ → новый адрес по языкам → 301 или 410;
4. вопросы заказчику — с вариантами и рекомендацией.

Читать. Что HERON уже умеет, гайды Понятия и SEO и переезд, контракт: папка сайта, адреса и языки, site.yaml, theme.yaml.

Правила. Структура строится из возможностей HERON, а не из устройства старого сайта. Тип оправдан своей раскладкой. Страница в нескольких разделах — плоско и связями. Задача на HERON — только если потребности нет в списке возможностей.

Готово, когда: у каждой страницы есть ключ, тип и язык; у каждого типа — список секций с формами; у каждого старого адреса — решение 301/410; каждое решение ссылается на раздел документации.

Цель. Страницы, которые собираются без ошибок, и SEO-блок, заполненный по делу.

Вход. Структура от архитектора (или существующий сайт), тексты и факты от заказчика.

Выход. Файлы content/ru/…md (и других языков), картинки в media/, данные в data/, redirect_from у страниц, список долгов контента и вопросов.

Читать. Гайды Страницы и контент и SEO; образец страницы templates/page.md; контракт: формат страницы.

Правила. Новая страница — heron page с типом и именем или копия готового файла; SEO-блок не сокращается, комментарии не удаляются. title ≠ h1. Ссылки на свои страницы — ключом от корня, без языкового префикса. Нет материала — секции нет. Контакты и реквизиты — в site.yaml, не в тексте.

Готово, когда: check без ошибок; у каждой страницы заполнены title, h1, description; у картинок есть alt; сводка «Не заполнено» перенесена в отчёт.

Цель. Тема, которая рисует все типы страниц из структуры и не ломается на неполном контенте.

Вход. Типы и секции от архитектора, макет или описание вида.

Выход. theme/: theme.yaml, шаблон на каждый тип, модуль на каждую форму, файлы i18n на каждый язык, стили.

Читать. Гайд Тема и дизайн; контракт: формы секций, theme.yaml, картинки; сборка: что видит шаблон.

Правила. Шаблон не содержит текстов контента и данных сайта: тексты — в секциях, реквизиты — site.*, строки интерфейса — t.*. Секции выводятся через mod.MODULE('ANCHOR'), без условий вокруг. Картинки — только через picture().

Готово, когда: у каждого типа из types есть шаблон; у каждой формы из uses — модуль; сборка на стартовом и на полном контенте проходит; в отчёте нет недостающих строк i18n.

Цель. Сайт, который собирается --env prod --strict и отвечает правильными кодами.

Вход. Структура, site.yaml, тема и контент — или задача «собери по структуре», тогда сборщик ведёт остальные роли сам.

Выход. Рабочая папка сайта; dist/ или образ; отчёт: что сделано, долги контента, вопросы, оставленные предупреждения.

Читать. Гайды Первый сайт и Сборка и выкладка; коды ошибок — сборка, раздел 11.

Правила. site.yaml — единственная точка правды: флагов «язык» и «тема» у команд нет. В папку сайта не кладутся Dockerfile, compose, .env. Предупреждение — либо долг контента, либо ошибка, не шум.

Готово, когда: build --env prod --strict проходит; smoke prod зелёный; отчёт сдан.

1. Факты не выдумываются. Телефоны, адреса, цены, сроки, имена, номера, цифры — только из источника заказчика. Нет факта — поле пустое, вопрос в список. Пустой блок HERON не рисует; выдуманный — рисует.
2. site.yaml — единственная точка правды о сайте: языки, тема, домен, меню, счётчики, 410.
3. Папка сайта — только контент. Сборка и упаковка — командами HERON и scripts/site.sh.
4. Ключ страницы — путь файла, адрес — slug. Имена файлов одинаковы во всех языках; ссылки и меню пишутся ключами.
5. Структура важнее разметки. Порядок секций в файле не важен; форму секции задаёт её разметка.
6. Предупреждение — работа. --strict превращает их в ошибки — так собирается прод.
7. HERON не правится из сайта. Не хватает возможности — задача на HERON (шаблон на странице Архитектор), на сайте — самый простой честный вариант.

Образцы — в папке docs/agents/templates: structure.md, site.yaml, theme.yaml, page.md. Все проверяются тестами HERON: устаревший образец уронит тесты раньше, чем вы его возьмёте.

Это инструкция для сайта; репозиторий HERON — отдельная работа. Там: uv sync --group dev, ./scripts/check.sh перед каждым коммитом. Никаких имён сайтов, доменов, слагов и предметной лексики в коде, тестах и документации — это проверяет scripts/check-boundaries.sh. Документация меняется в том же коммите, что и поведение.

Эта страница повторяет файл AGENTS.md из ветки prod. Репозиторий обновляется первым, поэтому самая свежая версия всегда там: AGENTS.md на GitHub.