Один файл AGENTS.md с правилами проекта для ИИ-агентов, линтер, который не даёт ему протухнуть, и SessionStart-хук, который проверяет среду до начала работы.
Claude Code, Codex, Cursor, GitHub Copilot и другие агенты читают AGENTS.md (Claude Code читает CLAUDE.md, который просто импортирует @AGENTS.md). Если в файле записаны стек, команды, соглашения, запреты и критерии готовности, агент меньше гадает, реже ломает сборку и реже переспрашивает.
- Внедряется за час: скопировать шаблон и заполнить 5 разделов.
- Без зависимостей: линтер на чистом Python 3.9+, работает на Windows, macOS и Linux.
- Без привязки к вендору: обычный Markdown под git.
- Растёт вместе с командой: каждая ошибка агента превращается в одну строку в разделе
Lessons.
| Путь | Что это |
|---|---|
AGENTS.md, CLAUDE.md |
Контракт самого этого репозитория (проходит --strict) |
templates/AGENTS.md |
Шаблон контракта с заглушками <...> |
templates/CLAUDE.md |
Одна строка @AGENTS.md, чтобы Claude Code читал тот же файл |
scripts/agents_lint.py |
Линтер контракта (JSON-вывод, коды выхода для CI) |
scripts/session-start.sh, scripts/session-start.ps1 |
SessionStart-хук: линтер, установка зависимостей, тесты |
.claude/settings.json |
Подключение хука в Claude Code (bash; на Windows работает через Git Bash) |
.claude/settings.windows.example.json |
Вариант хука на чистом PowerShell |
.github/workflows/agents-lint.yml |
CI: тесты линтера и проверка на Ubuntu, Windows, macOS |
examples/python-app/ |
Заполненный пример, проходящий линтер |
bench/ |
Замеры скорости и A/B-тест агента |
# в корне вашего репозитория
git clone https://github.com/AntoGA/agents-contract $env:TEMP\agents-contract
Copy-Item $env:TEMP\agents-contract\templates\AGENTS.md, $env:TEMP\agents-contract\templates\CLAUDE.md .
New-Item -ItemType Directory -Force scripts, .claude | Out-Null
Copy-Item $env:TEMP\agents-contract\scripts\* scripts\
# если .claude\settings.json уже есть, не перезаписывайте его, а добавьте блок "hooks" вручную
if (-not (Test-Path .claude\settings.json)) { Copy-Item $env:TEMP\agents-contract\.claude\settings.json .claude\ }
notepad AGENTS.md # заполните все <...>
python scripts\agents_lint.py # должно быть "Итого: ошибок 0"macOS / Linux: те же шаги через cp, запуск python3 scripts/agents_lint.py.
Линтер требует пять разделов (заголовки на русском или английском):
| Раздел | Допустимые заголовки | Зачем агенту |
|---|---|---|
| Project | Project, Overview, Stack, О проекте, Стек |
Что это и на чём написано |
| Commands | Commands, Setup, Команды |
Как ставить, собирать, тестировать (строка - Test: `...` обязательна) |
| Conventions | Conventions, Code style, Соглашения |
Как писать код и коммиты |
| Boundaries | Boundaries, Don'ts, Запреты, Ограничения |
Чего не трогать |
| Definition of Done | Definition of Done, Done, Критерии готовности |
Как понять, что задача закончена |
Раздел Lessons необязателен, но именно он со временем даёт больше всего пользы.
python scripts\agents_lint.py # проверить AGENTS.md / CLAUDE.md в текущем каталоге
python scripts\agents_lint.py --strict # предупреждения тоже валят проверку
python scripts\agents_lint.py --check-commands # проверить, что команды есть в PATH
python scripts\agents_lint.py --json # машинный вывод
python scripts\agents_lint.py -r # монорепо: все AGENTS.md / CLAUDE.md в подкаталогахКоды выхода: 0 ок, 1 есть ошибки (или предупреждения при --strict), 2 неверный запуск.
| Код | Уровень | Что проверяется |
|---|---|---|
| E001–E004 | error | файл читается, UTF-8, не пустой, @импорты существуют (разделы из импортированного файла засчитываются) |
| E010 | error | есть все пять обязательных разделов |
| E020, E021 | error | в Commands есть команды и команда тестов (строкой - Test: `...` или в блоке кода) |
| E030 | error | не осталось заглушек <...>, {{...}}, TODO, TBD, FIXME |
| E040 | error | нет похожих на секреты строк (AWS, GitHub, OpenAI/Anthropic, Slack, Google, приватные ключи), включая HTML-комментарии |
| W011 | warning | раздел пустой |
| W022 | warning | команда не найдена в PATH (с --check-commands) |
| W050 | warning | путь в `обратных кавычках` не существует в репозитории |
| W060 | warning | повторяющиеся заголовки |
| W070 | warning | есть и AGENTS.md, и CLAUDE.md, но второй не импортирует первый |
| W101 | warning | файл больше 32 КиБ (Codex по умолчанию обрезает инструкции на этом размере) |
При старте или возобновлении сессии Claude Code выполняет scripts/session-start.sh. Его вывод попадает агенту в контекст, поэтому агент сразу знает, в порядке ли контракт и были ли тесты зелёными до его изменений. Хук всегда завершается с кодом 0 и не блокирует сессию.
Команды задаются переменными окружения (например, в env файла .claude/settings.json):
{ "env": { "AGENTS_SETUP": "pip install -e .", "AGENTS_TEST": "python -m pytest -q" } }AGENTS_SKIP_TESTS=1 отключает прогон тестов. Если на Windows нет Git Bash или нужен PowerShell-вариант, возьмите .claude/settings.windows.example.json: команда в нём использует относительный путь и работает из любой оболочки, потому что хуки запускаются из корня проекта.
Все цифры ниже получены скриптами из bench/, их можно перезапустить.
python bench/speed.py, Python 3.13, Linux, 4 vCPU, локальный диск, 200 повторов на размер:
| Размер файла | check(), медиана |
check(), p95 |
+ проверка путей, медиана | CLI целиком (холодный старт), медиана |
|---|---|---|---|---|
| 1.3 КиБ | 0.21 мс | 0.36 мс | 0.26 мс | 50 мс |
| 3.9 КиБ | 0.56 мс | 0.95 мс | 0.95 мс | 50 мс |
| 15.9 КиБ | 2.04 мс | 3.62 мс | 4.03 мс | 53 мс |
| 31.9 КиБ | 3.91 мс | 5.65 мс | 7.85 мс | 56 мс |
| 128.0 КиБ | 15.70 мс | 26.79 мс | 32.09 мс | 87 мс |
Время растёт линейно с размером. Для типичного контракта (1–4 КиБ) сама проверка занимает меньше миллисекунды, а полный запуск почти целиком уходит на старт интерпретатора Python (~50 мс). На сетевых дисках проверка путей заметно медленнее; её можно отключить флагом --no-paths.
python bench/ab_test.py --runs 5 берёт игрушечный репозиторий bench/ab-fixture (расчёт НДС) с тремя ловушками, которые не видны из задачи:
- ставки лежат в
rates.yaml, аinvoice/generated/rates.pyгенерируется скриптом, и править его руками нельзя; - голые
unittestиpytestпадают, тесты запускаются только черезpython3 run_tests.py; - по правилам команды каждое изменение записывается в
CHANGELOG.md.
Агент получает одну и ту же задачу «Добавь ставку НДС для Польши (PL) 23%.» в свежей копии репозитория: 5 раз без контракта и 5 раз с AGENTS.md. Результат оценивается автоматически по 5 критериям.
Claude Code в headless-режиме (claude -p), модель по умолчанию, 18.10.2026:
| Без AGENTS.md | С AGENTS.md | Разница | |
|---|---|---|---|
| Баллы (из 5) | 4.8 | 5.0 | +0.2 |
| Тесты зелёные | 5/5 | 5/5 | = |
Правка в источнике истины (rates.yaml) |
5/5 | 5/5 | = |
| Генерат синхронизирован, руками не правился | 5/5 | 5/5 | = |
| Добавлен тест | 5/5 | 5/5 | = |
| Запись в CHANGELOG | 4/5 | 5/5 | +1 прогон |
| Шагов агента (среднее) | 5.6 | 3.8 | −32% |
| Время (медиана) | 18.2 с | 12.9 с | −29% |
| Стоимость (среднее) | $0.091 | $0.084 | −8% |
Сырые данные: bench/results.json.
Как это читать честно. Сильная модель справляется с маленьким репозиторием и без контракта: она видит комментарий DO NOT EDIT и сама находит run_tests.py. Главный выигрыш здесь в том, что агенту не нужно исследовать репозиторий: шагов на треть меньше, разброс времени меньше (с контрактом всегда 3–4 шага, без него от 4 до 7). Единственное различие в качестве касается правила, которое из кода не вывести вообще (CHANGELOG). На больших репозиториях и с неочевидными правилами разница должна быть больше, но здесь это не измерялось.
Ограничения. 5 прогонов на условие слишком мало для статистической значимости. Задача одна и маленькая. Проверялся только Claude Code, без Codex, Cursor и Copilot. Модель и её версия влияют на результат. Для своего проекта лучше подставить свою фикстуру и задачу в bench/ab_test.py.
python -m unittest discover -s tests -v15 тестов: обязательные разделы, команда тестов (в том числе в блоке кода), импорты в CLAUDE.md, рекурсивный поиск в монорепо, заглушки (без ложных срабатываний на List<T> и <br>), секреты, русские заголовки, заголовки внутри блоков кода, размер, импорты, пути, CLI и коды выхода.
MIT