Зачем выносить настройки AI-агентов в репозиторий и как это сделать

Как хранить инструкции, скиллы и субагентов в git и не потерять рабочую систему.

Аккаунт забанят, компьютер сломается, инструмент решишь сбросить, и все настройки агента пропадут. Я давно пришёл к простой схеме: CLAUDE.md, скиллы и субагентов надо держать в git-репозитории. Тогда переезд на новую машину занимает примерно 30 минут, а не несколько вечеров боли.

Введение

У меня на это когда-то и ушло несколько вечеров. Я научил рабочего агента писать коммиты в нужном формате, сделал код-ревьюера с характером, прописал правила под свой стек. Он знает, что я пишу на TypeScript и не терплю any. Показываешь это знакомым, и люди удивляются, насколько хорошо такая штука работает.

А потом прилетает: «Your account has been suspended.»

Такое реально бывает. За последний год задокументированы десятки таких случаев: иногда за реальное нарушение, иногда триггер вообще случайный. Например, Claude Code Action в цикле PR-ревью срабатывал как suspicious bot-like activity, и аккаунт улетал.1 Когда аккаунт блокируют, ты теряешь доступ ко всему: истории, настройкам, MCP-серверам, то есть расширениям с доступом к GitHub, базе и другим внешним сервисам.2

Или без бана. Новый MacBook. Открываешь терминал, а папки пустые. Начинай сначала.

Поэтому я храню настройки отдельно от инструмента, в git-репозитории. Один раз потратил полчаса на установку, потом просто благодаришь себя при каждом переезде.

Сначала — два слова про термины

Тут постоянно путают скилл и агента.

Скилл — это набор инструкций. Файл, который говорит агенту, что делать при вызове. Сам по себе он ничего не запускает. Это просто текст с правилами. Пример — скилл /review-code, который гоняет код по конкретному чеклисту.

Агент — штука шире. Это языковая модель, контекст, инструменты и иногда история разговора. Claude Code — агент. Cursor — агент. Внутри Claude Code можно собирать специализированных субагентов: код-ревьюера, продакта, дизайнера. У каждого свои инструкции и свой характер.

Короче: скилл — инструкция. Агент — исполнитель с инструкциями.

И то и другое — файлы. Им место в репозитории, а не только на одной машине.

Где сейчас живут настройки

У каждого инструмента своя папка в домашней директории (~/ — это /Users/твоё-имя на Mac или C:\Users\твоё-имя на Windows) и свой главный файл с инструкциями.

Для примера возьму Claude Code:

~/.claude/
├── CLAUDE.md          — главный файл с инструкциями агента
├── settings.json      — технические настройки: разрешения, deny-list
├── skills/            — скиллы: /write-commit, /review-code и т.д.
├── agents/            — субагенты: code-reviewer.md, pm.md и т.д.
└── rules/             — правила для конкретных паттернов файлов

AGENTS.md — открытый стандарт, который поддерживают Claude Code, Codex, Gemini CLI, Cursor и десятки других инструментов.3 Я делаю так: один общий AGENTS.md, а каждый инструмент читает его через свою тонкую обёртку CLAUDE.md, GEMINI.md и так далее. В обёртке лежит @-импорт, то есть встроенный способ подтянуть содержимое другого файла при загрузке.4

Плюс в корне каждого проекта могут лежать свои .claude/ или AGENTS.md с проектными настройками. Они дополняют глобальные.

Пока всё это живёт на твоей машине, схема работает. До первого сбоя.

Что именно теряется без бэкапа:

Бан или деактивация аккаунта: нет доступа ни к истории, ни к настройкам
Новый компьютер: папки пустые, начинай заново
Переустановка системы: то же самое
Сброс Claude Code: официальная документация прямо пишет, что он удаляет все настройки, MCP-серверы и историю сессий5

Отдельно про авто-память. Claude Code умеет записывать заметки к следующей сессии, и это удобно. Но задокументированы баги, когда эти файлы памяти не подхватывались при следующем старте.6 Делать из этого основное хранилище — плохая идея.

Агент — это исполнитель с профилем

Я вообще не верю в одного универсального агента на все случаи. Человек, который одновременно проектирует архитектуру, кидает 20 сырых идей, делает код-ревью и пишет копирайтинг, почти всегда будет средним во всём. С агентами то же самое.

По умолчанию любой агент старается угодить. Сглаживает углы. Редко спорит. Для широкой аудитории это нормально. Для работы — так себе.

Поэтому я развожу роли.

Код-ревьюер должен быть жёстким. Нашёл race condition, то есть два потока одновременно трогают один счётчик без блокировки, и данные поплыли, значит пишет про это прямо. Проверяет OWASP top-10 на любом пути с пользовательским вводом: SQL-инъекции, подмену чужого ID, небезопасную загрузку файлов и прочие базовые дыры. Не пишет «в целом хорошо». Пишет файл:строка — вот что сломано и почему.

