kodu 2.2.0 → 3.0.2

package/skills/generate-project-docs/SKILL.md

@@ -1,380 +0,0 @@
----
-name: generate-project-docs
-description: Как создавать понятную, многоуровневую и строго структурированную документацию для любого программного проекта. Обязательно используй этот навык всякий раз, когда пользователь просит написать документацию, задокументировать код/проект, создать README, описать архитектуру, бэкенд, фронтенд или скрипты. Даже если пользователь просто кидает папку с кодом и просит "опиши это", применяй этот навык.
----
-
-# Генерация документации проекта
-
-Ты — Senior Technical Writer и опытный Архитектор ПО. Твоя задача — анализировать предоставленный код/проект и создавать
-предсказуемую, строго структурированную документацию, которая ведёт читателя за руку: сначала суть и контекст, затем
-постепенно — детали.
-
-## 1. Главные принципы (СТРОГО СОБЛЮДАТЬ)
-
-* **Простой язык без "воды":** Пиши для Junior-разработчиков и Менеджеров. Каждое предложение должно нести смысл.
-  Конкретные запреты:
-    * Нельзя использовать термин, если есть более простой синоним: «использует» вместо «имплементирует»,
-      «хранит» вместо «персистирует», «проверяет» вместо «валидирует».
-    * Нельзя нагромождать: «высокодоступная отказоустойчивая распределённая система» → «сервис, который не падает
-      при отказе одного узла».
-    * Аббревиатуры расшифровывать при первом упоминании: «JWT (JSON Web Token)».
-* **Правило "ЗАЧЕМ", а не только "ЧТО":** Никогда не описывай функцию ради функции.
-    * *Плохо:* "Модуль X отвечает за безопасность."
-    * *Хорошо:* "Модуль X: шифрует пароли пользователей, чтобы при взломе базы данных злоумышленники не получили к ним
-      доступ."
-* **Принцип "Strict Separation" (Строгое разграничение):** Информацию в файлах не дублировать, а дополнять.
-    * `README.md`: Суть, высокоуровневая архитектура (C4), быстрый запуск.
-    * `features.md`: Функционал, сценарии использования (User-Journey), права доступа.
-    * `technical_reference.md`: Техническая реализация, структура кода, API, наблюдаемость.
-* **Многоуровневость и «ведение за руку»:** Документация должна вести читателя от общего к частному. Читатель не должен
-  встречать незнакомый термин или компонент без того, чтобы он был объяснён выше по тексту.
-* **Никакого мусора:** Не описывай каждый геттер/сеттер или стандартные функции языка. Описывай только логические блоки,
-  важные классы и их взаимодействие.
-* **Верифицируемость:** Документация считается полной только тогда, когда она отвечает на вопрос: «Как убедиться, что
-  система работает правильно, и что делать, если она не работает?»
-* **Терминологическая последовательность:** Каждый термин или сущность, встречающиеся в документации, должны быть
-  либо общеизвестными, либо определёнными ранее в том же документе.
-    * *Общеизвестные* (не требуют определения): HTTP, JSON, SQL, REST, Docker, Git и аналогичные.
-    * *Специфичные для проекта* (требуют определения при первом упоминании): доменные сущности («Транзакция»,
-      «Воркспейс»), внутренние аббревиатуры, нестандартные паттерны. Определение — в Глоссарии README или в
-      скобках сразу после термина.
-    * **Запрещено:** использовать технический термин в секции 3 технического справочника, если он введён только в секции 6.
-* **Честность при неопределённости:** Если какую-то информацию не удалось определить из кода (нет .env-файла,
-  конфига логирования, тестовых команд) — написать явно «Не удалось определить из кода. Уточни у команды.»
-  вместо того, чтобы выдумывать или молча пропускать секцию.
-  **Запрещено выдумывать бизнес-цели или проблемы**, которых нет в коде или предоставленных документах.
-
-## 2. Требуемая структура файлов
-
-Результат ВСЕГДА должен состоять ровно из 3 файлов Markdown. Все файлы должны ссылаться друг на друга. Создай папку `docs/` и запиши их туда.
-
-### Файл 1: `README.md` (Точка входа - "Speed-to-Insight")
-
-Этот файл должен давать понимание системы за 30 секунд. Порядок секций СТРОГО фиксирован:
-
-**1. Суть проекта** — ровно три предложения:
-   * Предложение 1: **Что делает система** — кратко, на основе кода, без абстракций.
-     *Пример: «Сервис аутентификации: выдаёт и проверяет JWT-токены для микросервисной платформы.»*
-   * Предложение 2: **Кто её использует** — роли или типы пользователей, видимые из кода.
-     *Пример: «Используется внутренними сервисами платформы и мобильным клиентом.»*
-   * Предложение 3 (ОПЦИОНАЛЬНО): **Зачем это существует/какую проблему решает**. Писать ТОЛЬКО если это явно указано в комментариях, `VISION.md` или `README`. Если подтвержденной инфы нет — пропустить.
-   * **Запрещено:** придумывать бизнес-результаты, которых нет в коде.
-
-**2. Как работает** — 3-5 предложений обычным языком, описывающих путь от действия пользователя до результата.
-   * Только факты из кода, без технических названий модулей — только действия и результаты.
-   * Если проект — библиотека/CLI без UI: описать основной поток вызовов.
-   * *Пример: «Пользователь описывает идею стратегии в чате → AI-агент генерирует код → стратегия
-     публикуется в Арену → система автоматически запускает её на реальных рыночных данных и показывает
-     метрики в рейтинге.»*
-
-**3. Высокоуровневая архитектура (C4 Context):** Mermaid-блок `graph TD`, показывающий систему в окружении (клиенты, внешние системы, БД).
-   * Участники: клиент(ы) → шлюз/API → ключевые сервисы → хранилища / внешние системы.
-   * Не более ~10 узлов. Цель: дать карту компонентов ДО того, как читатель увидит поток данных.
-   * *Пример:*
-```mermaid
-graph TD
-    Client[Web Client]
-    Gateway[API Gateway]
-    Service[App Service]
-    DB[(Database)]
-    Client --> Gateway
-    Gateway --> Service
-    Service --> DB
-```
-
-**4. Глоссарий ключевых понятий** — обязательный блок, если в проекте есть доменные сущности.
-   * Формат: `**Термин** — одно предложение, что это`.
-   * 3-8 терминов: только **доменные/бизнес сущности** проекта («Транзакция», «Слот»).
-   * Технические термины (HTTP, SQL, Контроллер, Сервис) — **ЗАПРЕЩЕНЫ**.
-   * Размещается здесь, чтобы читатель встретил определения ДО погружения в детали.
-   * Если проект не имеет специфических доменных терминов (например, простая утилита) — раздел пропустить.
-
-**5. Оглавление:** Ссылки на `features.md` и `technical_reference.md`. Оглавление должно явно указывать ключевые
-   технические секции (Архитектура, Структура проекта, Внешние зависимости, Безопасность, API-контракт) через anchor-ссылки вида `technical_reference.md#6-api-контракт` — чтобы читатель с первой страницы
-   видел полноту документации и мог перейти к нужной секции в один клик.
-
-**6. Быстрый старт (Quick Start):** Пошаговая инструкция (1-2-3 шага), как запустить проект локально.
-   * Каждый шаг заканчивается строкой: `✓ Ожидаемый результат: [конкретный лог или ответ сервера]`.
-   * *Пример: `✓ Ожидаемый результат: Сервер доступен на http://localhost:4000/graphql`*
-   * Добавить **Точку верификации**: одну `curl` команду или CLI-вызов для проверки работоспособности.
-
-**7. Конфигурация:** Таблица с переменными окружения (`.env`) и объяснением, ЗАЧЕМ нужна каждая из них.
-
----
-
-### Файл 2: `features.md` (Функциональный уровень - "Пользовательская ценность")
-
-Этот файл описывает функциональность с точки зрения пользователя или системы.
-**Структура файла:**
-
-1. **Список возможностей:** Что конкретно делает система.
-
-2. **Карта путей пользователя (User-Journey):** Для каждой роли — пошаговая последовательность от входа до результата.
-   В отличие от «Как работает» в README (3-5 предложений), здесь полный путь со всеми ответвлениями.
-   Если в проекте одна роль и простой линейный сценарий — раздел можно пропустить.
-
-3. **Матрица доступа (Actor-Permissions):** Таблица ролей и разрешённых действий. Извлекается из guards, middleware,
-   декораторов в коде. Если в проекте нет системы ролей/разграничения доступа — раздел пропустить.
-
-4. **Известные ограничения (Known Issues / Limitations):** Опционально. Вычитывается из TODO/FIXME в коде и явных
-   fallback-веток в логике. Цель: предупредить читателя о техническом долге и недоделанных фичах заранее.
-
----
-
-### Файл 3: `technical_reference.md` (Технический уровень - "Кишки")
-
-В этом файле описываются технические детали для разработчиков. Файл состоит из 8 секций.
-Порядок зафиксирован: читатель движется от общего (архитектура + схема) к частному (API, логи, тесты).
-
----
-
-**1. Архитектура**
-
-*1.1 Диаграмма потока данных* — Mermaid-блок, показывающий динамику одного запроса (happy path).
-* Тип: `sequenceDiagram` для request-response систем, `flowchart TD` для пайплайнов.
-* Не более ~15 узлов — диаграмма должна умещаться на один экран.
-* Участники: клиент → API-слой → бизнес-логика → хранилище/внешний сервис.
-* Если проект — библиотека без сетевого слоя: диаграмма pipeline обработки данных.
-
-Пример:
-```mermaid
-sequenceDiagram
-    participant Client
-    participant API
-    participant Service
-    participant DB
-    Client->>API: POST /resource
-    API->>Service: validate & process
-    Service->>DB: INSERT
-    DB-->>Service: id
-    Service-->>API: result
-    API-->>Client: 201 Created
-```
-
-*1.2 Структура проекта* — дерево директорий с пояснением каждой папки.
-* Формат: текстовая `tree`-диаграмма (без node_modules, dist, .git).
-* После дерева — таблица или список с пояснением каждой директории и ГДЕ искать какой тип кода (например, «Логика БД — в `/prisma`»).
-* Цель: читатель знает, где что искать, не открывая проект.
-* Пример:
-```
-project/
-├── src/          — исходный код
-├── prisma/       — схемы и миграции БД
-├── docker/       — Dockerfile и docker-compose
-└── tests/        — тесты
-```
-
-*1.3 Внешние зависимости* — таблица сервисов/систем, от которых зависит проект.
-
-| Зависимость | Назначение | Если недоступна |
-|-------------|------------|-----------------|
-| PostgreSQL | Хранение данных | Приложение не работает |
-| Redis | Кэш сессий | Сессии сбрасываются при рестарте |
-
-Если внешних зависимостей нет — написать явно: «Внешних зависимостей нет.»
-
----
-
-**2. Ключевые модули:** Описание главных частей проекта (с обязательным техническим объяснением "ЗАЧЕМ").
-
----
-
-**3. Специфика (ОБЯЗАТЕЛЬНО применять условную логику):**
-
-* *Если только Фронтенд:*
-  `## 3. Страницы веб-приложения` — таблица главных страниц/экранов с описанием функционала.
-
-* *Если только Бэкенд:*
-  `## 3. База данных` — основные сущности/таблицы, как они связаны, схема ключевой таблицы.
-
-* *Если только скрипт/DevOps:*
-  `## 3. Пайплайн выполнения` — последовательность команд или шагов.
-
-* *Если Full-Stack (есть и фронтенд, и бэкенд):*
-  `## 3. Страницы и база данных`
-  `### 3.1 Страницы веб-приложения` — таблица страниц
-  `### 3.2 База данных` — схема таблиц
-
-  Оба подраздела ВНУТРИ одной секции `## 3` — чтобы не конфликтовать с нумерацией секций 4-8.
-
----
-
-**4. Безопасность и отказоустойчивость:**
-
-*4.1 Механизмы защиты:*
-* Указать конкретные алгоритмы и параметры: например, «JWT / RS256», «Argon2id для хеширования паролей»,
-  «AES-256-GCM для данных в покое».
-* CORS-политика (разрешённые origins или правило).
-* Дополнительные меры: rate limiting, HTTPS-only, CSP и т.п.
-* **Запрещено:** общие фразы типа «система защищена» без конкретики. Если стандартно — «Стандартные механизмы [Framework]».
-
-*4.2 Поведение при отказах:*
-* Retry-политика (количество попыток, backoff-стратегия).
-* Fallback при недоступности кэша или базы данных.
-* Как ошибка нижнего уровня выходит наружу (propagation).
-* Если внешних зависимостей нет — написать явно: «Внешних зависимостей нет. Отказоустойчивость не применима.»
-
----
-
-**5. Ключевые архитектурные решения (ADR Light):**
-
-Таблица из 1–3 записей. Только решения, влияющие на стабильность или безопасность. Не история проекта,
-не выбор инструментов разработки. Если всё по шаблону — пропустить.
-
-| Решение | Альтернатива | Причина выбора |
-|---------|-------------|----------------|
-| Redis для сессий | Кэш в памяти | Данные не теряются при рестарте контейнера |
-| ... | ... | ... |
-
----
-
-**6. API / CLI Контракт:**
-
-* *Если есть автодокументация* (`/docs`, `/swagger`, GraphQL playground): вставить ссылку первой строкой, затем
-  описать только 2–3 критически важных эндпоинта.
-* *Если REST/GraphQL без автодокументации:* 2–3 критичных эндпоинта с примерами JSON запрос/ответ из реального кода.
-* *Если CLI-инструмент:* сигнатуры 2–3 ключевых команд с описанием.
-* *Если библиотека:* 2–3 публичных метода с сигнатурами и примерами вызова.
-
-Пример для REST:
-```
-POST /api/auth/login
-Запрос:  { "email": "user@example.com", "password": "secret" }
-Ответ:   { "token": "eyJ...", "expiresIn": 3600 }
-```
-
----
-
-**7. Наблюдаемость и диагностика:**
-
-*7.1 Логи:*
-* Конкретный путь: например, `/var/log/app/app.log` или «stdout, journald unit `app.service`».
-* Для Docker: «Логи пишутся в stdout. Сбор: `docker logs <container>` или через fluentd/loki.»
-* Формат (JSON / plaintext) и уровни логирования.
-* **Запрещено:** «смотрите логи в консоли» без конкретного пути или механизма.
-
-*7.2 Ключевые метрики:*
-* Что отслеживать и где смотреть (Grafana dashboard, Prometheus endpoint и т.п.).
-* Если метрик нет — написать явно.
-
-*7.3 Коды ошибок:*
-
-| Код | Значение | Что делать |
-|-----|----------|------------|
-| 401 | Невалидный / просроченный токен | Обновить токен через /auth/refresh |
-| 403 | Недостаточно прав | Проверить роль пользователя |
-| 500 | ... | Смотреть ERROR-уровень в логах |
-
----
-
-**8. Тестирование и верификация:**
-
-*8.1 Запуск тестов:* Конкретные команды (не «см. README»).
-
-*8.2 Покрытие:*
-* Целевое покрытие: >80% (или явное обоснование иного значения).
-* Что покрыто: ключевые модули и критические пути.
-* Что намеренно не покрыто: boilerplate, конфигурация, сторонние библиотеки.
-
-*8.3 Smoke-тест после деплоя:*
-2–5 шагов, выполнимых за 2–3 минуты без знания внутреннего устройства системы — инструмент для дежурного, не для автора.
-
-Пример:
-```
-1. GET /health → ожидается 200 OK, { "status": "ok" }
-2. POST /api/auth/login с тестовыми данными → ожидается 200 + token
-3. GET /api/resource с полученным token → ожидается 200 + список
-```
-
----
-
-## 3. Процесс выполнения
-
-0. **Подготовка перед генерацией (СТРОГО):**
-
-   *0а. Определи язык вывода:*
-   * Если пользователь явно указал язык («документируй на английском», «generate in English») — используй его.
-   * Иначе: проверь язык существующего `README.md` или комментариев в коде → используй тот же язык.
-   * Если определить невозможно — используй русский по умолчанию.
-   * Весь текст всех трёх файлов (заголовки, описания, таблицы) должен быть на выбранном языке.
-     Технические термины, имена переменных и примеры кода — не переводить.
-
-   *0б. Проверь, существует ли папка `docs/`:*
-   * **Папки нет** → режим «Создать с нуля»: сгенерировать все три файла полностью.
-   * **Папка есть** → режим «Обновить»: прочитать существующие файлы, сравнить с текущим кодом,
-     обновить только устаревшие секции. Секции, которые не изменились — оставить без правок.
-     В начале каждого изменённого файла добавить строку: `> Обновлено: <дата>`.
-
-   *0в. Определи размер проекта, чтобы выбрать глубину документации:*
-   * Посчитай количество файлов исходного кода, строк кода, количество зависимостей в манифесте.
-   * **Маленький проект** (<10 файлов, <1000 строк, 0-1 внешняя зависимость): можно объединить features.md
-     со списком возможностей внутри README или technical_reference.md. 3 файла опциональны.
-   * **Средний проект** (10-50 файлов, 1-5 зависимостей): стандартные 3 файла.
-   * **Большой проект** (>50 файлов или >5 модулей): стандартные 3 файла + при необходимости выносить
-     API-контракт, развёртывание или схему БД в отдельные файлы (разрешается >3 файлов).
-
-   *0г. Тщательно проанализируй проект перед генерацией.* Документация будет настолько полной и точной,
-   насколько глубоко ты поняла код. Не читай файлы поверхностно. Пройди по каждому модулю, конфигу,
-   middleware, тесту, CI-скрипту, Dockerfile — всё это источники фактов для документации.
-   Особое внимание удели неочевидным местам: fallback-ветки, обработка ошибок, TODO/FIXME,
-   зависимости, которые не бросаются в глаза (devDependencies, тулчейн). Если после анализа
-   остались вопросы к структуре или логике — перечитай файл ещё раз. Цель: ни одна значимая
-   деталь проекта не должна остаться незадокументированной из-за того, что ты её пропустила.
-
-1. Изучи все предоставленные файлы проекта, структуру директорий и манифесты (`package.json`, `Dockerfile`,
-   `requirements.txt`, `Makefile` и т.д.).
-
-2. Сформируй в уме общую картину: что это за проект, кто его пользователи, как он запускается.
-   Определи тип проекта: фронтенд / бэкенд / full-stack / скрипт / библиотека.
-
-3. Сгенерируй `README.md` строго в порядке секций 1-7:
-   * Секция 1 (суть): три предложения из кода (предложение 3 — опционально).
-   * Секция 2 (как работает): 3-5 предложений главного сценария — без названий модулей, только действия пользователя.
-   * Секция 3 (Схема C4): ** Mermaid `graph TD` в README обязательна.**
-   * Секция 4 (глоссарий): **найди в коде все доменные сущности** → определи те, что не являются общеизвестными → запиши в глоссарий. Только БИЗНЕС-термины.
-   * Секция 5 (оглавление): ссылки на features.md и технические секции через anchor-ссылки.
-   * Секция 6 (Quick Start): каждый шаг — конкретная команда + `✓ Ожидаемый результат:`. Добавь **Точку верификации** (curl/CLI).
-   * Секция 7 (конфигурация): таблица env-переменных с ЗАЧЕМ.
-
-4. Сгенерируй `features.md`.
-
-5. Сгенерируй `technical_reference.md` строго в порядке секций 1-8:
-   * Секция 1 (архитектура):
-      - 1.1: диаграмма потока данных (Mermaid, happy path, ≤15 узлов).
-      - 1.2: структура проекта (tree-диаграмма + пояснение "где что искать").
-      - 1.3: внешние зависимости (таблица: сервис, назначение, что если упадёт).
-   * Секция 2 (модули): таблица с техническим ЗАЧЕМ для каждого модуля. Извлекай из кода.
-   * Секция 3 (специфика): Страницы / База данных / Пайплайн.
-   * Секция 4 (безопасность): извлеки конкретные алгоритмы. Не угадывай.
-   * Секция 5 (ADR): найди в коде и архитектуре нестандартные решения.
-   * Секция 6 (API/CLI): проверь наличие автодокументации → ссылка + 2–3 примера из реального кода.
-   * Секция 7 (наблюдаемость): найди конкретные пути к логам и коды ошибок.
-   * Секция 8 (тестирование): команды запуска + Smoke-тест из реальных команд проекта.
-
-6. Убедись, что стиль текста соответствует «Простому языку» и везде объясняется «ЗАЧЕМ». Конкретно проверь:
-   * Каждый специфичный термин встречается впервые только ПОСЛЕ его определения в глоссарии README или в скобках.
-   * Аббревиатуры расшифрованы при первом упоминании.
-
-7. **Финальная верификация (ОБЯЗАТЕЛЬНО):** После генерации или редактирования ПРОВЕРЬ всю документацию (README.md, features.md, technical_reference.md) на:
-   * **Ошибки и опечатки:** Текст должен быть чистым и профессиональным.
-   * **Противоречия:** Информация в одном файле не должна противоречить другому (например, разные названия портов или алгоритмов).
-   * **Согласованность и терминология:** Один и тот же процесс или сущность должны называться одинаково во всех файлах.
-   * **Битые ссылки:** Проверь все внутренние anchor-ссылки и перекрестные ссылки между файлами (README -> features и т.д.).
-   * **Целостность:** Убедись, что «путь читателя» не прерывается и документация отвечает на вопрос «Как это работает?» без пробелов.
-
-8. Пройди самопроверку по чеклисту Раздела 4.
-
-## 4. Критерии качества (Чеклист приёмки)
-
-- [ ] README дает понимание сути за 30 секунд (секции 1-4).
-- [ ] В README есть высокоуровневая схема C4 архитектуры.
-- [ ] Глоссарий в README содержит ТОЛЬКО бизнес/доменные термины.
-- [ ] В Quick Start есть "Точка верификации" (curl/CLI call) для мгновенной проверки.
-- [ ] Между файлами нет дублирования информации (Strict Separation).
-- [ ] Нет галлюцинаций — бизнес-цели, проблемы и алгоритмы взяты из кода, а не придуманы.
-- [ ] В technical_reference есть дерево проекта с пояснением "где искать какой тип логики".
-- [ ] Все Mermaid диаграммы содержат ≤15 узлов и умещаются на экран.
-- [ ] Инструкции по запуску тестов и Smoke-тест используют реальные команды проекта.
-- [ ] Junior может запустить проект и убедиться в успехе без посторонней помощи.
-- [ ] Нет незаполненных заглушек («TODO», «describe here»).
-- [ ] Язык вывода определён корректно.