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

Введение

Три месяца назад ты потратил несколько вечеров на настройку рабочего агента. Научил его писать коммиты в нужном формате, сделал код-ревьюера с характером, прописал правила для своего стека. Агент знает, что ты пишешь на TypeScript и терпеть не можешь any. Показываешь знакомым — удивляются, как хорошо работает.

А потом приходит письмо: «Your account has been suspended.»

Это не фантастика. За последний год задокументированы десятки таких случаев — иногда за реальное нарушение, иногда триггер случайный: например, Claude Code Action в цикле PR-ревью срабатывал как «подозрительный bot-like activity» и аккаунт улетал.¹ Когда аккаунт заблокирован, теряешь доступ ко всему: истории, настройкам, MCP-серверам (расширениям, которые дают агенту доступ к внешним сервисам вроде GitHub или базы данных) — всему.²

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

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

---

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

В сообществе часто путают «скилл» и «агент».

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

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

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

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

---

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

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

Инструмент	Где живут настройки	Главный файл
Claude Code	~/.claude/	CLAUDE.md
Codex CLI	~/.codex/	AGENTS.md
Gemini CLI	~/.gemini/	GEMINI.md
Cursor	~/.cursor/rules/	.mdc-файлы

Внутри у каждого — своя логика. Для примера возьмём Claude Code как самый распространённый:

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

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

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

Вся эта инфраструктура живёт на твоей машине. Инструмент читает её при старте — и получаешь настроенного агента.

Работает хорошо. До тех пор, пока что-то не идёт не так.

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

• Бан или деактивация аккаунта → нет доступа ни к истории, ни к настройкам
• Новый компьютер → все папки пустые, начинай заново
• Переустановка системы → то же самое
• Сброс Claude Code (иногда помогает при странных багах) → официальная документация пишет честно: «удаляет все настройки, MCP-серверы и историю сессий»⁵

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

---

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

Попробуй думать об агенте как о сотруднике. Ты не нанимаешь одного человека, который одновременно разрабатывает архитектуру, рисует UX, проводит код-ревью и пишет копирайтинг. Это разные профили, разный характер, разные ценности. С агентами — то же самое, и это часто упускают из виду.

Любой агент — Claude Code, Codex, Cursor, неважно — по умолчанию универсальный ассистент. Старается угодить, смягчает углы, редко возражает. Для широкой аудитории это хорошо. Для конкретной рабочей задачи — нет.

Смотрите сами.

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

Дизайнер-брейнштормер. Другая температура. Генерирует 20 идей и не фильтрует. Говорит «а что если сделать наоборот» вместо «давайте остановимся на надёжном варианте». Провокации приветствуются.

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

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

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

И эти файлы с профилями надо хранить в репозитории. Потому что агент с хорошим профилем — результат месяцев итераций, а не пяти минут.

---

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

Есть несколько вариантов.

Локально на компьютере. Просто помнить про эти папки и делать ручные копии куда-то. Поначалу кажется достаточным. Потом ломается диск или приходит новый MacBook — и ты снова с нуля.

Облачное хранилище (Google Drive, Dropbox, iCloud). Синхронизация есть, знание git не нужно. Но нет истории изменений — если сделал что-то не то, откатиться некуда.

GitLab или Gitea. Полноценные альтернативы GitHub. GitLab предлагает self-hosted вариант для тех, кто хочет полный контроль над сервером. Чуть сложнее для начинающих.

GitHub. Мой выбор — и объясняю почему именно для новичков.

Главная причина — GitHub Desktop. Это приложение с графическим интерфейсом: кнопка «Commit», кнопка «Push», кнопка «Clone».⁸ Никакого терминала, никаких команд. Скачивается бесплатно, работает на Mac и Windows.

Ещё: бесплатные приватные репозитории без ограничений.⁹ Твои настройки — только твои.

И ещё: GitHub — стандарт. Большинство гайдов и скриптов написаны под него. Меньше трений при поиске помощи.

Концепция не нова: разработчики хранят dotfiles — .bashrc, .zshrc, .vimrc, .ssh/config — в git уже полтора десятка лет. Та же логика применяется к .claude/.¹⁰ Когда видишь репозиторий под названием «dotfiles» у опытного разработчика — это именно оно.

---

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

Я держу свои настройки публично: 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 ссылается на отдельные файлы-модули через @-импорты:

