Всем привет! В новой статья я хотел бы поделиться своим опытов в работе с Claude Code.

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

Теперь я делаю больше акцент на проектирование системы, в которой этот код пишет AI.

В новой статье я расскажу о том:

• Как я использую Git для улучшения работы с AI

• Какую роль играют Git Hooks в моей системе

• Какие проверки я использую в CI и в Git Actions

• Как я настроил правила для Claude 

Далее давайте пройдёмся подробнее по каждому этапу настройки системы.

Git

Многие используют Git только как систему версий, я же пошёл чуть дальше.

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

Я придерживаюсь следующей архитектуры...

Для каждой задачи создаётся отдельная ветка, в название которой содержится номер задачи (например Issue из GitHub).

issues-123

Коммиты также содержат номера задач

issues-123 | add user registration

Такой подход даёт преимущество, как для людей, так и для AI. И те и другие легче ориентируется внутри проекта и всегда могу получить информацию о задаче по номеру указанному в название ветки.

Да и в целом такой подход приводит ваш репозиторий в адекватный, структурированный вид.

Git Hooks

Git Hooks одно из важнейших направлений в разработке с использованием AI.

Важно отлавливать ошибки до появления их в репозитория. Поэтому каждый мой проект имеет свой набор скриптов для Git Hooks.

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

https://github.com/prog-time/git-hooks

Данные скрипты запускаются автоматически перед созданием коммита или перед отправкой изменений в репозиторий.

Сами скрипты представляют из себя .sh файлы, которые обычно размещены в директории ./linting в корне проекта. Эти файлы подключаются в папке .git/hooks, внутри конкретного события (pre-commit или pre-push).

Там есть проверки разной направленности:

• Линтеры 

• Статические анализаторы

• Запуск автотестов

• Корректность названия ветки

• Проверка соответствия Code Style

Важное правило! Если хотя бы одна проверка вернет ошибку, значит процесс прерывается, пока Claude Code не исправит ошибки.

Для каждого языка программирования я использую свой набор проверок.

Например для PHP это:

• PHP Cs Fixer - для проверки code style

• PHPStan - статический анализатор, для проверки наличия ошибок

• Composer Validate - для проверки конфигурации composer

Для JavaScript:

• EsLint

Для HTML, CSS и SCSS:

• Prettier

• Stylelint

Также нужно учитывать, что очень часто ошибки появляются вовсе не в коде, поэтому я отдельно использую:

• Yamlint - для проверки YAML и YML 

• actionlint - для проверки GitHub Actions

• shellcheck - для проверки .sh файлов

• markdownlint - для проверки документации и прочих файлов в формате Markdown

Отдельно хочу отметить использование gitleaks, который помогает проверять файлы на наличие «секретов».

К таким относятся:

• API-ключи

• Токены 

• Пароли

• Приватные сертификаты

Все эти проверки позволяют защитить ваш проект от типичных ошибок и соблюдать единый стиль кода. Это делает AI более предсказуемым и позволяет создавать более качественные проекты.

Настройки CI или GitHub Actions

Отдельно хотел бы затронуть настройку CI.

Важно, чтобы локальные проверки через Git Hooks и конфигурация CI имели одинаковые проверки.

За несколько лет у меня накопилась своя библиотека GitHub Actions, которые я постоянно переиспользую в разных проектах.

Чтобы каждый раз не переписывать скрипты, я создал репозиторий workflow, который также находится в открытом доступе на GitHub.

https://github.com/prog-time/workflows

Для меня важно, чтобы Claude Code не придумывал свои CI конфигурации, так как эти проверки могут быть ненадёжными и пропускать опасные ошибки. Поэтому я требую Claude Code, чтобы он брал части конфигурации только из моего, проверенного репозитория.

Правила для Claude Code

Для генерации крупных проектов, одного умения писать промыты очень мало! Важно уметь грамотно проектировать архитектуру правил для AI.

Раз уж мы затрагиваем в данном посте Claude Code, давайте я расскажу свою систему хранения правил для агентов, скилов и команд, которые я использую в повседневной работе.

Агенты

Агент - это правило, которое обычно ассоциируется с участником команды.

