Skip to content

About

AGENTS.md contract for AI coding agents + zero-dependency linter + SessionStart hook. Works with Claude Code, Codex, Cursor, Copilot.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

agents-contract

Один файл 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-тест агента

Быстрый старт (Windows, PowerShell)

# в корне вашего репозитория
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 по умолчанию обрезает инструкции на этом размере)

SessionStart-хук

При старте или возобновлении сессии 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.

A/B-тест агента

python bench/ab_test.py --runs 5 берёт игрушечный репозиторий bench/ab-fixture (расчёт НДС) с тремя ловушками, которые не видны из задачи:

  1. ставки лежат в rates.yaml, а invoice/generated/rates.py генерируется скриптом, и править его руками нельзя;
  2. голые unittest и pytest падают, тесты запускаются только через python3 run_tests.py;
  3. по правилам команды каждое изменение записывается в 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 -v

15 тестов: обязательные разделы, команда тестов (в том числе в блоке кода), импорты в CLAUDE.md, рекурсивный поиск в монорепо, заглушки (без ложных срабатываний на List<T> и <br>), секреты, русские заголовки, заголовки внутри блоков кода, размер, импорты, пути, CLI и коды выхода.

Лицензия

MIT

About

AGENTS.md contract for AI coding agents + zero-dependency linter + SessionStart hook. Works with Claude Code, Codex, Cursor, Copilot.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages