AGENTS.md как оглавление, а не энциклопедия

Как писать AGENTS.md, разобрано в уроке «AGENTS.md: инструкции проекта», а как организовать его в большом репозитории — в уроке «AGENTS.md в большом репозитории». Здесь вопрос архитектурный: какую роль этот файл играет в harness. Короткий ответ команды OpenAI: Codex нужна карта, а не руководство на тысячу страниц. Разберём, почему так, что конкретно должно быть в карте и как не дать ей снова превратиться в энциклопедию.

Почему большой AGENTS.md проваливается

В статье «Harness engineering» команда OpenAI описывает, как подход «один большой AGENTS.md» не сработал, и называет четыре причины:

1. Контекст ограничен. Огромная инструкция вытесняет задачу, код и нужные документы.
2. Когда важно всё, не важно ничего. Агент перестаёт ориентироваться в системе и начинает подбирать шаблоны локально.
3. Монолит гниёт. Файл становится кладбищем устаревших правил, которые никто не решается удалить.
4. Его нельзя проверить механически. Ни покрытие, ни актуальность, ни владельцев, ни перекрёстные ссылки.

Их решение — AGENTS.md примерно на сто строк, который работает как оглавление, а знания лежат в структурированном docs/. Агент начинает с маленькой стабильной точки входа и знает, куда смотреть дальше. Это и есть постепенное раскрытие (progressive disclosure).

Техническая сторона: лимит и порядок склейки

По документации Codex, цепочка инструкций собирается так:

• глобальный уровень ~/.codex: AGENTS.override.md, иначе AGENTS.md — один файл;
• проектный уровень: от корня проекта до текущей папки, в каждой папке не больше одного файла — override, иначе AGENTS.md, иначе имена из project_doc_fallback_filenames;
• файлы склеиваются от корня к рабочей папке, более близкий идёт позже и перекрывает общий;
• суммарный объём ограничен project_doc_max_bytes, по умолчанию 32 KiB; когда лимит достигнут, следующие файлы не добавляются.

Наш вывод. Из порядка склейки следует неприятное: при переполнении теряются не общие, а самые специфичные инструкции — те, что лежат ближе всего к коду, с которым агент работает. Раздутый корневой файл молча отключает вложенные. Лимит можно поднять ключом, но это лечение симптома: проблема из пункта 1 никуда не денется. Лимит — техническое подтверждение тезиса «AGENTS.md — оглавление».

Ещё одна деталь из документации: цепочка собирается заново при каждом запуске, кэша нет. После правки AGENTS.md сессию нужно перезапустить.

Что входит в карту

Хорошая карта отвечает на вопросы, которые возникают почти в каждой задаче, и указывает, где искать остальное. Для примера — AGENTS.md нашего собственного сайта на OctoberCMS занимает около 70 строк и состоит в основном из ссылок в docs/. Обобщённая структура:

# AGENTS.md — сайт агентства

Сайт на OctoberCMS (PHP 8) + тема `amiga` (Twig, SCSS, Vite).
Локально: Docker, http://localhost:8001.

## Обязательные правила
- Перед правкой кода прочитать docs/CODESTYLE.md (BEM, strict_types, валидация).
- Большие стили и скрипты страниц — в resources/scss/pages и resources/js/pages,
  не inline (docs/CODESTYLE.md, раздел 3.4).
- robots.txt правится только на сервере, см. docs/DEPLOYMENT.md.

## Команды
- `make setup` — поднять стенд; `make test-agent` — тесты с коротким выводом
- `make lint` — PHPStan и стили; `make e2e` — Playwright против стенда
- После правок SCSS/JS: `cd themes/amiga && npm run build`

## Где что лежит
- themes/amiga/ — страницы, партиалы, ресурсы
- plugins/<vendor>/<plugin>/ — компоненты, модели, сервисы
- tests/e2e/ — Playwright

## Документация
- docs/ARCHITECTURE.md — слои и границы
- docs/exec-plans/ — планы исполнения (см. docs/PLANS.md)
- docs/SITEMAP.md — откуда берётся дата изменения страниц

