AntoGA / agents-contract

# 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)
 [code] 
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` необязателен, но именно он со временем даёт больше всего пользы.
## Линтер
 [code] 
Коды выхода: `0` ок, `1` есть ошибки (или предупреждения при `--strict`), `2` неверный запуск.
| Код | Уровень | Что проверяется |
|---|---|---|
| E001–E004 | error | файл читается, UTF-8, не пустой, `@импорты` существуют (разделы из импортированного файла засчитываются) |
| E010 | error | есть все пять обязательных разделов |
| E020, E021 | error | в `Commands` есть команды и команда тестов (строкой `` - Test: `...` `` или в блоке кода) |
| E030 | error