From 1f03251a9d5c508aff4ab859a3aff42dece9807d Mon Sep 17 00:00:00 2001 From: vitya Date: Wed, 26 Aug 2026 10:13:02 +0300 Subject: [PATCH] =?UTF-8?q?skills:=20admin-runbooks=20=E2=80=94=20=D0=BF?= =?UTF-8?q?=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=BD=D1=8B=D0=B9=20=D1=81=D0=BA?= =?UTF-8?q?=D0=B8=D0=BB=20=D0=B7=D0=BE=D0=BD=D1=8B=20=D0=B0=D0=B4=D0=BC?= =?UTF-8?q?=D0=B8=D0=BD=D0=B0=20(USE/EXECUTE/WRITE=20+=20=D0=B8=D0=BD?= =?UTF-8?q?=D0=B4=D0=B5=D0=BA=D1=81,=20=D0=BF=D0=BE=D0=B3=D0=BB=D0=BE?= =?UTF-8?q?=D1=89=D0=B0=D0=B5=D1=82=20writing-runbooks)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/admin-runbooks/SKILL.md | 140 +++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 .agents/skills/admin-runbooks/SKILL.md diff --git a/.agents/skills/admin-runbooks/SKILL.md b/.agents/skills/admin-runbooks/SKILL.md new file mode 100644 index 0000000..3ec73bd --- /dev/null +++ b/.agents/skills/admin-runbooks/SKILL.md @@ -0,0 +1,140 @@ +--- +name: admin-runbooks +author: ours +version: 1.0.0 +description: > + Единый контур ранбуков зоны админа (.admin): НАЙТИ нужный ранбук перед любой + прод-операцией → ИСПОЛНИТЬ по нему (чек-лист + verify + откат + письмо/таска) → + ВЕСТИ (обновлять после инцидентов/изменений) и СОЗДАВАТЬ новые. Поглощает + writing-runbooks (v1.0.0, superseded) — секция WRITE это его канон. + Trigger (user): деплой/редеплой/рестарт/ротация/миграция любого сайта или стека; + «по ранбуку», «как деплоить X», «напиши/обнови ранбук», «есть ли ранбук по X»; + любой прод-инцидент на сайте, который может потребовать операции. +--- + +# admin-runbooks + +Один контур: **индекс → USE → EXECUTE → WRITE/UPDATE**. Цель — устранить +«рыскание» (поиск рецепта по сессиям/чатам/grep), когда ранбук есть или должен быть. + +> ⚠️ **СЛУЖЕБНАЯ зона `.admin`.** Ранбуки — служебные документы `.admin`: +> применять/выполнять может только `.admin`; другие проекты читают по запросу, +> не выполняют; наружу не выносить. Прод-операция по ранбуку = таска на борде +> `.admin` + письмо от заказчика (исполнитель-не-админ не деплоит сам). + +## 0. ИНДЕКС РАНБУКОВ (всегда первый шаг) + +**Индекс:** `.admin/.wiki/concepts/runbooks-index.md` (единственный источник +«какой ранбук для чего»). **Прибит в AGENTS.md** — контур обязателен. + +Перед ЛЮБОЙ прод-операцией (деплой/редеплой/рестарт/ротация/миграция/инцидент): + +1. **Прочитай индекс** (`read .admin/.wiki/concepts/runbooks-index.md`) — найди + строку по проекту/операции → путь ранбука. +2. Ранбук может жить в трёх местах (индекс указывает, где): + - `.admin/.wiki/concepts/*-runbook*.md` — канон для VDS-проектов; + - `<репо-проекта>/.wiki/concepts/docker-deploy.md` и т.п. — репо-вики проекта + (pilorama98.ru: `apps/web/.wiki/concepts/docker-deploy.md`); + - mappa wiki (`wiki_search`) — если индекса ещё нет, искать там. +3. **Нет ранбука → НЕ деплоить молча.** Создать (см. WRITE) до/вместе с операцией: + отдельной таской или в теле операционной таски (пункт «нужен ранбук»). + Это не бюрократия: отсутствие ранбука = повторное рыскание в следующий раз. + +## 1. USE — найти и прочитать ранбук + +- Сначала индекс → ранбук. Не начинать grep по сессиям/чатам — это анти-паттерн + (источник этой секции: инцидент 2026-08-26 pilonuxt — рыскал, ранбука не было). +- Прочитать ранбук **целиком** перед операцией (секреты — плейсхолдеры, реальные + значения — из pass по указателям; ранбук сам секретов не несёт). +- Сверить актуальность: теги/версии на проде могут обогнать ранбук (пример: + stostayer-web ранбук показывал 0.3.23, прод был 0.3.26 → тег брать с проде, + а ранбук потом обновить — WRITE). Если расхождение → пометить на апдейт. + +## 2. EXECUTE — деплой/операция по ранбуку + +Выполнять шаги ранбука как чек-лист, **не пропуская**: + +1. **Предусловия** (auth: JWT/токены из pass; docker login; pull-ДО-рестарта; + .dockerignore/.yarnrc временные модификации — пометить на возврат). +2. **Шаги операции** — дословно по ранбуку, порядок важен (gotchas в ранбуке). +3. **Verify** по секции ранбука (страницы/эндпоинты/логи/uptime) — зелёный перед + закрытием. При красном — rollback-путь из ранбука, не импровизация. +4. **Фиксация результата:** + - sync source-of-truth compose (если менялся тег) → commit + push; + - письмо-отчёт заказчику (inbox_send, from `.admin`, с verify-таблицей); + - закрыть операционную таску (reason = что сделано + verify); + - при необходимости — обновить ранбук (WRITE): новый тег, новые gotchas. + +Ограничения: одна попытка там, где ранбук велит одну (egress-баны, retry-штормы); +не отклоняться от ранбука без причины — отклонение фиксировать в письме. + +## 3. WRITE / UPDATE — создание и ведение ранбуков + +Канон (наследие writing-runbooks v1.0.0, поглощено): + +### Жёсткие правила + +1. **Ранбук — служебный документ `.admin`.** Применять может только `.admin`. +2. **Из проекта не выносить.** Не копировать в другие вики, не публиковать. +3. **Деплой = таска + письмо админу.** Любая прод-операция — по задаче на борде + `.admin` и письму. Исполнитель-не-админ ставит задачу, не деплоит сам. +4. **Служебный блок — в первых абзацах** (машиночитаемый маркер служебности): + +```markdown +> **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.** +> Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять. +> Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать. +> Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют. +``` + +Дословно, без перефразирования. + +### Гигиена секретов (решение 5, write-тайм сканер mappa) + +**В ранбуках никогда не бывает реальных секретов.** Только плейсхолдеры + +указатели на pass: `<из pass />`. Сканер блокирует запись (422) +на password/token/api_key/secret+значение ≥6 симв., AKIA…, JWT, ssh-ключи. +Обход плейсхолдером: значение <6 симв. (`'<...>'`), либо ключ-слово не латиницей, +либо разрыв `: ` коротким словом (`PASSWORD: см. pass (…)`). После записи — +проверить `admin_secret_scan` (0 хитов). + +### Структура ранбука + +1. Frontmatter: `title`, `type: concept`, `tags: [.., runbook]`, `related`, `updated`. +2. H1 + служебный блок (обязательно, дословно). +3. Scope (VDS, стек Portainer Id, endpointId, source-of-truth compose). +4. Артефакты (код/образ/стек/БД/эндпоинт; тег = как на проде). +5. Шаги операции (копируемые команды) + таблица «рестарт vs пересборка» если уместно. +6. Verify/smoke после операции. +7. Rollback-путь всегда. +8. Gotchas из практики (нумерованные, с датой). + +### Ведение (UPDATE) + +Обновлять ранбук когда: +- прод ушёл вперёд (новый тег/версия) — поправить инвентарь/таблицы; +- появилась новая gotcha (инцидент с неочевидной причиной); +- изменился канал деплоя (адреса/стек/порядок). +После правки: bump `updated:`, синхронизировать с индексом (что покрывает), +проверить secret_scan. Коммит отдельный от операционного («docs(runbook): …»). + +## Порядок записи (мутации вики) + +- Файл ранбука живёт в `.admin/.wiki/concepts/` (репо .admin, git). Писать файл → + commit → push (проектная дисциплина: push свободно). mappa-импорт подхватит при + следующем импорте (индекс/ранбуки доступны и через wiki_search после импорта). +- Секрет-сканер: `mcp__mappa__admin_secret_scan` после записи — 0 hits. + +## Место жительства этого скила + +Скил лежит в `.admin/.agents/skills/admin-runbooks/SKILL.md` — проектные скилы +`.admin` (pi: `.agents/skills/` в cwd). НЕ дублировать в `~/.agents/skills/` +(глобальная установка, перезаписывается update-skills) и НЕ в общий skills-репо. +Обновление — правкой файла в проекте + commit/push (.admin). + +## Связи + +- `concepts/runbooks-index.md` — индекс ранбуков (обязательный первый шаг). +- `writing-skills` — RED-GREEN-REFACTOR для скилов (если править сам скил). +- `using-vds-ops` — диагностика контейнеров (read-only), не деплой. +- `project-discipline` — семвер/пуш-правила при правке версионируемых артефактов.