## Готово, когда
- `make lint` и `make test-agent` зелёные, для вёрстки — `make e2e`
- Проверены разрешения от 360px до 4K (docs/RESPONSIVE.md)

Обратите внимание на форму каждого правила: коротко что делать, плюс ссылка, где подробности и почему.

Чего в карте быть не должно

Правило, которое можно проверить программой, но которое живёт только текстом, — слабейшее звено harness. Бёкелер называет такое состояние «только направляющие»: правила есть, проверки нет. Как переносить их в код — урок об инвариантах.

Вложенные файлы и override

Вложенный AGENTS.md оправдан, когда у части репозитория действительно свои правила: мобильное приложение в монорепозитории, отдельный сервис интеграции с CRM, каталог e2e-тестов. Документация советует размещать такие файлы как можно ближе к специализированной работе. Там же для ревью есть отдельный раздел ## Code Review Rules в AGENTS.md, ближайшем к коду.

AGENTS.override.md в папке имеет приоритет над соседним AGENTS.md. Если он игнорируется git, Codex копирует его в управляемые worktree. Это удобно для личных временных настроек, но командные правила должны жить в обычном файле под версионным контролем.

Как карта растёт и худеет

Best practices Codex дают простое правило роста: начинать с основ и добавлять новые правила только после повторяющихся ошибок; когда агент дважды ошибся одинаково, попросить его провести ретроспективу и обновить AGENTS.md.

Наше дополнение — правило похудения. Бёкелер отмечает, что новые модели делают часть старых инструкций лишними. При смене модели в команде пройдите по AGENTS.md и проверьте, какие правила ещё несут нагрузку: уберите правило в ветке и прогоните задачи, на которых оно появилось. Это ручная версия evals, о настоящих — урок о своих evals.

Проверка в CI

Тезис OpenAI о механической проверке легко применить к самой карте. Скрипт проверяет бюджет строк корневого файла, суммарный объём и живость ссылок. Сообщения написаны как инструкции по исправлению — их прочитает и агент.

#!/usr/bin/env python3
"""Проверка карты для агента: бюджет строк, суммарный объём, живые ссылки."""
import pathlib
import re
import sys

MAX_ROOT_LINES = 150
MAX_TOTAL_BYTES = 24 * 1024  # запас до project_doc_max_bytes (32 KiB)
LINK = re.compile(r"\]\(([^)#\s]+)(?:#[^)]*)?\)")
SKIP = {"node_modules", "vendor", ".git"}

root = pathlib.Path(__file__).resolve().parents[1]
files = [p for p in root.rglob("AGENTS.md") if not SKIP & set(p.parts)]
errors, total = [], 0
for f in files:
    text = f.read_text(encoding="utf-8")
    total += len(text.encode("utf-8"))
    rel = f.relative_to(root)
    lines = text.count("\n") + 1
    if f.parent == root and lines > MAX_ROOT_LINES:
        errors.append(f"{rel}: {lines} строк при бюджете {MAX_ROOT_LINES}. "
                      "Вынесите подробности в docs/ и оставьте ссылку.")
    for target in LINK.findall(text):
        if re.match(r"^[a-z]+:", target):
            continue
        if not (f.parent / target).exists():
            errors.append(f"{rel}: ссылка на несуществующий {target}. "
                          "Исправьте путь или удалите ссылку.")
if total > MAX_TOTAL_BYTES:
    errors.append(f"Все AGENTS.md вместе — {total} байт при бюджете {MAX_TOTAL_BYTES}. "
                  "Сократите корневой файл, иначе вложенные могут не попасть в контекст.")
print("\n".join(errors) or "AGENTS.md: OK")
sys.exit(1 if errors else 0)

agents-md:
  stage: test
  image: python:3.12-alpine
  script:
    - python3 scripts/check_agents_md.py
  rules:
    - changes:
        - "**/AGENTS.md"
        - "docs/**/*"

Суммарный объём всех файлов — консервативная оценка: в контекст попадает только цепочка от корня до рабочей папки. Зато проверка простая и ловит главное — разрастание.