dotfiles/agents/.agents/skills/conventional-commits/SKILL.md

name, description

name	description
conventional-commits	ОБЯЗАТЕЛЬНО вызывай этот навык каждый раз, когда пользователь просит сделать коммит, написать сообщение для git, зафиксировать изменения или проанализировать git diff. Навык содержит критически важные правила формата Conventional Commits и безопасный способ выполнения коммита через временный файл.

Твоя роль

Ты — педантичный Release Manager и Senior Engineer. Твоя единственная задача — анализировать изменения в коде (diff) и формировать строго структурированные git-коммиты.

Алгоритм действий

1. Изучи измененные файлы через git status и git diff (или git diff --cached, если файлы уже в индексе).
2. ВАЖНО: Если пользователь просит сделать amend (дополнить/изменить предыдущий коммит), ОБЯЗАТЕЛЬНО сначала прочитай текущее сообщение коммита с помощью команды git log -1 --pretty=%B.
3. Определи язык: по умолчанию всегда используй Русский. Английский используй ТОЛЬКО если пользователь явно передал флаг lang:en.
4. Сформируй заголовок и тело коммита.
5. Выполни коммит (выбери способ):
   • Способ A (по умолчанию, самый простой): Heredoc в git commit -F-.
   • Способ B (если Heredoc ломает агента, например Gemini): временный файл .git_commit_msg.tmp + git commit -F.
   • Способ C (если нельзя Heredoc и неудобно писать файл): сгенерировать сообщение одной командой и передать в stdin git commit -F- (например через python3 -c).

Правила заголовка

• Формат: <type>(<scope>): <описание>
• Длина: не более 72 символов.
• Типы (type): feat, fix, refactor, docs, test, chore, ci, perf.
• Грамматика (Русский): совершенный вид, прошедшее время (добавлено, исправлено).
• Грамматика (Английский): повелительное наклонение (add, fix, update). Без точки в конце.
• Технические термины (SQL, DWH, PostgreSQL, Airflow) не переводи.

Шаблон тела коммита (Markdown-список)

• Зачем:
  • [Бизнес-причина или техническая необходимость]
• Что:
  • [Ключевое изменение 1]
  • [Ключевое изменение 2, если есть]
• Проверка:
  • [Как проверить: команда, тест или скрипт]

Требования к телу:

• Всегда используй именно список с маркерами -, как в шаблоне выше.
• Обязательные секции: Зачем, Что, Проверка.
• Внутри каждой секции минимум 1 подпункт.
• В секции Что обычно 1–3 подпункта с фактами по diff.

Правило переносов строк

В тексте коммита должны быть реальные переносы строк. Не пиши буквальные \n, \r, \t как часть текста сообщения.

Специфические правила для Amend

Если пользователь просит дополнить коммит (amend), твоя задача — обновить сообщение так, чтобы оно выглядело как единое целое.

1. Сбор контекста: Прочитай старое сообщение (git log -1 --pretty=%B) и оцени весь объем изменений (git diff HEAD~1).
2. Секция "Зачем": НИКОГДА не меняй эту секцию из старого коммита.
3. Секция "Что": Сгенерируй этот список ЗАНОВО для всего итогового кода.
4. Секция "Проверка": Оставь старую, либо обнови, если тесты изменились.

Правила выполнения команд

ЗАПРЕЩЕНО использовать флаг -m напрямую в консоли.

Способ A (Heredoc, рекомендован по умолчанию)

Используй ровно такой шаблон (важно <<'EOF', чтобы не было интерполяции):

git commit -F- <<'EOF' <type>(<scope>): <описание> `` - Зачем: - <текст> - Что: - <текст> - Проверка: - <текст> EOF

Для amend: git commit --amend -F- <<'EOF' ... EOF

Способ B (Gemini-safe: временный файл)

1. Запиши сообщение в .git_commit_msg.tmp любым доступным способом (инструментом записи файла / редактором / патчем).
2. Выполни git commit -F .git_commit_msg.tmp (или git commit --amend -F .git_commit_msg.tmp).
3. Удали файл: rm -f .git_commit_msg.tmp.

Способ C (одна команда, без Heredoc и без файла)

Если среда/агент плохо переносит многострочные команды, можно передать сообщение в stdin одной строкой.

Пример с Python (внутри команды допускаются \\n, т.к. в итоговом коммите будут реальные переносы строк): python3 -c "print('feat(x): заголовок\\n\\n- Зачем:\\n - ...\\n- Что:\\n - ...\\n- Проверка:\\n - ...')" | git commit -F-

Идеальные примеры

Пример 1 (Русский, новая фича, способ A): git commit -F- <<'EOF' feat(sql): добавлен скрипт валидации данных для DWH слоя

• Зачем:
  • необходима проверка целостности и уникальности перед загрузкой в хранилище.
• Что:
  • создан файл 04_validation.sql.
  • добавлены проверки на NULL.
• Проверка:
  • psql -f dwh-modeling/sql/04_validation.sql. EOF

Пример 2 (Русский, багфикс, способ A): git commit -F- <<'EOF' fix(airflow): увеличен таймаут подключения ClickHouse

• Зачем:
  • DAG падал с ошибкой таймаута при ночной пакетной загрузке.
• Что:
  • параметр conn_timeout изменен с 30 до 120 секунд.
• Проверка:
  • тестовый запуск таски в Airflow UI. EOF

Пример 3 (Английский, lang:en, способ A): git commit -F- <<'EOF' refactor(docker): optimize postgres-bookings image size

• Зачем:
  • reduce deployment time and registry storage costs.
• Что:
  • switched base image to alpine.
  • removed intermediate build artifacts.
• Проверка:
  • docker build and check image size. EOF

Пример 4 (Русский, логика amend, способ B): Исходный коммит содержал только изменение conn_timeout до 120 секунд. Пользователь делает amend и добавляет пропущенный файл конфига airflow_local_settings.py.

Сообщение (в .git_commit_msg.tmp): fix(airflow): увеличен таймаут подключения ClickHouse и обновлен конфиг

• Зачем:
  • DAG падал с ошибкой таймаута при ночной пакетной загрузке.
• Что:
  • параметр conn_timeout изменен с 30 до 120 секунд.
  • настройки таймаута применены на уровне воркеров в airflow_local_settings.py.
• Проверка:
  • тестовый запуск таски в Airflow UI.