docs: update AGENTS and README to include guidelines for Conventional Commits

- Added a section on Conventional Commits in AGENTS.md, detailing the process for generating commit messages. - Enhanced README.md with references to the Conventional Commits rules and the necessary scripts for generating commit messages. - Clarified the format for commit messages, specifying the language requirements for headers and bodies.
2026-05-20 00:48:21 +07:00
parent c263fd5c7e
commit 4c23232c4e
5 changed files with 430 additions and 0 deletions
@@ -0,0 +1,124 @@
+---
+name: commit-message
+description: >-
+  ОБЯЗАТЕЛЬНО при commit, коммит, закоммить, commit message, conventional commit,
+  staged, semantic-release, «сгенерируй коммит», git commit: ПЕРВЫМ делом Shell —
+  scripts/commit/staged-context.ps1; затем Conventional Commit (заголовок EN, тело RU).
+---
+
+# Commit message (EvoBGP)
+
+## Когда применять (сразу читать этот скилл)
+
+Триггеры в промпте пользователя или в плане/AGENTS.md:
+
+- `commit`, `коммит`, `закоммить`, `commit message`, `conventional commit`
+- `git commit`, `staged`, `сообщение коммита`, `сгенерируй коммит`
+- агент собирается выполнить `git commit` или предложить текст коммита
+
+## Шаг 0 — ОБЯЗАТЕЛЬНО (до любого текста коммита)
+
+**Первый вызов инструментов** в этой задаче — Shell из корня репозитория:
+
+```powershell
+powershell -NoProfile -File scripts/commit/staged-context.ps1
+```
+
+| Правило | Деталь |
+|---------|--------|
+| **MUST** | Запустить скрипт до генерации заголовка/тела коммита |
+| **MUST NOT** | Строить сообщение только по `git diff --cached` / `git status` без скрипта |
+| **MUST NOT** | Пропускать скрипт, даже если diff «и так понятен» |
+| Exit `1` | Index пуст — сообщить пользователю, **не коммитить** |
+| Exit `0` | Разобрать JSON stdout: `staged_count`, `groups[]` (`scope`, `files`, `stat`, `diff_excerpt`) |
+
+Дополнительно: [.cursor/rules/conventional-commits.mdc](../../rules/conventional-commits.mdc).
+
+## Слияние групп (одна фича)
+
+Скрипт группирует **только по путям**. Перед split проверьте логическую связность:
+
+**Объединить в один коммит**, если это одна задача:
+
+- `docs/openapi.yaml` + `internal/httpapi/` (+ опционально `web/`) — один endpoint/контракт;
+- `migrations/` + `internal/store/` / `repository/` — одна схема;
+- правки теста рядом с кодом той же фичи.
+
+При объединении: один scope (доминирующий пакет, часто `httpapi` или `openapi`), один type, одно тело RU.
+
+**Auto-split** — если группы **не связаны** (например `web/` + `internal/birdfmt/` без общего смысла): **отдельный коммит на группу**, без вопроса пользователю.
+
+## Порядок коммитов при split
+
+1. `openapi`
+2. `httpapi`, `store`, `jobs`
+3. `pipeline`, `birdfmt`, `birddeploy`, `bundle`
+4. `web`
+5. `ci`, `deploy`, `db`
+6. `docs`
+7. `chore`, `cmd`
+
+## Алгоритм auto-split (уровень файлов)
+
+1. `git status` и `git diff --cached --stat` — зафиксировать полный список staged-файлов.
+2. `git reset HEAD` — снять всё из index (working tree не трогать).
+3. Для каждой (объединённой) группы по порядку выше:
+   - `git add -- <paths…>`
+   - Сгенерировать сообщение по правилу conventional-commits.
+   - Закоммитить (см. ниже).
+4. После всех коммитов — `git status` для проверки.
+
+**Ограничение:** частичный stage одного файла с разной семантикой — предупредить; split по hunk'ам не делать; предложить разнести правки по файлам.
+
+## Создание коммита
+
+Только если пользователь **явно** просил закоммитить. Иначе — только вывести готовые сообщения.
+
+```powershell
+git commit -m "$( @'
+<type>(<scope>): <summary in English>
+
+<Тело на русском.>
+'@ )"
+```
+
+В PowerShell для многострочного тела используйте here-string как выше или `-m` для заголовка и `-m` для тела.
+
+Перед коммитом: `git status`, `git diff --cached` для группы — убедиться, что stage соответствует сообщению.
+
+## Генерация текста
+
+По `groups[].diff_excerpt`, `stat`, `files`:
+
+- **type** — по смыслу diff (`feat` / `fix` / …), не по умолчанию `chore`.
+- **scope** — из JSON группы или доминирующий при merge.
+- **summary** — конкретный, английский, императив.
+- **body** — русский: что, зачем, edge cases, breaking impact.
+
+## Вывод пользователю
+
+Для **каждого** коммита:
+
+### 1. Готовое сообщение
+
+```
+<type>(<scope>): <summary>
+
+<тело>
+```
+
+### 2. Пояснение (RU)
+
+- Почему выбран type/scope.
+- Риски и impact.
+- Split: сколько коммитов и почему.
+
+## Не смешивать
+
+Один commit message — одна primary intent. Не объединять несвязанный `fix` и `feat` в один заголовок.
+
+## Ссылки
+
+- Правило: `.cursor/rules/conventional-commits.mdc`
+- Скрипт: `scripts/commit/staged-context.ps1`
+- Просмотр групп: `powershell -File scripts/commit/staged-context.ps1 | ConvertFrom-Json`