System Atlas

Строит интерактивные изометрические атласы архитектуры в виде HTML.

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

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

Навык System Atlas

Атлас — это один файл данных (data.mjs), из которого рендерятся два представления: интерактивная изометрическая карта (единственный самодостаточный atlas.html — наведите, чтобы прочитать; кликните, чтобы закрепить; зайдите внутрь ради шагов; движущиеся пакеты данных, которые можно рассмотреть; главы, раскрывающие систему по несколько структур за раз) и сгенерированный текстовый двойник (SYSTEM.md) с таблицей решений, каждой структурой, потоками и открытыми вопросами по ID. Файл данных — единственное, что кто-либо правит; оба представления пересобираются из него. Рядом с ним лежат написанный вручную глоссарий (CONTEXT.md) и ADR.

Делает: интерактивные карты архитектуры с постепенным раскрытием, отслеживание вопросов через раунды обратной связи, сгенерированный текстовый двойник и повторяемый цикл обновления. Не делает: статичные разовые диаграммы (для них — навык architecture-diagram или excalidraw), готовые системы, которым хватает README, или одну диаграмму для PR.

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

Используйте всякий раз, когда кто-то хочет обсудить, спроектировать, отревьюить или объяснить архитектуру визуально — «сделай атлас», «нарисуй карту системы», «сделай архитектуру интерактивной», «визуализируй кодовую базу/агента/конвейер, чтобы мы могли это обсудить», «диаграмма, по которой можно кликать», «проведи меня по тому, как всё это стыкуется», — или когда обсуждение архитектуры плодит кучу открытых вопросов, которые нужно отслеживать через раунды обратной связи. Также используйте его, чтобы обновить существующий атлас после того, как решения изменились. Лучше всего подходит, когда система настолько новая, что словарь, решения и вопросы ещё в движении и раундов обратной связи будет больше одного.

Требования

• Node.js (любая свежая версия; сборка использует только node:fs, node:path, node:url — npm install не нужен).
• Статический сервер для проверки (npx serve или python3 -m http.server).

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

mkdir -p <atlas home>/atlas
cp <skill>/assets/{template.html,build.mjs} <atlas home>/atlas/
cp <skill>/assets/data.example.mjs <atlas home>/atlas/data.mjs   # затем заполните его
node <atlas home>/atlas/build.mjs   # пишет ../SYSTEM.md и ../atlas.html

Каждое поле файла данных задокументировано в assets/data.example.mjs.

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

Процедура

Соблюдайте порядок — каждый шаг заработан поправкой в первый раз.

