claudeers.
// Developer Tools

agents-contract

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

Actively maintained
95/100
last commit about 1 month ago
last release none
releases 0
open issues 0

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.
// or clone
git clone https://github.com/AntoGA/agents-contract

// compatibility

Platformscli
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguagePython

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

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.ps1SessionStart-хук: линтер, установка зависимостей, тесты
.claude/settings.jsonПодключение хука в Claude Code (bash; на Windows работает через Git Bash)
.claude/settings.windows.example.jsonВариант хука на чистом PowerShell
.github/workflows/agents-lint.ymlCI: тесты линтера и проверка на 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.

Структура контракта

Линтер требует пять разделов (заголовки на русском или английском):

РазделДопустимые заголовкиЗачем агенту
ProjectProject, Overview, Stack, О проекте, СтекЧто это и на чём написано
CommandsCommands, Setup, КомандыКак ставить, собирать, тестировать (строка - Test: `...` обязательна)
ConventionsConventions, Code style, СоглашенияКак писать код и коммиты
BoundariesBoundaries, Don'ts, Запреты, ОграниченияЧего не трогать
Definition of DoneDefinition 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–E004errorфайл читается, UTF-8, не пустой, @импорты существуют (разделы из импортированного файла засчитываются)
E010errorесть все пять обязательных разделов
E020, E021errorв Commands есть команды и команда тестов (строкой - Test: `...` или в блоке кода)
E030errorне осталось заглушек <...>, {{...}}, TODO, TBD, FIXME
E040errorнет похожих на секреты строк (AWS, GitHub, OpenAI/Anthropic, Slack, Google, приватные ключи), включая HTML-комментарии
W011warningраздел пустой
W022warningкоманда не найдена в PATH (с --check-commands)
W050warningпуть в `обратных кавычках` не существует в репозитории
W060warningповторяющиеся заголовки
W070warningесть и AGENTS.md, и CLAUDE.md, но второй не импортирует первый
W101warningфайл больше 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.85.0+0.2
Тесты зелёные5/55/5=
Правка в источнике истины (rates.yaml)5/55/5=
Генерат синхронизирован, руками не правился5/55/5=
Добавлен тест5/55/5=
Запись в CHANGELOG4/55/5+1 прогон
Шагов агента (среднее)5.63.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.

11 views
★ 34 stars
unclaimed
updated 30 days ago

// embed badge

agents-contract on Claudeers
[![Claudeers](https://claudeers.com/api/badge/agents-contract.svg)](https://claudeers.com/agents-contract)

// retro hit counter

agents-contract hit counter
[![Hits](https://claudeers.com/api/counter/agents-contract.svg)](https://claudeers.com/agents-contract)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 297,269◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

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,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how agents-contract connects across the ecosystem