Дизайнер-брейнштормер — другая история. Ему не надо быть осторожным. Он генерирует 20 идей, не фильтрует и спокойно говорит: а что если сделать наоборот.

Продакт должен задавать неудобные вопросы. Когда я говорю «хочу добавить фичу», он не помогает сразу, а спрашивает: зачем, какую боль это закрывает, кто это просил. Пока проблема не сформулирована, решения не будет.

Разработчик — системный. Пишет тесты до кода. Предлагает архитектуру. Коммитит часто и маленькими кусками. Не терпит any в TypeScript и голые except: в Python.

Всё это настраивается через persona.md, то есть файл с характером, ценностями и стилем работы агента, или прямо через frontmatter субагента — короткий YAML-заголовок в начале файла с метаданными: имя, роль, модель, инструменты. Конкретная персона с чётким профилем работает заметно лучше общих инструкций вроде «будь полезным».7 «Старший инженер, который ставит корректность выше скорости и спорит по делу даже под давлением» — это профиль. «Будь дружелюбным» — нет.

И эти файлы тоже надо хранить в репозитории. Хороший профиль собирается месяцами, а теряется за минуту.

Где хранить настройки

Вариантов несколько. Нормальный для меня один.

Оставить всё локально. Можно. Пока не умрёт диск и пока не приедет новый ноутбук.

Скинуть в облако вроде Google Drive, Dropbox или iCloud. Синхронизация будет, знание git не нужно. Но истории изменений нет. Если что-то испортил, откатываться некуда.

Уйти в GitLab или Gitea. Это полноценные альтернативы GitHub. У GitLab есть self-hosted вариант, если нужен полный контроль над сервером. Но для новичка это чуть тяжелее.

Взять GitHub. Это мой выбор.

Главная причина — GitHub Desktop.8 Это графическое приложение с кнопками Commit, Push и Clone. Без терминала и без команд. Скачивается бесплатно, работает на Mac и Windows.

Вторая причина — бесплатные приватные репозитории без ограничений.9 Настройки остаются только твоими.

Третья — GitHub это стандарт. Большинство гайдов, шаблонов и скриптов написаны под него. Когда надо что-то быстро нагуглить или попросить помощи, трения меньше.

Сама идея не новая. Разработчики лет 15 держат в git свои dotfiles: .bashrc, .zshrc, .vimrc, .ssh/config.10 С настройками агентов логика та же. Только вместо .vimrc у тебя теперь .claude/.

Готовый репозиторий: как не начинать с нуля

Я держу свои настройки публично: github.com/tsergeytovarov/ai-settings.

Главный файл — `AGENTS.md`

AGENTS.md в корне — единый источник правил для всех инструментов. Claude Code читает его через CLAUDE.md, где лежит @./AGENTS.md и больше ничего. Gemini CLI — через GEMINI.md. Codex и Cursor получают плоскую версию с уже развёрнутыми импортами через скрипт.

Поменял одну строчку в AGENTS.md, и она приехала везде.

Модули в `docs/ai/`

AGENTS.md ссылается на отдельные файлы-модули через @-импорты.

Каждый модуль можно править отдельно. У тебя другой стек — меняешь typescript.md на свой.

Субагенты в `agents/`

У меня там шесть специализированных исполнителей. Вот так выглядит frontmatter реального код-ревьюера:

---
name: code-reviewer
description: |
  Use after completing a major implementation step, or when the user asks
  "review this / check the code / look at the diff", or before any commit.
  SKIP: trivial doc-only changes, cosmetic refactors, pure design discussions.
model: opus
tools: [Read, Grep, Glob, Bash]
---

После frontmatter идёт системный промпт: что проверять, в каком порядке и как форматировать вывод.

Всего субагентов шесть. Код-ревьюер сидит на Opus, потому что должен находить то, что остальные пропускают. PR-writer сидит на Haiku, потому что задача механическая и тратить дорогую модель на неё жалко.

Скиллы в `skills/`

Тут два типа: для разработки (skills/code/) и для рабочих процессов (skills/work/).

Скилл /ru-commit-message работает очень просто. Я написал код, добавил изменения в индекс и вызвал:

/ru-commit-message

Дальше агент сам читает git diff --staged, разбирает изменения и возвращает готовое сообщение:

feat(auth): добавить вход через GitHub OAuth

Закрываем задачу #42. Обычный логин/пароль остаётся как fallback.

Без дополнительных инструкций. Вызвал и получил текст в нужном формате.

Что делает `install.sh`

Скрипт раскладывает содержимое репозитория по нужным местам.

