Agent-rules-skill

Agent Rules v2.0

Правила работы агента, которые переживают любой харнесс.

Набор правил, ролевых контрактов и проектной памяти для ИИ-агентов, которые кодируют. Не промпт и не персона: это операционная система репозитория — луп проверки, шесть ролей, память, переживающая сжатие контекста, и исполняемые проверки вместо просьб «обязательно».

Работает в Claude Code, OpenAI Codex CLI, Cursor, Gemini CLI, Windsurf, Cline, Aider, OpenCode, Factory Droid, GitHub Copilot Agent — и в любом будущем агенте, который умеет читать текстовый файл инструкций.

git clone git@github.com:Samiixo/Agent-rules-skill.git

Что было в v1 и что изменилось

v1 был честным, но Claude-специфичным: роли лежали в .claude/agents/*.md с захардкоженным model: opus, ядром был CLAUDE.md, все ссылки внутри указывали на .claude/rules/.... Перенести это в Cursor или Gemini CLI было невозможно без ручной переработки каждого файла.

v2.0 — это тот же пакет, но переносимый:

Найденные при переносе дефекты v1, которые теперь закрыты тестами:

• ядро ссылалось на docs/stream/CHANGES/, которого не было в пакете;
• docs/stream/STATE.md объявлялся «перезаписываемым», но шаблон содержал инструкции по append-стилю;
• .claude/hooks/block-secrets.sh зависел от jq, которого может не быть;
• инструкция про memory: у субагентов была Claude-only и не имела переносимого эквивалента;
• все файлы содержали typographic dashes, которые ломались в консоли cp1251.

Что внутри

Agent-rules-skill/
├── AGENTS.md                 ядро, < 200 строк (RAM)
├── SKILL.md                  вход для агента: когда применять
├── CLAUDE.md                 адаптер под Claude Code
├── rules/
│   ├── karpathy.md            поведение: минимально, хирургически, по цели
│   ├── bayes.md               решения на коэффициентах правдоподобия
│   └── forbidden.md           «никогда» для этого репозитория
├── agents/
│   ├── architect.md           цель -> спеки. Кода не пишет
│   ├── implementer.md         ровно один спек за раз
│   ├── verifier-spec.md       механическая проверка по критериям, read-only
│   ├── verifier-adversarial.md независимый критик
│   ├── fixer.md               чинит только найденное
│   ├── risk-assessor.md       байесовский pre-mortem
│   └── README.md              как зарегистрировать роли в ЛЮБОМ харнессе
├── references/
│   ├── context-budget.md      почему ядро должно быть маленьким
│   ├── adapters.md            таблица портирования по харнессам
│   ├── stream-memory.md       4-слойная память с шаблонами
│   ├── deterministic-guards.md хуки vs проза, три уровня подключения
│   └── bayes.md               полный справочник движка решений
├── tools/
│   ├── doctor.py              проверить, что проект настроен верно
│   ├── block-secrets.py       гард, fail-closed, маскирует значения
│   ├── context_report.py      измерить RAM/disk-разделение
│   └── install.py             установка в проект, --dry-run безопасен
├── docs/stream/
│   ├── STATE.md               «сейчас», перезаписывается, verified-факты
│   ├── CHANGES/               append-only поток, файл на сессию
│   ├── LEARNINGS.md           пойманная ошибка -> постоянное правило
│   └── DECISIONS.md           журнал решений со ссылкой на EV-таблицу
└── tests/run_selftest.py      7 тестов; exit 0 = пакет цел

Главная идея

Проза исполняется вероятностно. Исполняемые гарды исполняются всегда.

Текстовое правило «никогда не коммить секреты» агент нарушит с вероятностью, зависящей от настроения, длины контекста и фазы. Хук, который возвращает exit 2, нарушить нельзя. Поэтому всё, что должно происходить всегда, в v2.0 лежит в tools/, а не в прозе.

Вторая опора: агент не проверяет сам себя. Модель, разглядывающая свой собственный вывод, не проверяет его — она предсказывает, как выглядел бы вывод, и выглядит он правдоподобно. Отсюда два независимых верификатора с чистым контекстом, а не «и проверь заодно».

Память

Четыре слоя, потому что контекст сжимается посреди задачи, а сессия заканчивается:

• STATE.md — «сейчас». Перезаписывается, не растёт, только проверенные факты. «Должно работать» — не факт.
• CHANGES/ — append-only, файл на сессию, строка на шаг. Пишется во время работы, не в конце: если контекст умрёт, уцелеет именно это.
• LEARNINGS.md — каждая пойманная ошибка становится постоянным правилом в том же тюне, где исправлена.
• DECISIONS.md — необратимые решения с апостериорной таблицей и проигравшим вариантом.

Быстрый старт

git clone git@github.com:Samiixo/Agent-rules-skill.git
cd Agent-rules-skill

# проверить пакет
python tests/run_selftest.py

# посмотреть, что будет записано в проект, ничего не меняя
python tools/install.py --target /path/to/project --dry-run

# поставить
python tools/install.py --target /path/to/project

# проверить, что всё встало
python tools/doctor.py /path/to/project

Дальше:

1. Заполнить блок Project в AGENTS.md: точные команды test/build/lint. Незаполненная команда означает непроверенную область — агент не должен её угадывать.
2. Зарегистрировать роли из agents/ в своём харнессе. Таблица маппинга — в references/adapters.md, назначение на модели — в agents/README.md.
3. Первую задачу сформулировать как бинарную цель и посмотреть, как крутится луп implementer -> 2 верификатора -> fixer.
4. Каждую пойманную ошибку сразу писать в docs/stream/LEARNINGS.md.
5. Через пару недель: перенести повторяющиеся правила в rules/forbidden.md.

Требуется Python 3.9+, только стандартная библиотека.

Честно о границах

references/adapters.md помечает каждый механизм как Stated (можно опираться) или Verify (надо сверить с документацией своего харнесса). Например, для Cursor и Gemini CLI точные имена файлов субагентов и схема хуков помечены как Verify — я не стал выдумывать API, потому что неверная строка в таблице адаптера хуже её отсутствия: агент в неё поверит и настроит неправильно. Сверил, зафиксировал у себя — таблица твоя.

English summary

Portable working rules for any AI coding agent. v2.0 removed every Claude-specific path and vendor model name: the core is now AGENTS.md, roles declare capabilities (read, search, write, shell, delegate) and a relative tier (strong / mid / cheap) that the host maps to its own models.

The pack adds what prose cannot do: tools/doctor.py validates that a project is actually set up correctly, tools/block-secrets.py fails closed (exit 2 blocks) and masks values in its own output, tools/context_report.py measures the RAM/disk split, and tests/run_selftest.py covers the whole thing in 7 tests. All Python 3.9+, stdlib only, ASCII output so it survives a cp1251 console.

references/adapters.md is a porting table for Claude Code, Codex CLI, Cursor, Gemini CLI, Windsurf, Cline, Aider, OpenCode, Factory Droid and Copilot Agent, with a generic recipe for everything else. Each mechanism is marked Stated or Verify; nothing is invented. Hosts without subagents run the roles sequentially with a forced clean context for verification. Hosts without hooks fall back to a pre-commit hook and a CI step.

MIT licensed.

Лицензия

MIT, Copyright (c) 2026 Samiixo. Взносы идей: поведенческие правила — по наблюдениям Андрея Карпатого; луп-инжиниринг и паттерн «независимый верификатор» — Борис Черный; слой решений на коэффициентах — стандартная форма обновления odds, адаптированная под диагностику кода. Все они указаны в NOTICE.md.