|
Professor Seleznov
|
В последнее время я активно использую Claude Code в своей разработке. По мере роста числа агентов я столкнулся с неожиданной проблемой — стало сложно синхронизировать их правила между разными системами.
Кроме того, появилось вполне рациональное опасение: в случае блокировки аккаунта можно потерять все наработки — команды, скилы и правила агентов, которые я собирал и оттачивал на протяжении нескольких месяцев. Это подтолкнуло меня к созданию удобной системы хранения конфигурации. Здесь важно зафиксировать простую мысль: директория ~/.claude/ — это такой же код. А код должен храниться в Git.
Так появился claude-config-template — репозиторий-шаблон, в котором живут скилы, агенты, команды, хуки и MCP-конфигурации. При этом сама папка ~/.claude/ собирается из него с помощью симлинков.
Если кратко, этот подход решает сразу три ключевые проблемы:
- конфигурация хранится в Git и легко переносится на любую машину;
- команда работает с единым набором агентов и скилов;
- набор линтеров (в pre-push хуках и GitHub Actions) отлавливает ошибки во frontmatter, YAML и JSON ещё до попадания в main.
Дальше расскажу, как устроен шаблон и почему именно симлинки, а не копирование, оказались оптимальным решением.
Структура репозитория
Если вы хотя бы раз заглядывали в ~/.claude/, структура этого шаблона вас не удивит.
skills/ пользовательские скилы (SKILL.md + ресурсы)
agents/ субагенты (отдельные .md с frontmatter)
commands/ слеш-команды
mcp/ примеры конфигов MCP-серверов
hooks/ PreToolUse / PostToolUse и прочие хуки
docs/ конвенции, гайды, changelog
scripts/ утилиты: линтер, генератор новых скилов
linting/ pre-push-хук и набор проверок
И это сделано намеренно: чем меньше различий между репозиторием и реальной рабочей директорией, тем проще всё переносится и поддерживается.
Например, вы просто кладёте SKILL.md в skills/my-skill/ — и уже через минуту он доступен в Claude Code так, будто всегда там и находился.
Сам репозиторий по умолчанию пустой: никаких готовых скилов или агентов. Есть только agents/example.md — в качестве минимальной заглушки.
По сути, claude-config-template — это ваш персональный конфиг. Вы форкаете его и наполняете под свои задачи.
Использование симлинков
Самое интересное в этом шаблоне — не структура, а способ подключения.
Механика максимально простая:
- Клонируете репозиторий
- Добавляете правила Claude Code в нужные директории
- Запускаете make install
- Скрипт создаёт симлинки в ~/.claude/, указывающие на файлы из репозитория
make install # создаёт ссылки в ~/.claude/
make uninstall # удаляет только наши ссылки, родные скилы не трогает
Важно: все ваши текущие файлы в ~/.claude/ остаются нетронутыми. make install ничего не копирует и не перезаписывает — он только создаёт ссылки.
Под капотом install.sh проходит по категориям (skills, agents, commands, hooks) и линкует каждый элемент отдельно.
ln -s "$REPO/skills/my-skill" "$CLAUDE_HOME/skills/my-skill"
ln -s "$REPO/agents/example.md" "$CLAUDE_HOME/agents/example.md"
Это принципиальный момент. Если бы мы линковали директории целиком (например, skills/), то затёрли бы встроенные скилы, которые Anthropic добавляет автоматически.
Поэлементная линковка позволяет избежать этого: системные и пользовательские файлы спокойно сосуществуют в одной директории.
Это важно. Если бы мы линковали целиком папку skills/, то затёрли бы встроенные скилы, которые Anthropic кладёт туда сама. Поэлементная линковка оставляет родные файлы в покое — наш репозиторий и встроенные скилы мирно живут в одной директории.
Что это даёт на практике:
- Изменения подхватываются мгновенно. Поправили SKILL.md в репозитории — Claude Code видит новую версию при следующем запуске. Не нужно копировать, переустанавливать, перезапускать что-то ещё.
- Один источник правды. Файл лежит в одном месте — в репозитории.
- Git-история — это история ваших скилов. Можно git blame по агенту, откатиться на старую версию, открыть PR на скил от коллеги.
- Чистый uninstall. install.sh --uninstall удаляет ровно те ссылки, которые создал, и проверяет, что они до сих пор указывают на репозиторий. Чужие файлы в ~/.claude/ не трогает.
Разумеется, у такого подхода есть и ограничения.
Если вы переместите репозиторий, симлинки «сломаются» — нужно будет снова запустить make install. Кроме того, если поверх симлинка вручную положить реальный файл, скрипт не станет его перезаписывать — он просто пропустит его.
Это осознанный компромисс: лучше ничего не трогать и избежать потери данных, чем случайно затереть чужую работу.
Пример вывода make install:
[skills]
+ /home/me/.claude/skills/my-skill -> /home/me/code/claude-config/skills/my-skill
= /home/me/.claude/skills/hello-test (already linked)
! /home/me/.claude/skills/manual-skill exists and is not a symlink. Skipping.
- + — создана новая ссылка
- = — ссылка уже существует
- ! — файл не наш, пропускаем
Перенос на новую машину
Когда скилы превращаются в обычный Git-репозиторий, перенос на новую машину становится тривиальной задачей:
git clone
cd
make install
И всё. Уже через несколько секунд в ~/.claude/ появляются симлинки на ваши скилы, агенты и команды.
Бонусом автоматически подключается и pre-push хук — install.sh создаёт ссылку из linting/pre-push-check.sh в .git/hooks/pre-push.
Если что-то пошло не так, есть команда make doctor. Скрипт scripts/doctor.sh проверяет:
- на месте ли симлинки
- установлены ли нужные версии Python, ruff, shfmt и других линтеров
- корректно ли читаются конфиги
На выходе — понятный отчёт: что работает, а что нужно доустановить или поправить.
Для ускорения работы есть ещё одна удобная команда: make new-skill name=my-skill desc="Что делает"
Она создаёт каркас нового скила с готовым frontmatter. Не нужно вспоминать структуру и обязательные поля — всё уже настроено, и шаблон сразу проходит линтер.
Линтеры и проверки
Скилы и агенты — это всего лишь Markdown с frontmatter. Казалось бы, что тут можно сломать.
На практике — очень многое. Достаточно:
- опечататься в имени поля
- забыть description
- нарушить YAML-синтаксис
И Claude Code просто молча проигнорирует часть файла — без ошибок и предупреждений.
Именно поэтому в шаблоне заложен довольно строгий (и местами параноидальный) набор проверок.
Они запускаются локально (через pre-push хук в linting/pre-push-check.sh) и в CI:
- lint_skills.py — проверяет frontmatter во всех SKILL.md и agents/*.md
- lint_commands.py — валидирует структуру commands/task_*.md по контракту
- shellcheck — анализирует shell-скрипты в linting/
- markdownlint — следит за стилем Markdown (.markdownlint.yml)
- yamllint — проверяет YAML (.yamllint.yml)
- ruff — линтинг Python-скриптов
- shfmt — форматирование shell-скриптов
- codespell — ищет опечатки в документации
- jsonschema — валидирует JSON и схемы .claude/settings*.json
- gitleaks — проверяет утечки секретов (опционально)
Каждая проверка оформлена как отдельный скрипт в linting/check_scripts/: check_shellcheck_all.sh, check_codespell_all.sh и так далее.
pre-push хук просто запускает их последовательно, а CI использует те же самые скрипты в виде отдельных джоб.
В результате — один источник правды для локальной разработки и для GitHub Actions.
Когда подход подойдёт, а когда нет
Я не считаю этот шаблон серебряной пулей или обязательным стандартом. Это просто инструмент, который хорошо решает конкретный класс задач — но не все подряд.
Он действительно начинает приносить пользу, если:
- у вас больше пары скилов или агентов, и вы хотите их системно хранить и развивать
- вы работаете с Claude Code на нескольких машинах и устали вручную переносить конфиги
- вам важно делиться наработками с командой — через pull request’ы, с историей изменений и обсуждением
- вы периодически переустанавливаете систему, меняете аккаунты или переключаетесь между устройствами
В этих сценариях Git + симлинки дают предсказуемость: конфигурация всегда под рукой, изменения отслеживаются, а окружение легко восстановить.
С другой стороны, этот подход может быть избыточным.
Если у вас:
- один-два простых скила
- работа только с одной машины
- и нет потребности в версионировании
— то обычный файл в ~/.claude/skills/ решит задачу быстрее и проще.
Не стоит поднимать инфраструктуру ради инфраструктуры. Если всё помещается в один SKILL.md, Git-репозиторий и набор линтеров, скорее всего, только усложнят жизнь, а не упростят её.
Итог
В итоге получился не просто шаблон, а удобный способ навести порядок в своей работе с Claude Code: хранить конфигурацию как код, контролировать изменения и не зависеть от конкретной машины или аккаунта.
Если вам откликнулась эта идея — поддержите проект ⭐️ на GitHub. Это действительно помогает другим разработчикам находить его и экономить время.
Важно: этот шаблон задумывался не как готовое решение «из коробки», а как отправная точка. Форкните репозиторий, адаптируйте под себя и соберите свой собственный конфиг — такой, который идеально ложится в ваш процесс.
Если захотите поучаствовать в развитии — буду рад: багрепорты, идеи для новых проверок и pull request’ы с улучшениями только приветствуются. Процесс описан в CONTRIBUTING.md.-Источник
|