Для Claude Code создаёт симлинки, то есть файловые ярлыки: ~/.claude/CLAUDE.md → ~/ai-settings/CLAUDE.md, ~/.claude/agents → ~/ai-settings/agents и так далее
Для Gemini CLI создаёт симлинк ~/.gemini/GEMINI.md → ~/ai-settings/GEMINI.md
Для Codex CLI генерирует плоский файл ~/.codex/AGENTS.md с развёрнутыми импортами, потому что Codex сам их не резолвит
Для Cursor синхронизирует .mdc-файл в ~/.cursor/rules/; у Cursor нет стабильного глобального механизма, поэтому для надёжности используется per-project через scripts/init-project.sh

Скрипт можно гонять повторно. Результат будет тем же. Перед перезаписью существующие файлы складываются в backups/<timestamp>/.

Как кастомизировать под себя

Это мой личный пресет. Персона зовётся Борис, стек Python + Next.js + Yandex Cloud, сообщения коммитов на русском. Если просто клонировать репозиторий и запустить install.sh как есть, получишь меня, а не себя.

Поэтому сначала надо открыть docs/setup/customization.md. Там чеклист из 5 секций, и у каждой есть готовый промпт. Копируешь его в Claude, он задаёт 5–6 вопросов по одному и возвращает готовый файл под твои ответы. Персона, стиль, стек, правила — всё переписывается под тебя.

По времени это выглядит так:

Клонировать репозиторий — 2 минуты
Пройти customization.md — 20–30 минут
Запустить install.sh — 2 минуты

git clone https://github.com/tsergeytovarov/ai-settings.git ~/ai-settings
cd ~/ai-settings
# 1. Открой docs/setup/customization.md, пройди чеклист
# 2. Запусти:
./scripts/install.sh

Если с GitHub пока сложно

Если ты никогда не работал с git и не хочешь разбираться сам, можно отдать это агенту. Открываешь Claude и пишешь:

Объясни мне по шагам, как:
1. Создать аккаунт на GitHub
2. Установить GitHub Desktop
3. Создать приватный репозиторий
4. Склонировать репозиторий на мой компьютер
5. Сделать первый коммит и запушить изменения

Объясняй каждый шаг простыми словами, как будто я никогда не работал
с git. После каждого шага жди подтверждения, что я его выполнил.

За 20–30 минут этот путь проходится под руководством агента.

Что класть в репозиторий дальше

Базовая схема уже работает. Дальше я просто складываю туда всё, что накапливается по дороге.

Промпты, которые хорошо сработали, — в examples/. Новый скилл для повторяющейся задачи — в skills/. Субагент для нового типа работы — в agents/. Проектные инструкции — через scripts/init-project.sh в корне конкретного проекта.

Если вы используете это в команде, форкайте репозиторий на свой аккаунт и меняйте под себя. Когда в оригинале появятся обновления, которые захочется подтянуть, команда такая:

git remote add upstream https://github.com/tsergeytovarov/ai-settings.git
git fetch upstream
git merge upstream/main

Как итог

И ещё важная вещь. Если что-то настроил и оно работает, коммить сразу. Не через неделю. Через неделю это почти всегда превращается в никогда, а потом всё снова теряется при переезде.

Скилл — это инструкция. Агент — исполнитель с профилем. Оба надо версионировать. Настройки внутри инструмента ненадёжны: бан, новая машина, сброс, баг с памятью, и всё. AGENTS.md даёт один слой правил на несколько инструментов. Git даёт историю, откат и нормальную установку на новой машине. Если только начинаешь, GitHub + GitHub Desktop закрывают входной барьер без командной строки.

Начать можно с готового репозитория tsergeytovarov/ai-settings, пройти кастомизацию через customization.md и дальше уже патчить систему под себя.

Про то, как хранить в репозитории память по проектам и другие накопленные данные, расскажу отдельно.

Словарь терминов из этой статьи

Если выше встретилось что-то непонятное. Полный глоссарий живёт отдельно, здесь только то, что понадобилось в этой статье.

Источники

False-positive ban on PR review loop — задокументированные случаи случайных банов при работе с PR-ревью
Claude AI Account Banned — что происходит с данными и настройками при бане аккаунта
AGENTS.md open standard — открытый стандарт для настройки AI coding-агентов, принятый в Linux Foundation
Anatomy of .claude/ Folder — разбор структуры папки Claude Code
Claude Code Troubleshooting — официальная документация, раздел про сброс настроек
Claude Code Memory Persistence Issue — баги с авто-памятью между сессиями
Persona-based AI approach — почему конкретная персона работает лучше общих инструкций
GitHub Desktop — GUI для git без командной строки, бесплатный для macOS и Windows
GitHub Pricing — бесплатные приватные репозитории без ограничений
Storing Dotfiles in Git — классический подход разработчиков к версионированию конфигов
tsergeytovarov/ai-settings — репозиторий с настройками и установщиком
Claude Code Sub-agents Docs — официальная документация по субагентам
Claude Code Settings Docs — официальная документация по структуре настроек