Генератор руководств по адаптации для вики-проектов

Сгенерируйте четыре документа по адаптации, адаптированных под конкретную аудиторию, в папке onboarding/, каждый из которых даст различным заинтересованным сторонам именно ту информацию, в которой они нуждаются.

Определение репозитория-источника (НЕОБХОДИМО СДЕЛАТЬ В ПЕРВУЮ ОЧЕРЕДЬ)

Перед созданием каких-либо руководств ВЫ ДОЛЖНЫ определить контекст исходного репозитория:

1. Проверьте наличие удаленного репозитория git: выполните команду git remote get-url origin, чтобы определить, существует ли удаленный репозиторий
2. Спросите пользователя: «Это исключительно локальный репозиторий или у вас есть URL исходного репозитория (например, GitHub, Azure DevOps)?»
   • Указан URL удалённого репозитория → сохраните его как REPO_URL, используйте ссылки на файлы: [file:line](REPO_URL/blob/BRANCH/file#Lline)
   • Только локальный репозиторий → используйте локальные ссылки: (file_path:line_number)
3. Определите ветку по умолчанию: выполните команду git rev-parse --abbrev-ref HEAD
4. НЕ продолжайте, пока не будет определён контекст репозитория-источника

Когда активировать

• Пользователь запрашивает документы по адаптации или руководства по началу работы
• Пользователь запускает команду `/deep-wiki:onboard `
• Пользователь хочет помочь новым членам команды разобраться в кодовой базе

Структура вывода

Создать папку onboarding/ со следующими файлами:

onboarding/
├── index.md                    # Центр адаптации — ссылки на все 4 руководства с описанием целевой аудитории
├── contributor-guide.md        # Для новых участников (предполагается наличие опыта работы с Python или JS)
├── staff-engineer-guide.md     # Для штатных/ведущих инженеров
├── executive-guide.md          # Для руководителей инженерных подразделений уровня вице-президента/директора
└── product-manager-guide.md    # Для менеджеров по продукту и заинтересованных лиц, не связанных с инженерией

index.md — Центр адаптации

Страница приветствия, содержащая:

• Краткое описание проекта в одном абзаце
• Таблица выбора руководств:

Определение языка

Просканируйте репозиторий на наличие файлов сборки, чтобы определить основной язык для примеров кода:

• package.json / tsconfig.json → TypeScript/JavaScript
• *.csproj / *.sln → C# / .NET
• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• go.mod → Go
• pom.xml / build.gradle → Java

Руководство 1: Руководство для участников

Файл: onboarding/contributor-guide.md Аудитория: инженеры, присоединяющиеся к проекту. Предполагается владение Python или JavaScript и общий опыт в области разработки программного обеспечения. Объем: 1000–2500 строк. Постепенное построение — каждый раздел основывается на предыдущем.

Обязательные разделы

Часть I: Основы (пропустить, если в репозитории используется Python или JS)

1. {Основной язык} для инженеров Python/JS — таблицы сравнения синтаксиса, асинхронная модель, коллекции, система типов, управление пакетами. Конкретный код в параллельном сравнении, а НЕ абстрактные описания.
2. Основы {основного фреймворка} — сравнение с эквивалентными фреймворками на Python/JS (например, FastAPI, Express). Конвейер запросов, маршрутизация, DI, конфигурация.

Часть II: Данная кодовая база 3. Задача проекта — краткое описание в 2–3 предложениях 4. Структура проекта — аннотированное дерево каталогов (что где находится и почему). Включите обзор архитектуры в виде графа TB. 5. Основные концепции — терминология, специфичная для данной области, с объяснениями на примерах кода. Используйте диаграмму er для модели данных. 6. Жизненный цикл запроса — диаграмма последовательности (с автонумерацией), прослеживающая типичный запрос от начала до конца. 7. Ключевые шаблоны — шаблоны типа «Если вы хотите добавить X, следуйте этому шаблону» с реальным кодом

Часть III: Начало продуктивной работы 8. Необходимые условия и настройка — Таблица: инструмент, версия, команда установки. Пошаговая инструкция с ожидаемым результатом на каждом шаге. 9. Ваша первая задача — Пошаговое руководство по добавлению простой функции от начала до конца 10. Рабочий процесс разработки — Стратегия создания веток, соглашения о фиксации изменений, процесс PR. Используйте блок-схему. 11. Запуск тестов — Все тесты, отдельный файл, отдельный тест, команды для проверки покрытия 12. Руководство по отладке — Таблица типичных проблем: симптом, причина, исправление 13. Распространённые ошибки — Ошибки, которые допускает каждый новый участник проекта, и как их избежать

Приложения

• Глоссарий (более 40 терминов)
• Справочник по ключевым файлам — таблица: путь, назначение, важность, исходный код
• Карточка быстрого справочника — Справка по наиболее часто используемым командам и шаблонам

Правила

• Все примеры кода на основной языке, определенном системой
• Каждая команда должна быть доступна для копирования и вставки с ожидаемым результатом
• Минимум 5 диаграмм Mermaid (архитектура, ER, последовательность, блок-схема, состояния)
• Используйте Mermaid для диаграмм рабочих процессов (цвета темного режима) — добавьте блок комментариев после каждой
• Все утверждения должны быть подкреплены реальным кодом — цитируйте с использованием формата ссылок

Руководство 2: Руководство для штатных инженеров

Файл: onboarding/staff-engineer-guide.md Аудитория: старшие/ведущие инженеры, которым необходимо понимать «почему» за каждым решением. Обладают глубоким опытом работы с системами, но могут не знать языка этого репозитория. Объём: 800–1200 строк. Концентрированное, субъективное, архитектурное руководство.

Обязательные разделы

1. Краткое содержание — Описание системы в одном плотном абзаце. Что система делает самостоятельно, а что делегирует.
2. Ключевая архитектурная идея — ЕДИНСТВЕННАЯ наиболее важная концепция. Включите псевдокод на ЯЗЫКЕ, ОТЛИЧАЮЩЕМСЯ от языка репозитория.
3. Архитектура системы — Полная диаграмма TB, выполненная в Mermaid. Выделите «сердце» системы.
4. Доменная модель — диаграмма erDiagram в формате Mermaid, отображающая основные сущности. Таблица инвариантов данных: сущность, инвариант, кто обеспечивает соблюдение, источник.
5. Ключевые абстракции и интерфейсы — диаграмма классов (classDiagram), демонстрирующая несущие абстракции.
6. Жизненный цикл запроса — sequenceDiagram (с автонумерацией), показывающий типичный запрос от входа до ответа.
7. Переходы между состояниями — stateDiagram-v2 для сущностей со значимыми состояниями жизненного цикла.
8. Журнал решений — таблица: решение, рассмотренные альтернативы, обоснование, источник.
9. Обоснование зависимостей — таблица: «Зависимость», «Цель», «Что она заменила», «Источник».
10. Поток данных и состояние — как данные перемещаются по системе. Таблица сравнения систем хранения данных.
11. Режимы сбоев и обработка ошибок — блок-схема путей распространения ошибок.
12. Характеристики производительности — узкие места, пределы масштабирования, «горячие» пути.
13. Модель безопасности — аутентификация, авторизация, границы доверия, степень конфиденциальности данных.
14. Стратегия тестирования — что тестируется, что нет, философия тестирования.
15. Известный технический долг — Таблица: проблема, уровень риска, затронутые файлы, источник.
16. На что следует обратить особое внимание — рекомендуемый порядок чтения исходных файлов, ссылки на разделы вики.

Правила

• Используйте псевдокод на другом языке для объяснения концепций
• Используйте сравнительные таблицы для сопоставления незнакомых концепций (например, Task =Awaitable[T])
• Плотный текст с таблицами, а НЕ поверхностные списки с маркерами
• Каждое утверждение должно подкрепляться ссылкой на источник
• Минимум 5 диаграмм Mermaid (архитектурная, ER, классная, последовательность, состояний, блок-схема)
• После каждой диаграммы следует блок комментариев
• Активно используйте таблицы — решения, зависимости, долг должны ВСЕ быть представлены в виде таблиц со столбцами «Источник»
• Сосредоточьтесь на том, ПОЧЕМУ были приняты решения, а не только на том, ЧТО существует

Руководство 3: Руководство для руководства

Файл: onboarding/executive-guide.md Аудитория: вице-президент/директор по инженерным вопросам. Требуется обзор возможностей, оценка рисков и контекст инвестиций — НЕ детали на уровне кода. Объем: 400–800 строк. Стратегический, лаконичный, ориентированный на принятие решений.

Обязательные разделы

1. Обзор системы — что она делает, кто ею пользуется, бизнес-ценность в 2–3 предложениях
2. Карта возможностей — Таблица: Возможность, Статус (Реализовано/Частично реализовано/Планируется), Степень зрелости, Зависимости. Что система может и чего не может делать на сегодняшний день.
3. Краткий обзор архитектуры — диаграмма Mermaid высокого уровня в формате LR. Сервисы, хранилища данных, внешние интеграции — БЕЗ деталей внутреннего кода. Акцент на единицах развертывания и границах команд.
4. Топология команды — Какая команда/какой человек отвечает за какие компоненты. Таблица: компонент, ответственное лицо, критичность, коэффициент «автобуса».
5. Тезис об инвестициях в технологии — Почему были выбраны именно эти технологии. Таблица: технология, цель, рассмотренные альтернативы, уровень риска.
6. Оценка рисков — Таблица: риск, вероятность, последствия, меры по снижению риска, ответственное лицо. Охватывает надежность, безопасность, масштабируемость и соответствие нормативным требованиям.
7. Модель затрат и масштабирования — как затраты меняются в зависимости от использования. Каковы узкие места. Когда потребуются следующие инвестиции в масштабирование.
8. Карта зависимостей — график TB, показывающий критические внешние зависимости. Таблица: зависимость, тип (сервис/библиотека/платформа), риск в случае недоступности.
9. Ключевые метрики и наблюдаемость — что измеряется, какие существуют информационные панели, охват оповещений. Таблица: метрика, текущее значение, целевое значение, источник.
10. Согласованность с дорожной картой — сопоставление инженерных рабочих потоков с бизнес-приоритетами. Что находится в процессе реализации, что запланировано, что заблокировано.
11. Сводка технического долга — 5 основных пунктов долга, оказывающих влияние на бизнес. Таблица: проблема, влияние на бизнес, трудозатраты на устранение, приоритет.
12. Рекомендации — 3–5 практических рекомендаций на следующий квартал, упорядоченных по степени влияния.

Правила

• НИКАКИХ фрагментов кода — это руководство предназначено для руководителей инженерных подразделений, а не для программистов
• Диаграммы должны быть на уровне сервисов/команд, а нена уровне классов/функций
• Каждое утверждение подкреплено доказательствами — ссылкина разделы вики, документацию по архитектуре или исходные файлы
• Минимум 3 диаграммы Mermaid (обзор архитектуры, карта зависимостей, возможности/дорожная карта)
• Таблицы для каждого структурированного вывода — эта аудитория читает таблицы, а не прозу
• Используйте бизнес-язык — переведите технические концепции в понятные показатели воздействия (надёжность, скорость, стоимость, риск)

Руководство 4: Руководство для менеджеров по продукту

Файл: onboarding/product-manager-guide.md Аудитория: продуктовые менеджеры и заинтересованные стороны, не связанные с разработкой. Им необходимо понимать, что делает система, что в ней возможно и где пролегают границы — а НЕ то, как она построена. Объем: 400–800 строк. Ориентирован на пользователя, сосредоточен на функциональности, учитывает ограничения.

Обязательные разделы

1. Что делает эта система — краткое описание из 2–3 предложений на понятном пользователю языке (без жаргона)
2. Карта пользовательского пути — диаграмма Mermaid LR или схема пути, демонстрирующая основные потоки пользователей в системе
3. Карта функциональных возможностей — таблица: функция, статус (в эксплуатации/бета-версия/в планах/невозможно), поведение с точки зрения пользователя, ограничения. Исчерпывающая карта того, что реализовано, а что нет.
4. Модель данных (с точки зрения продукта) — упрощённая диаграмма erDiagram, созданная в Mermaid, показывающая сущности, с которыми взаимодействуют пользователи. Объясните на бизнес-языке (например, «Проект имеет много документов», а не «связь по внешнему ключу»).
5. Флаги конфигурации и функций — Таблица: флаг/параметр, что он контролирует, значение по умолчанию, кто может его изменить. Что можно включать и выключать без технической работы.
6. Возможности API — Какие интеграции возможны. Таблица: Возможность, конечная точка/метод, аутентификация, ограничения по скорости. Написано для партнеров по интеграции, а не для разработчиков.
7. Производительность и SLA — Время отклика, ограничения пропускной способности, целевые показатели доступности. Таблица: Операция, ожидаемая задержка, ограничение пропускной способности, текущее SLA.
8. Известные ограничения и сдерживающие факторы — честный перечень того, что система не может делать или делает плохо. Таблица: Ограничение, Влияние на пользователя, Обходной путь, Планируемое исправление.
9. Данные и конфиденциальность — какие данные собираются, где они хранятся, политики хранения, статус соответствия нормативным требованиям. Таблица: тип данных, место хранения, срок хранения, соответствие нормативным требованиям.
10. Глоссарий — термины данной области, объясненные простым языком (без технического жаргона)
11. Часто задаваемые вопросы — более 10 типичных вопросов, которые может задать менеджер проекта, с краткими ответами

Правила

• АБСОЛЮТНО БЕЗ технического жаргона — никаких «промежуточного ПО», «инъекции зависимостей», «ORM». Используйте простой язык.
• Ориентация на пользователя — описывайте всё с точки зрения пользовательского опыта, а не того, как работает код
• Минимум 3 диаграммы Mermaid (путь пользователя, модель данных, карта функций/обзор возможностей)
• Таблицы для каждого структурированного вывода — менеджера по продукту просматривают таблицы, а не прозу
• Если необходимо упомянуть техническое понятие, объясните его одним предложением (например: «Флаги функций — переключатели, позволяющие включать и выключать функции без развертывания кода»)
• Каждое утверждение должно быть подкреплено доказательствами — указывайте разделы вики или исходные файлы для проверки

Правила создания диаграмм Mermaid (ВСЕ руководства)

ВСЕ диаграммы должны использовать цвета темного режима:

• Заливка узлов: #2d333b, границы: #6d5dfc, текст: #e6edf3
• Фон подграфов: #161b22, границы: #30363d
• Линии: #8b949e
• При использовании встроенных директив стиля используйте тёмную заливку с ,color:#e6edf3
• НЕ используйте
в метках Mermaid (используйте
или разрывы строк)

Проверка

После генерации каждого руководства проверьте:

• все указанные пути к файлам действительно существуют в репозитории
• Все имена классов/методов указаны верно (не выдуманы)
• Рендерируются ли диаграммы Mermaid (без синтаксических ошибок)
• Отсутствуют ли голые теги, похожие на HTML (общие типы, такие как List), за пределами блоков кода — их нужно заключать в обратные кавычки
• Каждое руководство соответствует своей целевой аудитории — в руководствах для руководителей и менеджеров проектов не должно быть кода