diff --git a/skills/docs-map/SKILL.md b/skills/docs-map/SKILL.md new file mode 100644 index 0000000..ac6b81b --- /dev/null +++ b/skills/docs-map/SKILL.md @@ -0,0 +1,36 @@ +--- +name: docs-map +description: Используй, когда нужно найти или написать внутреннюю документацию — где искать по теме, какие есть ключевые пространства/разделы, куда класть новую страницу или RFC. Применяй при вопросах «где документация», «куда записать», «есть ли дока по», а также в команде /rfc. +--- + +# Работа с документацией + +Скилл помогает искать существующую документацию и правильно размещать новую. + +## Адрес документации + +Адрес портала документации — в поле `docsUrl` корпоративного конфига. Его текущее значение +инжектится в **корпоративный контекст сессии** расширением `company-context` — бери адрес +оттуда, здесь он намеренно не дублируется (единый источник правды — `config/company.json`). + +## Ключевые пространства/разделы + + + +- **Архитектура и RFC:** `` +- **Гайды по сервисам:** `` +- **Онбординг:** `` +- **Runbooks / эксплуатация:** `` + +## Как искать + +1. Начни с портала документации (адрес — из корпоративного контекста сессии). +2. `` + +## Куда писать новое + + + +- Новую страницу по фиче: `` +- RFC/ADR: `` +- Правило: не дублируй информацию — сначала поищи существующую страницу и обнови её. diff --git a/skills/go-standards/SKILL.md b/skills/go-standards/SKILL.md new file mode 100644 index 0000000..24261f5 --- /dev/null +++ b/skills/go-standards/SKILL.md @@ -0,0 +1,59 @@ +--- +name: go-standards +description: Используй при написании, ревью и проверке кода на Go в наших сервисах — структура сервиса, запуск линтеров и тестов, формат коммитов и merge request. Применяй всегда, когда пишешь или правишь Go-код, готовишь MR, а также в командах /bugfix, /feature и /review. +--- + +# Стандарты Go + +Наш основной стек — **Go**. Скилл описывает, как писать, проверять и оформлять код. +Реалистичные общепринятые дефолты приведены ниже; то, что специфично для компании, +помечено `TODO` — уточняй, не выдумывай. + +## Структура сервиса + +Ориентир (уточняется под компанию): + +``` +cmd//main.go # точка входа +internal/ # приватный код сервиса + / # доменные пакеты +pkg/ # переиспользуемый публичный код (если есть) +api/ # спецификации API (proto/openapi) +``` + + + +## Линтеры + +- Форматирование: `gofmt -l -w .` и `goimports -w .` — код должен быть отформатирован. +- Статический анализ: `go vet ./...`. +- Основной линтер: **golangci-lint** — `golangci-lint run ./...`. + Набор линтеров задаётся в `.golangci.yml` в корне репозитория. + + +## Тесты + +- Прогон всех тестов: `go test ./...`. +- С гонками и покрытием: `go test -race -cover ./...`. +- Требования к покрытию и обязательные виды тестов: ``. +- Именование: `TestXxx`, табличные тесты приветствуются. + +## Коммиты и MR + +- **Формат коммитов:** ``. +- **Ветки:** от основной, именование ``. +- **MR обязателен** (см. корпоративные правила из контекста сессии). Прямой push в защищённые + ветки запрещён — расширение `permission-gate` дополнительно переспросит. +- **Описание MR:** что и зачем изменено, как проверено (линтеры + тесты), ссылка на тикет + (см. скилл `jira-workflow`). +- Перед MR прогони линтеры и тесты — всё должно быть зелёным. + +## Чек-лист перед MR + +- [ ] `gofmt`/`goimports` без изменений +- [ ] `go vet ./...` чисто +- [ ] `golangci-lint run ./...` чисто +- [ ] `go test ./...` (или `-race`) зелёные +- [ ] есть тесты на новую логику / фикс +- [ ] нет секретов и закоммиченных `.env` +- [ ] описание MR со ссылкой на тикет diff --git a/skills/jira-workflow/SKILL.md b/skills/jira-workflow/SKILL.md new file mode 100644 index 0000000..c677923 --- /dev/null +++ b/skills/jira-workflow/SKILL.md @@ -0,0 +1,57 @@ +--- +name: jira-workflow +description: Используй, когда нужно работать с корпоративным трекером задач (Jira) — прочитать тикет по ключу, добавить комментарий, приложить ссылку на MR, разобраться в статусах и переходах. Применяй при упоминании ключей задач, «тикет», «задача в трекере», «переведи в статус», а также в командах /bugfix и /feature. +--- + +# Работа с трекером задач (Jira) + +Скилл описывает, как читать и обновлять задачи в нашем трекере через REST API. + +## Откуда берутся адрес и токен + +**Никогда не хардкодь и не спрашивай их отдельно — они уже есть в окружении.** + +- **Базовый адрес трекера** — из переменной окружения `TRACKER_URL`. Если она не задана, + возьми адрес трекера из корпоративного контекста сессии (его инжектит расширение + `company-context`). +- **Токен доступа** — из переменной окружения `JIRA_TOKEN` (personal access token). +- Токен в команды и логи не подставляй в открытом виде — скрипты читают его из окружения сами. + +Быстрая проверка окружения: + +```bash +: "${TRACKER_URL:?установи TRACKER_URL или возьми адрес из корпоративного контекста}" +: "${JIRA_TOKEN:?установи JIRA_TOKEN (personal access token трекера)}" +``` + +## Готовые скрипты + +Все скрипты лежат в `scripts/` и читают `TRACKER_URL` и `JIRA_TOKEN` из окружения: + +- `./scripts/get-issue.sh ` — получить тикет (поля summary, status, description). +- `./scripts/add-comment.sh "<текст>"` — добавить комментарий. +- `./scripts/link-mr.sh "" ["<заголовок>"]` — приложить ссылку на MR + (добавляется комментарием со ссылкой; при доступном remote link API — см. TODO в скрипте). + +Пример: + +```bash +./scripts/get-issue.sh PROJ-123 +./scripts/add-comment.sh PROJ-123 "Начал работу, воспроизвёл баг" +./scripts/link-mr.sh PROJ-123 "https:///ai/foo/-/merge_requests/42" "Fix PROJ-123" +``` + +## Соглашения + + + +- **Формат ключей задач:** `` +- **Статусы и переходы:** `` +- **Кто и когда меняет статус:** `` +- **Что писать в комментарии при старте/готовности:** `` + +## Полезное + +- ID переходов статуса можно получить через `GET /rest/api/2/issue//transitions`, + выполнить переход — `POST` туда же с `{"transition":{"id":""}}`. +- Если API возвращает 401/403 — проверь `JIRA_TOKEN` и права. Не логируй сам токен. diff --git a/skills/jira-workflow/scripts/add-comment.sh b/skills/jira-workflow/scripts/add-comment.sh new file mode 100755 index 0000000..a735053 --- /dev/null +++ b/skills/jira-workflow/scripts/add-comment.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +# add-comment.sh "" +# Adds a comment to a tracker issue. +# Reads TRACKER_URL and JIRA_TOKEN from the environment. No secrets are hardcoded. +set -euo pipefail + +KEY="${1:?usage: add-comment.sh \"\"}" +TEXT="${2:?usage: add-comment.sh \"\"}" +: "${TRACKER_URL:?set TRACKER_URL (or take the tracker address from the session corporate context)}" +: "${JIRA_TOKEN:?set JIRA_TOKEN (tracker personal access token)}" + +BASE="${TRACKER_URL%/}" + +# Build JSON body safely (jq escapes the text); fall back to a naive body if jq is absent. +if command -v jq >/dev/null 2>&1; then + BODY="$(jq -n --arg b "$TEXT" '{body: $b}')" +else + BODY="{\"body\": \"${TEXT//\"/\\\"}\"}" +fi + +curl -fsS -X POST \ + -H "Authorization: Bearer ${JIRA_TOKEN}" \ + -H "Content-Type: application/json" \ + -d "$BODY" \ + "${BASE}/rest/api/2/issue/${KEY}/comment" >/dev/null + +echo "Comment added to ${KEY}" diff --git a/skills/jira-workflow/scripts/get-issue.sh b/skills/jira-workflow/scripts/get-issue.sh new file mode 100755 index 0000000..0b82d3d --- /dev/null +++ b/skills/jira-workflow/scripts/get-issue.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# get-issue.sh +# Prints summary, status and description of a tracker issue. +# Reads TRACKER_URL and JIRA_TOKEN from the environment. No secrets are hardcoded. +set -euo pipefail + +KEY="${1:?usage: get-issue.sh }" +: "${TRACKER_URL:?set TRACKER_URL (or take the tracker address from the session corporate context)}" +: "${JIRA_TOKEN:?set JIRA_TOKEN (tracker personal access token)}" + +BASE="${TRACKER_URL%/}" + +curl -fsS \ + -H "Authorization: Bearer ${JIRA_TOKEN}" \ + -H "Accept: application/json" \ + "${BASE}/rest/api/2/issue/${KEY}?fields=summary,status,description" \ + | { jq -r '"\(.key)\t\(.fields.status.name)\n\(.fields.summary)\n\n\(.fields.description // "")"' 2>/dev/null || cat; } diff --git a/skills/jira-workflow/scripts/link-mr.sh b/skills/jira-workflow/scripts/link-mr.sh new file mode 100755 index 0000000..d7b9bb4 --- /dev/null +++ b/skills/jira-workflow/scripts/link-mr.sh @@ -0,0 +1,22 @@ +#!/usr/bin/env bash +# link-mr.sh "" [""] +# Attaches a merge request link to a tracker issue. +# Default implementation posts a comment with the link (works on any Jira). +# Reads TRACKER_URL and JIRA_TOKEN from the environment. No secrets are hardcoded. +set -euo pipefail + +KEY="${1:?usage: link-mr.sh <ISSUE_KEY> \"<mr-url>\" [\"<title>\"]}" +URL="${2:?usage: link-mr.sh <ISSUE_KEY> \"<mr-url>\" [\"<title>\"]}" +TITLE="${3:-Merge request}" +: "${TRACKER_URL:?set TRACKER_URL (or take the tracker address from the session corporate context)}" +: "${JIRA_TOKEN:?set JIRA_TOKEN (tracker personal access token)}" + +BASE="${TRACKER_URL%/}" + +# Default: comment with the MR link. +COMMENT="${TITLE}: ${URL}" +exec "$(dirname "$0")/add-comment.sh" "$KEY" "$COMMENT" + +# TODO: если в компании используется remote issue link API, заменить на: +# POST ${BASE}/rest/api/2/issue/${KEY}/remotelink +# с телом {"object":{"url":"<URL>","title":"<TITLE>"}} diff --git a/skills/repo-map/SKILL.md b/skills/repo-map/SKILL.md new file mode 100644 index 0000000..2e35991 --- /dev/null +++ b/skills/repo-map/SKILL.md @@ -0,0 +1,32 @@ +--- +name: repo-map +description: Используй, когда нужно сориентироваться в наших репозиториях — найти нужный сервис, понять соглашения по именованию репозиториев, где лежат CI-конфиги, куда добавлять новый сервис. Применяй при вопросах «где код», «в каком репозитории», «как найти сервис», а также в начале работы по /feature и /bugfix. +--- + +# Карта репозиториев + +Скилл помогает понять, где что лежит, и быстро найти нужный сервис. + +## Актуальная карта + +Конкретная карта репозиториев — в поле `repoMap` корпоративного конфига. Её текущее значение +инжектится в **корпоративный контекст сессии** расширением `company-context` — смотри туда, +здесь оно намеренно не дублируется (единый источник правды — `config/company.json`). + +Адрес git-хоста также берётся из корпоративного контекста сессии. + +## Соглашения + +<!-- TODO: заполнить реальными значениями компании --> + +- **Именование репозиториев:** `<!-- TODO: напр. <домен>-<сервис>, service-*, lib-* -->` +- **Группы/неймспейсы в git:** `<!-- TODO: какие группы за что отвечают -->` +- **Где CI-конфиги:** `<!-- TODO: напр. .gitlab-ci.yml в корне, шаблоны в группе ci/ -->` +- **Общие библиотеки:** `<!-- TODO: где переиспользуемый код -->` +- **Как заводится новый сервис:** `<!-- TODO: шаблон/cookiecutter, чек-лист -->` + +## Как искать сервис + +1. Загляни в `repoMap` из корпоративного контекста сессии — там верхнеуровневая карта. +2. Если нужен поиск по коду — используй поиск по git-хосту (адрес из корп. контекста). +3. Определи владельца по неймспейсу/группе репозитория.