Если у вас разработка, то это может быть backend-developer, frontend-developer и так далее.

Если рассматривать мой личный пример, то у меня есть агент task-writer, который отвечает за создание задач.

Он выполняет следующие действия:

• Получает ссылку на репозиторий из git origin

• Анализирует существующие Issues

• Читает шаблоны для формирования задач из проекта

• Пишет текст для задачи: описание задачи, критерии приёмки, связи между задачами, исполнителя и остальные поля

На этом его работа заканчивается! Далее другие агенты по прямому запросу или через агента team-lead будут читать его задачи и выполнять их. Но это уже другая история…

Команды

Если агент — это роль, то команда — это конкретное действие.

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

Вот опять пример из моей работы…

Продолжим развивать тему с задачами.

У меня есть команда /task_create, которая выполняет следующие действия:

• Принимает запрос для создания задачи. Например так: /task_create создай кнопку для восстановления пароля на странице авторизации

• Передаёт работу агенту task-writer. Тот в свою очередь подготавливает текст для задачи, посоветовавшись с агентом tech-lead

• Создаёт локальную копию задачи в каталоге /tasks

• Публикует Issue в GitHub и в чате выводит ссылку

Одна строка в запросе выполняет много отлаженых действий.

Скилы

Скилы это третий тип правил, которые описывают сценарий из нескольких действий.

Сам скилл обычно не выполняет действия, он только выступает в роли «оркестратора» передавая работу агентам и командам.

Например ci-setup выполняет следующую работу:

• Вызывает агента tech-lead для проверки стека технологий, которые используются в проекте

• Далее анализируется репозиторий prog-time/workflows и выбираются подходящие конфигурации

• На основе выбранного, агент devops собирает .github/workflows

Как я храню правила для Claude Code

Здесь тоже есть свои тонкости, о которых я уже рассказывал в предыдущей статье. В данной записи расскажу чуть покороче.

Хранения правил разделяется на 2 вида:

• Системное хранение, внутри ~/.claude

• И локальное хранение, внутри проекта в папке .claude

Я воспринимаю правила для AI, как код. А код должен всегда контролироваться git.

Если речь идёт о локальных версиях правил, достаточно просто добавить их в репозиторий проекта — и всё.

То с глобальными правилами всё гораздо сложнее, так как вы не можете загрузить директорию ~/.claude в репозиторий.

Во-первых, потому что она очень большая и хранит множество файлов логов.

Во-вторых, данная директория будет содержать все ваши сообщения, которые вы писали Claude Code, тем самым вызывая риск публикации конфиденциальной информации.

Чтобы избежать данных проблем, я создал проект claude-config-template.

Данный проект является шаблоном, который полностью копирует директорию ~/.claude, но имеет важную особенность - «Все ваши правила будут передаваться в ~/.claude через симлинки».

Процесс простой:

• Вы клоните данный проект

• Наполняете его своими файлами правил

• Запускаете команду make install и в директорию ~/.claude добавляются симлинки

Такой подход даёт много преимуществ:

1. Вы можете не бояться потерять свои файлы правил, ведь они будут находиться на стороне. Даже если вы потеряете доступ к аккаунту, ваши правила не удалятся.

2. Вы можете делиться правилами с командой и использовать единую систему правил. Для этого нужно просто клонировать ваш репозиторий на все машины.

3. Не нужно бояться затереть уже имеющиеся файлы правил, ведь команда make install просто не даст вам создать симлинк, если файл в таким названием уже присутствует в директории.

Опять же замечу важную вещь…

Проект claude-config-template это пустой шаблон, от которого вы можете создать форк и наполнить его своими файлами.

Итог

Важно грамотно подходить к проектированию окружения для работы с Claude Code. Чем лучше вы подготовите почву тем качественнее получится ваш проект и тем проще вам будет с ним работать.

Всегда зажимайте Claude Code в рамки. Максимального количества проверок не бывает, как и не бывает идеального набора правил. Вы должны каждый день дорабатывать правила и придумывать новые критерии приёмки работы от AI.

Ну и самое важное - цените своё время. Написание правил занимает огромное количество времени и важно ответственно подходить к хранению правил и прочих конфигураций.