Для AI-агентов · обновлено 2026-05-05

Как писать гайды в /info

Этот документ — обязательное чтение перед написанием любого гайда. Он объясняет КАК писать, чтобы вышло так же понятно как /info/vibecoders/.

1. Главное правило

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

Не как программисту. Не как DevOps-инженеру. Не как «опытному пользователю». Школьнику.

Это значит: - Каждый технический термин — сразу же объяснить в скобках или на простом примере. - Никакого «само собой разумеется». Если ты упомянул git pull — поясни что это «забрать новые файлы с сервера». - Каждая команда — с примером что вернётся. - Каждый шаг — с конкретной кнопкой/ссылкой, не «зайди в настройки», а «нажми правый верхний угол → Settings».

2. Структура любого гайда

Обязательные элементы (порядок):

  1. Frontmatter — метаданные (см. ниже)
  2. # Заголовок — что это и для кого
  3. «Кому это» / «Зачем это» — 1-2 абзаца. Если не понял за 30 сек — закрыл вкладку.
  4. Содержание — список из 5-10 разделов с якорями
  5. Разделы ## 1., ## 2., ... — нумерованные
  6. Подразделы ### 1.1, ### 1.2, ... — если раздел длинный
  7. «Что от тебя сейчас требуется» — последний раздел с чек-листом действий

Frontmatter (обязателен):

---
title: "Полное название гайда"
slug: short-url-slug
audience: dev | ops | admin | designer | client
status: draft | review | published
last-updated: 2026-05-05
---

audience — для кого: dev (разработчик), ops (оператор клуба), admin (админ платформы), designer (дизайнер), client (клиент клуба).

3. Тон голоса

✅ Так писать

❌ Так НЕ писать

Принципы

4. Технические термины — обязательный словарь

Если используешь любой из этих терминов первый раз в гайде — поясни:

Термин Объяснение в скобках
Git «версионная система — она хранит историю всех изменений в коде»
Repository / репо «папка с кодом проекта в GitLab»
Branch / ветка «параллельная копия кода, где можно править не ломая основное»
Commit «снимок изменений с подписью кто и зачем поправил»
Push «отправить свои изменения на сервер GitLab»
Pull «забрать с сервера то, что добавили коллеги»
Merge Request (MR) «заявка слить твою ветку с основной — её просматривают перед принятием»
Pipeline «автоматический набор проверок которые запускаются при каждом push»
Job «один шаг в pipeline — например build или test»
Artifact «файл который pipeline сохранил после работы — например собранный AAB или ZIP»
Docker «способ упаковать программу со всеми зависимостями в отдельный изолированный контейнер»
Container «один запущенный экземпляр Docker-образа»
Image «шаблон контейнера, замороженная программа на диске»
Migration / миграция «SQL-скрипт который меняет структуру БД (добавляет колонки, индексы)»
Manifest «JSON-файл-паспорт который описывает что внутри версии»
Channel / канал «уровень готовности версии: test (свежак), beta (обкатка), stable (прод)»
API «способ программе общаться с другой программой по HTTP»
Endpoint «конкретный URL у API, например /api/clubs/123»

Не паникуй если этих терминов нет в твоём гайде — главное последовательность: один раз пояснил → дальше используешь.

5. Шаблон раздела «Как сделать X»

## 5. Как обновить версию клуба вручную

**Зачем это нужно:** клиент жалуется что у него старая версия. Ты идёшь в panel и говоришь «обнови».

**Что понадобится:**
- Доступ в [panel.recore.su](https://panel.recore.su) (Maintainer уровень)
- Знать `slug` клуба (короткое имя в URL, например `rio` или `sever`)

**Шаги:**

1. **Открыть карточку клуба.**
   `panel.recore.su` → левое меню → Clubs → найти строчку → клик.

2. **Найти кнопку «Обновить весь клуб».**
   Прокрути вниз, она в блоке «Версии API» рядом с pills `stable / beta / test`.

3. **Подтвердить.**
   Появится диалог «Обновить весь клуб <Имя>?» → Yes.

4. **Проверить что отправилось.**
   Сверху появится зелёная плашка `Команда отправлена на N ПК`.

**Что произошло под капотом:** panel опубликовал NATS-сообщение
`recore.cmd.<clubId>.<pcId>.RecheckUpdates` для каждого ПК клуба.
Каждый desktop-client услышал → дёрнул `/api/clients/latest` → увидел новую версию → скачал и установился.

**Если не сработало:**
- Команда не дошла → проверь NATS жив (`status.recore.su` → монитор «panel API»)
- ПК скачал но не установился → ssh на ПК → `tail -f C:\ProgramData\RebornClient\update.log`
- Версии нет в канале клуба → в panel переключи канал клуба или подожди promote

6. Что НЕ писать в гайдах

Никогда: - Реальные пароли, API-токены, приватные ключи. Только placeholder'ы вида <твой-пароль> или ссылки «возьми у Никиты». - IP-адреса серверов вне общего контекста (panel-сервер уже публично известен — OK; внутренний staging IP — нет). - Имена/телефоны клиентов клубов. - Полные backup'ы / database dumps как примеры.

Всегда: - Ссылки на official docs где можно копнуть глубже («Подробности: <ссылка на GitLab docs>»). - Дата последнего обновления (в frontmatter last-updated). - Кто автор (frontmatter author опциональный).

7. Как опубликовать свой гайд

  1. Клонируй recore-platform или работай через GitLab Web IDE
  2. Создай файл info-content/<твой-slug>/index.md
  3. Заполни frontmatter + контент по этому гайду
  4. Положи картинки (если есть) в info-content/<твой-slug>/images/
  5. Открой MR feature/info-<slug> → main ветки recore-platform
  6. CI собирает HTML автоматически и публикует на https://reborndev.ru/info/<slug>/

После merge в main — твой гайд появится на сайте через 5 минут.

8. Чек-лист перед MR

9. Образец-эталон

Открой /info/vibecoders/ и раздел 9 «Теплов Влад» — это эталон стиля. Если твой гайд по уровню понятности заметно хуже — переписывай.

Конкретно что хорошо в нём: - Каждая команда отдельным step с заголовком + описанием - <callout> для важных предупреждений - <pre><code> для команд (не inline code в середине абзаца) - Тон «коллега объясняет коллеге» - Каждый этап завершается ссылкой «куда ехать дальше»

← Все справочники