1. Прочитайте входные данные, прежде чем рисовать. Документ с видением, существующие поверхности репозитория и всё, что пользователь разрешает из предшествующих наработок (спросите — он может запретить какую-то ветку или источник). Если будете строить на фреймворке, сначала прочитайте его документацию; длинные документы отдайте субагенту через delegate_task с вашими конкретными вопросами по дизайну и попросите вернуть вводный конспект с подводными камнями и списком «чего он нам не даёт». Рисование до этого даёт коробки, которые ни на что реальное не ложатся.
2. Обсудите, прежде чем рисовать. Предложите структуру в чате, привязанную к настоящим примитивам runtime, и задайте только те вопросы, которые нельзя вывести из репозитория. Для остального возьмите значения по умолчанию и скажите какие.
3. Первый атлас — вся система. Скопируйте assets/ в домашний каталог атласа (переименуйте data.example.mjs в data.mjs), заполните данные, соберите через node, опубликуйте. Где находится домашний каталог атласа, зависит от политики репозитория по документации — спросите, прежде чем что-либо коммитить. Репозитории, дружелюбные к документации: docs/{system}/atlas/ в дереве. Репозитории, где коммитят только ADR и CONTEXT.md: положите атлас, SYSTEM.md и research/ в игнорируемый git черновой каталог, а при публикации приложите SYSTEM.md + исследования к issue со спецификацией. (Однажды коммит всего набора породил PR с документацией на 3 900 строк и четыре раунда ревью, сводившие три пересказа одного дизайна.) Если полезно, загрузите через skill_view навык design-md или architecture-diagram ради рекомендаций по HTML-артефактам; references/design-language.md с визуальными правилами прочитайте в любом случае.
4. Постепенное раскрытие. Вся система разом читается как шум. Порядка десяти глав; каждая добавляет не больше трёх структур и прогоняет один небольшой поток, который касается только уже раскрытых структур; последняя глава показывает всё с выбором потока. Нераскрытые структуры остаются в индексе, приглушённые, с номером своей главы. Панели показывают сначала сводку: одно предложение, затем свёрнутые Read more и Steps.
5. Формы и подписи. Букв на коробках недостаточно. Дайте каждой роли свою форму и поместите читаемую подпись с именем на холсте под каждой структурой — см. design-language.
6. Текстовый двойник. CONTEXT.md — глоссарий и ничего больше (существительные, по строке на каждое); ADR — только для решений, которые трудно отменить, удивляют без контекста и стали результатом настоящего компромисса; эти два — части, живущие в дереве. SYSTEM.md генерируется, а research/ хранит доказательства; оба живут рядом с атласом (черновой каталог или docs/, согласно шагу 3). Не открывайте issue, если не просили.
7. Обратная связь по ID вопроса. Каждый вопрос — Q-<code><n> с состоянием: открыт (строка), решён {q, r} (ответ + дата) или перенаправлен {q, to} (передан именованному следующему шагу). Записывайте слова пользователя. Если он называет что-то «не вопросом» — убирайте; если говорит «я этого не понимаю» — объясните на конкретном примере до того, как помечать решённым. После каждого раунда: пересобрать, переопубликовать, обновить память.
8. Глубокие исследования возвращаются в атлас. Исследуйте субагентами (delegate_task) по одному общему брифу (интерфейс, которым владеем мы; требования, которые разделяют кандидатов; модель использования для оценки стоимости; фиксированная форма результата). Напишите синтез с нормализованной сеткой «стоимость/соответствие». Резолюции вносите в данные как {q, r: '… (from the deep dive, date)'}. Если пользователь отвергает предложение, пройдитесь по каждому файлу и перепишите — баннера поверх устаревшего раздела недостаточно.
9. Держите в актуальном состоянии. Один источник, пересборка и переопубликация после каждого изменения, никаких ручных правок сгенерированных файлов, и оставьте в папке с документацией README.md, объясняющий набор (таблица в references/process-and-lessons.md).

Публикация

atlas.html — один самодостаточный файл: без шага сборки, без внешних ресурсов, кроме стилей Google Fonts. Раздайте папку любым статическим сервером (npx serve, python3 -m http.server) и передайте URL, либо пусть хостинг страниц репозитория отдаёт закоммиченный файл. Один URL, переопубликованный после каждого изменения данных, и никогда — вторая копия. Если у вас есть стабильный опубликованный URL, положите его в META.artifactUrl, чтобы SYSTEM.md на него ссылался.

Подводные камни

• <!doctype html> держите первым, а <meta charset="utf-8"> сразу за ним — иначе quirks mode и кракозябры вместо стрелок.
• Рендерер пересобирает всю сцену при каждой отрисовке: случайный render() в обработчике наведения отсоединяет элемент под курсором, и браузер перестаёт генерировать клики — на скриншоте карта выглядит идеально, а не реагирует ничего.
• Некоторые встроенные в приложения браузеры показывают file:// как статичный снимок; проверяйте через статический сервер, а не с диска.
• Никогда не удаляйте вопрос — решайте или помечайте снятым, чтобы ID оставались стабильными.
• После каждого решения ищите в выходных файлах устаревшие слова (pending, старое имя модели, отвергнутый дизайн) — человек читает всё.
• Большие HTML/JS через heredoc в shell ломаются; используйте write_file и держите блок данных сериализуемым в JSON.

Проверка

• node <atlas home>/atlas/build.mjs завершается с кодом 0 и пишет и SYSTEM.md, и atlas.html.
• Проверьте синтаксис собранного скрипта (new Function(js)), затем откройте раздаваемую страницу в настоящем браузере при ~1280×800; проверьте первую главу, среднюю главу, последнюю главу, вид изнутри и светлую тему.
• Кликните структуру и убедитесь, что панель показывает pinned и предлагает Go inside; кликните точку пакета и убедитесь, что открывается полезная нагрузка.
• У каждой структуры есть one, what, how, подпись short, роль kind и её вопросы; призраки помечены; главы существуют с потоками на каждую главу; последняя глава — вся система.
• SYSTEM.md содержит таблицу решений, индекс вопросов с ID и состояниями и подвал «how this file is maintained».
• Память проекта хранит URL атласа, пути к документации, зафиксированные решения с датами, что пользователь отверг и почему, и следующий шаг.