
agents-contract
AGENTS.md contract for AI coding agents + zero-dependency linter + SessionStart hook. Works with Claude Code, Codex, Cursor, Copilot.
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up agents-contract (git-clone project) into my current project. Found on https://claudeers.com/agents-contract Repo: https://github.com/AntoGA/agents-contract Homepage/docs: https://cc-c.ru Detected install method: git-clone → git clone https://github.com/AntoGA/agents-contract Category: devtools. Platforms: cli. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
git clone https://github.com/AntoGA/agents-contract
// compatibility
| Platforms | cli |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Python |
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 (расчёт НДС) с тремя ловушками, которые не видны из задачи:
- ставки лежат в
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 -v
15 тестов: обязательные разделы, команда тестов (в том числе в блоке кода), импорты в CLAUDE.md, рекурсивный поиск в монорепо, заглушки (без ложных срабатываний на List<T> и <br>), секреты, русские заголовки, заголовки внутри блоков кода, размер, импорты, пути, CLI и коды выхода.
Лицензия
MIT
// faq
What is agents-contract?
AGENTS.md contract for AI coding agents + zero-dependency linter + SessionStart hook. Works with Claude Code, Codex, Cursor, Copilot.. It is open-source on GitHub.
Is agents-contract free to use?
agents-contract is open-source under the MIT license, so it is free to use.
What category does agents-contract belong to?
agents-contract is listed under devtools in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/agents-contract)
// retro hit counter
[](https://claudeers.com/agents-contract)
// reviews
// guestbook
// related in Developer Tools
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…
Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA