Code Wiki

Генерация вики-документации и диаграмм Mermaid для любой кодовой базы.

Метаданные навыка


Источник	Опционально — установка с помощью `vibeos skills install official/software-development/code-wiki`
Путь	`optional-skills/software-development/code-wiki`
Версия	`0.1.0`
Автор	Teknium (teknium1), VibeOS
Лицензия	MIT
Платформы	linux, macos, windows
Теги	`Documentation`, `Mermaid`, `Architecture`, `Diagrams`, `Wiki`, `Code-Analysis`
Связанные навыки	`codebase-inspection`, `github-repo-management`

Справочник: полный SKILL.md

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

Навык Code Wiki

Создание комплексной вики для любой кодовой базы: обзор, архитектура, детальный разбор каждого модуля, диаграммы классов и последовательностей Mermaid. Вдохновлено Google CodeWiki, но работает с локальными репозиториями, приватными репозиториями и любыми языками. Использует только существующие инструменты VibeOS (terminal, read_file, search_files, write_file); не требует Docker, внешних сервисов или дополнительных зависимостей.

Этот навык создаёт справочную документацию (что/как). Он не создаёт стратегическое повествование (почему — это другой навык).

Когда использовать

Пользователь говорит «задокументируй эту кодовую базу», «создай вики», «сделай диаграммы архитектуры»
Онбординг в незнакомый репозиторий и требуется структурированная справка
Пользователь указывает на URL GitHub и просит документацию
Нужен стабильный артефакт (markdown + Mermaid), который отображается на GitHub

НЕ используйте для:

Документирования одного файла или одной функции — просто ответьте напрямую
Справочника API для одной конкретной конечной точки — используйте read_file и ответьте в строке
Стратегического повествования «почему это существует» — другой навык, другая цель
Кодовых баз, которые пользователь активно разрабатывает в этой сессии — просто отвечайте на вопросы по мере их поступления

Предварительные требования

Переменные окружения не требуются.
git в PATH для отслеживания SHA репозитория и удалённого клонирования.
Опционально: pygount для статистики по языкам (см. навык codebase-inspection).

Как запустить

Вызов через инструмент terminal из корня целевого репозитория, затем используйте read_file / search_files / write_file для создания вики. Место вывода по умолчанию: ~/.vibeos/wikis/<repo-name>/. Записывайте в репозиторий (docs/wiki/) только по явному запросу пользователя.

Краткая справка

Шаг	Действие
1	Определить цель — локальная cwd, заданный путь или `git clone --depth 50 <url>` во временную директорию
2	Просканировать структуру — `ls`, `find -maxdepth 3`, файлы манифестов, README
3	Выбрать 8–10 модулей для документирования
4	Написать `README.md` (обзор + карта модулей)
5	Написать `architecture.md` с блок-схемой Mermaid
6	Написать документацию для каждого модуля в `modules/`
7	Написать `diagrams/class-diagram.md` (classDiagram Mermaid)
8	Написать `diagrams/sequences.md` (sequenceDiagram Mermaid, 2–4 сценария работы)
9	Написать `getting-started.md`
10	Написать `api.md` если применимо, иначе пропустить
11	Написать `.codewiki-state.json`
12	Сообщить пользователю пути

Процедура

1. Определить цель

Для URL GitHub:

WIKI_TMP=$(mktemp -d)
git clone --depth 50 <url> "$WIKI_TMP/repo"
cd "$WIKI_TMP/repo"
REPO_SHA=$(git rev-parse HEAD)
REPO_NAME=$(basename <url> .git)

Для локального пути (или cwd, если путь не указан):

cd <path>
REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
REPO_NAME=$(basename "$PWD")

Затем установите выходную директорию:

OUTPUT_DIR="$HOME/.vibeos/wikis/$REPO_NAME"
mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"

2. Просканировать структуру репозитория

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

# Сначала поверхностное дерево
ls -la

# Более глубокое дерево, с фильтрацией шума
find . -type d \
  -not -path '*/\.*' \
  -not -path '*/node_modules*' \
  -not -path '*/venv*' \
  -not -path '*/__pycache__*' \
  -not -path '*/dist*' \
  -not -path '*/build*' \
  -not -path '*/target*' \
  -maxdepth 3 | sort

# Разбивка по языкам (пропустить, если pygount недоступен)
pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,target" \
  . 2>/dev/null || true

Затем read_file соответствующих манифестов (package.json, pyproject.toml, setup.py, Cargo.toml, go.mod, pom.xml, build.gradle) и README проекта. Используйте search_files target='files' для их поиска, а не угадывания имён.

3. Выбрать модули для документирования

Ограничьте первый проход 8–10 модулями. Эвристика по языкам:

Python: пакеты верхнего уровня (директории с __init__.py), плюс подсистемные директории
JS/TS: src/<subdir>, директории рабочего пространства верхнего уровня
Rust: каждый крейт в рабочем пространстве или директории src/<module> верхнего уровня
Go: каждая директория пакета верхнего уровня
Смешанные/незнакомые: директории верхнего уровня, содержащие исходный код (не конфигурацию, не тесты)

Для очень больших репозиториев приоритизируйте по:

Количеству импортов (модуль, импортируемый многими, является основным)
LOC (более крупные модули обычно заслуживают отдельной документации)
Упоминаниям в README / документации верхнего уровня

Сообщите пользователю список модулей перед созданием документации для каждого модуля в больших репозиториях — это даст ему возможность перенаправить.

4. Написать `README.md`

read_file фактического README проекта плюс 2–3 файла точек входа верхнего уровня. Затем write_file:

# <Название проекта>

<Один абзац: что это и для чего. Самодостаточно — не предполагайте, что
читатель имеет исходный README.>

## Ключевые концепции

- **<Концепция 1>** — <одна строка>
- **<Концепция 2>** — <одна строка>

## Точки входа

- `path/to/main.py` — <что запускается при старте>
- `path/to/cli.py` — <CLI-интерфейс>

## Высокоуровневая архитектура

<2-3 предложения. Подробности в architecture.md.>

См. `architecture.md`.

## Карта модулей

| Модуль | Назначение |
|---|---|
| `<module>` | <назначение в одну строку> |

## Начало работы

См. `getting-started.md`.

Для целей ссылок в локальном режиме используйте относительные пути. Для клонированных репозиториев используйте https://github.com/<owner>/<repo>/blob/<sha>/<path>, чтобы ссылки сохранялись после будущих коммитов.

5. Написать `architecture.md`

# Архитектура

<2-3 абзаца: форма системы. Что с чем взаимодействует. Где данные входят,
где выходят, где находится состояние.>

## Компоненты

- **<Компонент>** — <1-2 предложения>. См. `modules/<module>.md`.

## Диаграмма системы

```mermaid
flowchart TD
    User([Пользователь]) --> Entry[Точка входа]
    Entry --> Core[Основной движок]
    Core --> StorageA[(База данных)]
    Core --> ExternalAPI{{Внешний API}}
```

## Поток данных

1. **<Шаг>** — `<file>`
2. **<Шаг>** — `<file>`

## Ключевые проектные решения

- <Всё важное, что читатель должен знать>

Семантика фигур Mermaid:

[] = компонент
[()] = база данных / хранилище
{{}} = внешний сервис
(()) = точка входа или терминал
--> = синхронный вызов, -.-> = асинхронный/событие

Ограничьте диаграмму ~20 узлами. При большем размере разделите на поддиаграммы.

6. Написать документацию для каждого модуля в `modules/`

Для каждого выбранного модуля проверьте его структуру с помощью ls, определите 3–5 наиболее важных файлов (по размеру, по имени core.py / main.py / __init__.py, по частоте импорта), затем read_file этих файлов (используйте offset / limit для чтения только необходимого; предпочитайте search_files для конкретных символов).

# Модуль: `<module>`

<Назначение в 1-2 предложения.>

## Обязанности

- <пункт>
- <пункт>

## Ключевые файлы

- `<module>/<file>` — <что делает>

## Публичный API

<Функции/классы/константы, используемые другим кодом. Группируйте связанные элементы. Показывайте
сигнатуры, а не полные реализации.>

## Внутренняя структура

<Как модуль организован внутри. Управление состоянием.>

## Зависимости

- **Используется:** <другие модули>
- **Использует:** <другие модули + внешние библиотеки>

## Примечательные паттерны / «Грабли»

- <Всё неочевидное>

7. Написать `diagrams/class-diagram.md`

Выберите 5–10 наиболее важных классов/типов. read_file их, затем напишите:

# Диаграмма классов

## Основные типы

```mermaid
classDiagram
    class Agent {
        +string name
        +list~Tool~ tools
        +chat(message) string
    }
    class Tool {
        <&lt;interface&gt;>
        +name string
        +execute(args) any
    }
    Agent --> Tool : использует
    Tool <|-- TerminalTool
    Tool <|-- WebTool
```

## Примечания

<Всё, что диаграмма не может выразить — жизненный цикл, потоки и т.д.>

Для языков без классов (Go, C, Rust): используйте диаграмму для отношений структур или пропустите class-diagram.md и объясните это в прозе в architecture.md. Не подгоняйте насильно.

8. Написать `diagrams/sequences.md`

Выберите 2–4 наиболее важных сценария работы. Проследите каждый путь вызова через код (прочитайте точку входа, следуйте за вызовами функций), затем:

# Диаграммы последовательностей

## Сценарий: <Название>

<1 предложение, описывающее, что это делает и когда запускается.>

```mermaid
sequenceDiagram
    participant Пользователь
    participant CLI
    participant Агент
    participant LLM
    Пользователь->>CLI: вводит сообщение
    CLI->>Агент: chat(message)
    Агент->>LLM: вызов API
    LLM-->>Агент: ответ + tool_calls
    Агент->>Агент: выполнение инструментов
    Агент-->>CLI: финальный ответ
```

### Пошаговое описание

1. **Ввод пользователя** — `cli.py:VibeOSCLI.run_session`
2. **Отправка сообщения** — `run_agent.py:AIAgent.chat`

Не выдумывайте участников. Каждый блок должен соответствовать реальному компоненту, который читатель может найти в коде.

9. Написать `getting-started.md`

# Начало работы

## Предварительные требования

<Из файлов манифестов + README. Будьте конкретны — версии, если зафиксированы.>

## Установка

```bash
&lt;точные команды&gt;
```

## Первый запуск

```bash
&lt;минимальная команда, чтобы увидеть, как система делает что-то полезное&gt;
```

## Типовые сценарии работы

### <Сценарий 1>
<команды>

## Конфигурация

- `<config-file>` — <что контролирует>
- Переменная окружения `<VAR>` — <что контролирует>

## Куда двигаться дальше

- Архитектура: `architecture.md`
- Справочник модулей: `README.md#module-map`

10. Написать `api.md` (пропустить, если не применимо)

Пишите это только если проект является библиотекой или API-сервером. Если это так:

Найдите публичную поверхность API (экспорты __init__.py, спецификации OpenAPI, обработчики маршрутов, экспортируемые типы)
Документируйте каждую публичную точку входа с сигнатурой, параметрами, типом возврата, описанием в одну строку
Группируйте по категориям

11. Написать файл состояния

cat > "$OUTPUT_DIR/.codewiki-state.json" <<EOF
{
  "repo_name": "$REPO_NAME",
  "source_path": "$PWD",
  "source_sha": "$REPO_SHA",
  "generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "generator": "vibeos-agent code-wiki skill v0.1.0",
  "modules_documented": []
}
EOF

12. Сообщить пользователю

Укажите, что именно было создано и где:

Создана вики в ~/.vibeos/wikis/<repo-name>/:
  README.md                   обзор проекта, карта модулей
  architecture.md             архитектура системы + блок-схема
  getting-started.md          настройка, первый запуск, сценарии работы
  modules/<N файлов>          детальный разбор модулей
  diagrams/architecture.md    блок-схема Mermaid
  diagrams/class-diagram.md   диаграмма классов Mermaid
  diagrams/sequences.md       диаграммы последовательностей Mermaid

Если вы клонировали во временную директорию, напомните пользователю, что её можно удалить (rm -rf "$WIKI_TMP") после просмотра вики.

Контроль объёма

Создание полной вики для монорепозитория на 500 КLOC чрезвычайно затратно по токенам. По умолчанию используйте ограниченный объём:

Начальное сканирование: максимальная глубина 3 директории
Документация для каждого модуля: не более 10 модулей, если пользователь не расширит объём
Чтение файлов: предпочитайте search_files для символов + read_file с offset/limit вместо полного чтения
Пропускайте вендорный код (vendor/, third_party/, сгенерированный код, _pb2.py, .min.js)

Если пользователь говорит «сделай всё исчерпывающе», поверьте ему — но сначала прикиньте стоимость: «в этом репозитории ~340 исходных файлов, полное покрытие будет дорогим — подтвердить?»

Повторный запуск / Обновление

Если .codewiki-state.json уже существует по целевому пути:

Прочитайте его для получения предыдущего SHA и списка модулей
Если SHA источника совпадает: спросите пользователя, хочет ли он перегенерировать или пропустить
Если SHA отличается: предложите перегенерировать только модули с изменёнными файлами (git diff --name-only <old-sha> HEAD)

Полная инкрементальная регенерация — это будущее улучшение; пока что перегенерация всего целиком приемлема.

«Грабли»

Выдумывание компонентов. Каждый узел диаграммы и заявленный вызов функции должен быть в исходном коде. read_file перед записью. Самый распространённый сбой автогенерируемой документации — правдоподобные выдумки.
Шаблонный AI-текст. «Этот модуль отвечает за...» — бессодержательно. Говорите, что модуль на самом деле делает, на предметно-ориентированном языке.
Пересказ кода в прозе. Документация модуля, в которой говорится «функция process обрабатывает вещи, вызывая process_item для каждого элемента», хуже, чем просто ссылка на функцию.
Mermaid > 50 узлов. Они не отображаются читаемо. Разделяйте их.
Документирование тестов, сгенерированного кода или вендорных зависимостей как продакшн-кода. Пропускайте их.
Вывод в репозиторий без запроса. По умолчанию ~/.vibeos/wikis/. Записывайте в репозиторий только по явному запросу пользователя.
Спецсимволы Mermaid требуют кавычек: A["Tool / Agent"], а не A[Tool / Agent]. <br> для переноса строк внутри узла.
Вложенные блоки кода в SKILL.md. При написании примера markdown, содержащего блок Mermaid, используйте внешние обрамления из 4 обратных кавычек, чтобы внутренние 3 обратные кавычки ```mermaid не закрывали внешние. (Этот SKILL.md так и делает.)
Дженерики classDiagram отображаются как ~T~ (например, List~Tool~), а не <T>.
Тема Mermaid на GitHub фиксирована — не включайте блоки %%{init: ...}%%; они удаляются при отображении.

Верификация

После записи проверьте:

Баланс блоков Mermaid — количество открывающих равно количеству закрывающих в каждом файле:

for f in "$OUTPUT_DIR"/diagrams/*.md "$OUTPUT_DIR"/architecture.md; do
  opens=$(grep -c '^```mermaid' "$f")
  total=$(grep -c '^```' "$f")
  echo "$f: $opens блоков mermaid, $total всего обрамлений (ожидается total = opens*2)"
done

Все ожидаемые файлы существуют —

ls "$OUTPUT_DIR"/{README.md,architecture.md,getting-started.md,.codewiki-state.json} \
   "$OUTPUT_DIR"/modules/ "$OUTPUT_DIR"/diagrams/

Количество модулей соответствует задуманному — ls "$OUTPUT_DIR/modules" | wc -l должно равняться количеству модулей, которые вы обязались задокументировать на Шаге 3.
Нет вымышленных путей — выборочно проверьте 2–3 ссылки на исходники, что они ведут к реальным файлам.

Метаданные навыка​

Справочник: полный SKILL.md​

Навык Code Wiki

Когда использовать​

Предварительные требования​

Как запустить​

Краткая справка​

Процедура​

1. Определить цель​

2. Просканировать структуру репозитория​

3. Выбрать модули для документирования​

4. Написать README.md​

5. Написать architecture.md​

6. Написать документацию для каждого модуля в modules/​

7. Написать diagrams/class-diagram.md​

8. Написать diagrams/sequences.md​

9. Написать getting-started.md​

10. Написать api.md (пропустить, если не применимо)​

11. Написать файл состояния​

12. Сообщить пользователю​

Контроль объёма​

Повторный запуск / Обновление​

«Грабли»​

Верификация​