| name | documentation |
| description | Детерминированная процедура создания и сопровождения документации сервисного репозитория как продукта (для ревью качества готовой доки — отдельный скилл doc-quality-review) для четырёх JTBD-потребителей (инженер-создатель, инженер-потребитель, потребитель concept-уровня, ИИ-агент). Рассчитан на слабую модель (уровня Qwen 37B): пошаговые проходы, таблицы-роутеры вместо суждений, жёсткие числовые лимиты, STOP-правила, fill-in-шаблоны и финальный чеклист. Применять, когда нужно собрать или отревьюить README или docs/architecture.md, решить в какой файл положить класс контента, или обновить доки по триггеру изменения. Не применять для лендинга платформы concept — это отдельный скилл platform-landing. |
Документация — детерминированная процедура
Документация репозитория — продукт для четырёх аудиторий, а не свалка прозы.
Этот скилл — процедура, а не справочник. Делай по шагам, не импровизируй.
Concept-уровень (лендинг платформы) проектируется отдельным скиллом
platform-landing. Здесь только указатель из
сервисного репо на concept (см. ниже) и роутинг «что НЕ кладём в concept».
0. Как пользоваться этим скиллом
- Делай ровно по шагам выбранной процедуры (A, B или C). Не пропускай проходы.
- Один проход = одна узкая задача. Закончил проход — проверь его условие, потом следующий.
- Числовые лимиты соблюдай буквально (слова считай).
- Сработало STOP-правило (раздел 2) → остановись и спроси оператора. Не угадывай.
- В конце прогони финальный чеклист (раздел 7). Все пункты должны быть «да».
Выбор процедуры:
| Задача | Процедура |
|---|
Собрать или пересобрать README.md | A (раздел 3) |
Собрать или пересобрать docs/architecture.md | B (раздел 4) |
| Обновить доки после изменения в коде/контракте | C (раздел 5) |
| Не знаю, в какой файл положить текст | Роутер (раздел 1) |
| Оценить качество УЖЕ написанной доки | скилл doc-quality-review |
1. Роутер: какой контент в какой файл
Возьми кусок контента. Найди строку. Положи ровно туда. Никаких других мест.
| Класс контента | Файл-назначение |
|---|
| Что сервис делает, зачем, границы (что умеет / не умеет) | README.md |
| Таблица API (метод, ресурс, действие) | README.md |
| Pipe-описание API (поток данных по шагам) | README.md |
| Стек (компонент → технология) | README.md |
| Команды запуска и проверки | README.md |
| Машинный контракт API (схемы, эндпоинты) | api-specification/ (OpenAPI/AsyncAPI) |
| Дерево модулей (кто кого вызывает) | docs/architecture.md |
| Блок-схема главного entry point | docs/architecture.md |
| Почему выбрана технология/паттерн/структура | docs/adr/ (+ строка в CLAUDE.md) |
| Правила контрибьюции | CONTRIBUTING.md |
| Очередь задач, статусы | backlog.md |
| Состояние модулей, решения, следующий шаг сессии | CLAUDE.md |
| Журнал шага (промпты, результат) | devlog/NN-topic.md |
| Описание ПЛАТФОРМЫ целиком (не одного сервиса) | НЕ сюда → репо ubik-life/concept |
Запрет дублирования: concept-уровень описания системы живёт в ubik-life/concept.
Сервис ссылается, не копирует. В первых строках README сервиса — строка:
> Часть платформы [Ubik](https://github.com/ubik-life/concept). Архитектура и концепция — там.
НЕ клади в concept README (если попало — верни по строке выше):
API-эндпоинты, pipe-описания, архитектуру сервиса, модель данных, команды запуска,
структуру проекта, детали реализации, длинный quickstart, troubleshooting.
2. STOP-правила
Остановись и спроси оператора, НЕ продолжай, если:
- Не понял, к какому сегменту (раздел 6) относится документ.
- В роутере (раздел 1) нет подходящей строки для куска контента.
- Нужно удалить или переписать существующий раздел, написанный человеком, не агентом.
- Контракт API (
api-specification/) отсутствует, а README требует таблицу API.
- Просят положить в README сервиса описание всей платформы (это в concept).
- Лимит требует выкинуть содержательный факт — спроси, куда его деть, не выкидывай молча.
3. Процедура A — README.md
README обслуживает ДВА сегмента сразу: создателя и потребителя (раздел 6).
Делай проходы по порядку. После каждого — проверь условие в скобках.
Pass A1 — Заголовок и одно предложение.
Напиши: название + что это, одно предложение ≤ 20 слов. Затем строка-указатель на concept (раздел 1).
(Проверка: ровно одно предложение, не абзац.)
Pass A2 — Границы.
Блок «Что умеет / что НЕ умеет» — два списка. Каждый пункт ≤ 12 слов.
(Проверка: есть оба списка, и «умеет», и «не умеет».)
Pass A3 — Стек.
Таблица компонент → технология. Только то, что реально используется.
(Проверка: таблица, не проза.)
Pass A4 — Таблица API.
Таблица метод | ресурс | действие. Источник истины — api-specification/.
Нет контракта → STOP (раздел 2).
(Проверка: каждая строка соответствует эндпоинту из спеки.)
Pass A5 — Pipe-описание каждого API.
Для каждого эндпоинта — поток данных по шагам через |. Шаблон:
POST /v1/registrations
| Принимаем handle от клиента
| Генерируем challenge (32 байта, TTL 5 мин)
| Сохраняем challenge в БД
| Возвращаем challenge + WebAuthn options → 201
Pipe = «как работает и где может сломаться». Таблица из A4 = «что есть». Нужны оба.
(Проверка: число pipe-блоков = числу строк таблицы API.)
Pass A6 — Запуск.
Минимальные шаги: команды (go run . / docker compose up) + ссылка на component-tests/.
(Проверка: команды можно скопировать и выполнить.)
Pass A7 — Ссылки вглубь (лестница).
Не копируй внутрь README — поставь ссылки в нужном порядке наращивания контекста:
README.md (что это, как запустить)
→ component-tests/ (как это работает снаружи)
→ docs/architecture.md (как устроена программа внутри)
→ docs/adr/ (почему сделано именно так)
→ CONTRIBUTING.md (как правильно менять)
(Проверка: архитектура и ADR — ссылками, не телом в README.)
4. Процедура B — docs/architecture.md
Обслуживает создателя, потребителя-на-доработке и ИИ-агента (раздел 6).
Ровно два обязательных раздела. Делай оба.
Pass B1 — Схема иерархий модулей.
Дерево от верхнего модуля к нижнему. Шаблон:
main
├── server (HTTP-сервер, роутинг)
│ ├── handlers/registration (обработка регистрации)
│ │ ├── challenge (генерация challenge)
│ │ └── attestation (проверка attestation)
│ └── middleware/auth (проверка JWT)
├── store (работа с БД)
│ ├── users
│ └── challenges
└── tokens (генерация и валидация JWT)
Правила (проверь каждый узел):
- Один узел = один модуль = одна ответственность.
- Стрелки только сверху вниз — нижний модуль НЕ знает о верхнем.
- I/O-модули (store, HTTP) отделены от бизнес-логики.
- I/O-объект автономен: головной модуль знает только его методы, не зависимости.
Имя по типу интеграции:
Store (БД), Client (HTTP), Publisher/Consumer (брокер).
Deps слайса держит объект, а не сырьё (*sql.DB, *http.Client).
Pass B2 — Блок-схема головного модуля.
Управляющий поток entry point. Шаблон:
main()
│
├─ Загрузить конфигурацию из ENV
│ └─ Нет обязательных переменных? → panic с явным сообщением
│
├─ Открыть БД, запустить миграции
│ └─ Ошибка? → panic
│
├─ Собрать роутер
│ ├─ /v1/registrations → registration handlers
│ └─ /v1/sessions → session handlers
│
└─ Запустить HTTP-сервер
└─ Graceful shutdown по SIGTERM
Правила (проверь):
- Только управляющий поток, без деталей реализации.
- Каждая ветка ошибки показана явно (что происходит при сбое).
5. Процедура C — обновить доки по триггеру
Произошло событие → найди строку → обнови ровно перечисленные файлы.
| Событие | Что обновить |
|---|
| Новый эндпоинт / изменение контракта | api-specification/, README.md (таблица API + pipe) |
| Изменение entry point или новый домен | docs/architecture.md (блок-схема, проц. B) |
| Значимый архитектурный выбор | docs/adr/ + строка в CLAUDE.md (Принятые решения) |
| Merge шага | CLAUDE.md (Статус модулей, Следующий шаг), backlog.md (Done) |
| Изменение структуры репо / способа запуска | README.md (Структура, Запуск) |
| Завершение шага разработки | devlog/NN-topic.md |
Форматы-шаблоны:
6. Справка: четыре сегмента (JTBD)
Используй, чтобы понять «для кого пишу» в проходах. Не редактируй документ, пока
не определил сегмент (иначе STOP, раздел 2).
| Сегмент | Job (зачем читает) | Главные документы |
|---|
| 1. Инженер-создатель (мейнтейнер) | Снизить стоимость онбординга до нуля | README.md (верх) + CONTRIBUTING.md + docs/adr/ + docs/architecture.md |
| 2. Инженер-потребитель (другая команда) | За 5 минут понять, решает ли его проблему; кратчайший путь к результату | README.md |
| 3. Потребитель concept-уровня | За 60 секунд решить «годится ли платформа», затем первый шаг | concept-репо (скилл platform-landing) |
| 4. ИИ-агент | За минимум токенов загрузить контекст и быть готовым к задаче | AGENTS.md, CLAUDE.md, docs/architecture.md |
Принципы письма для сегмента 4 (ИИ-агент): максимум фактов на токен, ноль воды;
один плоский файл (агент читает линейно, не кликает); структура таблицами и
заголовками, не прозой; запреты явные — «НЕ делай X», а не «старайся избегать X».
7. Финальный чеклист
Перед завершением проверь. Каждый пункт — «да». Любое «нет» → вернись и исправь.