Файл	Что описывает
persona.md	Характер агента: как думает, как спорит, как признаёт незнание
style.md	Стиль общения: язык, длина ответов, тон, эмодзи
writing-voice.md	Голос для текстов от имени автора — коммиты, посты, статьи
coding-standards.md	Принципы написания кода: YAGNI (не пиши то, что не нужно прямо сейчас), тесты, никакого мёртвого кода
git-workflow.md	Conventional Commits (формат: feat(auth): добавить вход через GitHub), ветки, PR-формат
hard-gates.md	Чего никогда нельзя: коммитить секреты, пропускать хуки, делать rm -rf без подтверждения
red-flags.md	Паттерны-ловушки: except Exception:, hardcoded URL, any в TypeScript
python.md / typescript.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 идёт системный промпт: что проверять, в каком порядке, как форматировать вывод.

Все шесть:

Агент	Роль	Модель
code-reviewer	Жёсткое code review: безопасность, тесты, dead code	Opus
debugger	Диагностика багов, не решение симптомов	Sonnet
fastapi-backend	Python/FastAPI: эндпоинты, схемы, миграции	Sonnet
ml-helper	ML-пайплайны, воспроизводимость, датасеты	Sonnet
next-frontend	Next.js/React: серверные компоненты, хуки, роутинг	Sonnet
pr-writer	PR-описания и коммит-сообщения	Haiku

Код-ревьюер на 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>/ перед перезаписью.

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

Поэтому сначала — docs/setup/customization.md. Там чеклист из пяти секций, у каждой готовый промпт. Копируешь в 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

И главное: если что-то настроил и работает — закоммить сразу. Не через неделю, а сразу. «Через неделю» превращается в «никогда», а потом снова теряется при переезде.

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

---

Как итог

• Скилл — инструкция. Агент — исполнитель с инструкциями и профилем. Профиль определяет характер: жёсткость, креативность, системность. Оба надо хранить в репозитории.
• Настройки внутри инструмента теряются при бане, смене машины или сбросе. Авто-память ненадёжна. Единственное стабильное хранилище — git.
• У каждого инструмента своё место для настроек. AGENTS.md — открытый стандарт, который через обёртки читают Claude Code, Codex, Gemini CLI и Cursor. Одни правила, несколько инструментов.
• Git — лучший способ: история изменений, откат, установка на новой машине за 30 минут. Для новичков — GitHub + GitHub Desktop без командной строки.
• Начать можно с готового репозитория tsergeytovarov/ai-settings, пройдя кастомизацию через customization.md.

---

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

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

Термин	Что это
MCP-сервер	Расширение для AI-агента, которое даёт ему доступ к внешним сервисам: GitHub, базе данных, браузеру.
Агент	Языковая модель + контекст + инструменты. Claude Code, Cursor, Codex — агенты.
Скилл	Файл с инструкциями для агента. Вызывается командой вроде /review-code.
Субагент	Специализированный агент внутри основного: код-ревьюер, дизайнер, продакт.
Frontmatter	YAML-заголовок в начале файла с метаданными: имя, модель, инструменты. Выглядит как блок между тремя дефисами ---.
Симлинк	Ярлык в файловой системе — указывает на другой файл. Меняешь оригинал — ярлык автоматически показывает новое содержимое.
Идемпотентный	Безопасно запускать повторно: одинаковый результат что в первый, что в пятый раз.
Dotfiles	Конфигурационные файлы, начинающиеся с точки: .zshrc, .vimrc. Разработчики хранят их в git для переноса на новую машину.
Git	Система контроля версий. Отслеживает историю изменений файлов, позволяет откатиться.
Репозиторий	Папка под управлением git. Хранится локально и дублируется на GitHub.
AGENTS.md	Открытый стандарт файла с инструкциями для AI coding-агентов. Читается Claude Code, Codex, Cursor и другими.
YAGNI	You Aren't Gonna Need It — не пиши код «на будущее», только то, что нужно прямо сейчас.
Conventional Commits	Стандарт для коммит-сообщений: тип(scope): описание. Например: feat(auth): добавить OAuth.
Race condition	Баг, при котором два потока одновременно меняют одни данные без синхронизации — результат непредсказуем.
OWASP top-10	Список из 10 самых опасных уязвимостей в веб-приложениях: SQL-инъекции, XSS, подмена чужого ID и т.д.
RSC	React Server Components — компоненты React, которые рендерятся на сервере, а не в браузере.
Dead code	Код, который написан, но никогда не выполняется. Засоряет проект и запутывает.
Upstream	Оригинальный репозиторий, от которого ты сделал форк.
Per-project	Настройки, которые применяются только к одному конкретному проекту, а не глобально.

---

Источники

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