Когда документация живёт своей жизнью

Знаете, что держит на плаву половину критичной инфраструктуры в мире? Пять команд, которые кто-то помнит наизусть. Та самая магическая последовательность kubectl с флагами, про которые уже никто не может объяснить, зачем они нужны. Или запрос к базе данных, который Сергей из DevOps написал полгода назад и теперь судорожно ищет в истории терминала каждый раз, когда что-то падает в три часа ночи.

А документация? Она где-то есть. Может быть, в Notion. Возможно, закопана в Confluence. Скорее всего — просто устарела. Копируешь команду из wiki, запускаешь, получаешь ошибку. Идёшь искать в Slack. Там находишь треть от нужного. Остальное додумываешь методом проб и ошибок на продакшене. Весело? Не очень.

Именно эту боль и пытается решить Atuin Desktop — проект, который находится сейчас в открытой бете и предлагает довольно радикальный подход: runbook’и, которые не просто описывают, что делать, а реально это делают.

Документация, которая не врёт

Представьте себе документ, который выглядит как обычный Markdown с инструкциями, но при этом может выполнять команды прямо внутри себя. Вы пишете последовательность шагов для развёртывания приложения — и тут же можете прогнать весь процесс, не копируя ничего в терминал. Если что-то не работает, сразу видите ошибку и можете поправить.

Это не совсем Jupyter Notebook для bash (хотя что-то общее есть). Atuin Desktop встраивает полноценный терминал прямо в интерфейс редактора. Добавляете блок кода с пометкой “shell” — и получаете возможность запустить его одним кликом. Результат выполнения отображается тут же, в контексте документа.

Больше никаких ситуаций в стиле “а эта команда ещё работает?” или “подождите, там путь другой”. Документ либо выполняется, либо нет. И если не выполняется — его сразу можно починить. Такая документация не успевает устареть, потому что её постоянно прогоняют.

Команда Atuin решила, что terminal history — это неплохо, но недостаточно. История показывает, что вы делали. Runbook должен показывать, что нужно делать, когда случается X.

Больше, чем просто терминал в редакторе

Конечно, идея запускать команды из документа не нова. Есть куча инструментов для executable notebooks. Но Atuin Desktop интересен тем, что замахивается на реальные рабочие процессы — те самые, которые обычно живут в головах инженеров и очень редко попадают в формализованную документацию.

Во-первых, там есть шаблонизация в стиле Jinja. Можете писать runbook с переменными — например, название окружения, версию релиза, имя пользователя — и подставлять их на лету. Один runbook для staging, production и develop. Меняете параметр — и те же самые шаги выполняются для другого окружения.

Во-вторых, поддержка не только shell-команд. Есть встроенные клиенты для баз данных (можете прямо в runbook’е писать SQL-запросы и видеть результаты), HTTP-запросы, даже интеграция с Prometheus для мониторинга. То есть ваш “сценарий действий при инциденте” может включать в себя и проверку метрик, и запросы к API, и работу с базой — всё в одном месте.

В-третьих (и это, наверное, самое необычное) — local-first архитектура с CRDT. Звучит пугающе, но на практике означает, что ваши runbook’и хранятся локально, работают оффлайн, а синхронизация с командой происходит автоматически, когда есть сеть. Никаких конфликтов при одновременном редактировании — система сама разруливает. Как в Google Docs, только без необходимости постоянно быть онлайн.

Кому это вообще нужно?

Хороший вопрос. На первый взгляд кажется, что это такой niche-инструмент для каких-то очень специфичных кейсов. Но копнёшь глубже — и понимаешь, что подобные сценарии встречаются постоянно.

Вот релиз-менеджмент. Классика: есть чек-лист, что нужно сделать перед деплоем. Обновить зависимости, прогнать тесты, проверить миграции, задеплоить на staging, убедиться что всё работает, задеплоить на прод, проверить метрики. Половину из этого приходится делать руками, потому что полная автоматизация слишком сложна (или её просто никто не доделал). С Atuin Desktop этот чек-лист превращается в executable runbook — нажимаете кнопку, он сам выполняет все шаги. Если где-то упал — видите, на каком именно месте.

Или миграция инфраструктуры. Переезжаете с одного облака на другое, и у вас есть последовательность из пятидесяти команд, которую нужно выполнить в строгом порядке. Обычно это живёт в каком-нибудь bash-скрипте, который написан на коленке и который страшно запускать, потому что непонятно, что он сделает. Runbook наглядно показывает каждый шаг, можно выполнять их по одному, проверяя результат, а можно прогнать всё разом.

База данных требует особого внимания. Кто-то должен регулярно запускать определённые запросы для мониторинга, очистки, миграций. Обычно эти запросы живут в чьём-то текстовом файле или в отдельном репозитории скриптов. Atuin Desktop позволяет держать их в контексте — с пояснениями, почему это нужно, когда запускать, что означает результат.

И самое важное — incident response. Когда всё падает, у вас есть минуты, чтобы разобраться что к чему. Времени искать правильные команды нет. Runbook с готовой последовательностью действий — “проверить логи вот здесь, посмотреть метрики вот тут, перезапустить вот это” — может сэкономить кучу нервов и времени. Особенно если в команде несколько человек, и не все из них знают систему досконально.

Локально и синхронизировано одновременно

Интересная деталь: Atuin Desktop не пытается быть облачным сервисом. Ваши runbook’и живут у вас на машине. Работают без интернета. Но при этом есть возможность синхронизации через Atuin Hub — их облачный сервис. То есть вы можете работать оффлайн, а когда появится сеть, изменения сами подтянутся на другие устройства и к коллегам.

Это решает сразу две проблемы: вы не зависите от стабильности чьих-то серверов, и вам не нужно морочиться с настройкой git-репозитория для документации. Просто пишете, сохраняете — и оно само синхронизируется.

Механизм CRDT (Conflict-free Replicated Data Types) под капотом означает, что даже если двое людей редактируют один runbook одновременно, конфликтов не будет. Система сама их разрешит. Это конечно не значит, что результат всегда будет идеальным, но по крайней мере ничего не сломается, и вы не потеряете чьи-то изменения.

Всё ещё бета, но уже рабочее

Важное уточнение: проект находится в открытой бете. То есть он работает, им можно пользоваться, но команда активно собирает фидбек и дорабатывает функциональность. Возможны баги, недоделанные фичи. С другой стороны — это шанс повлиять на развитие инструмента, если тема вам откликается.

Скачать можно с GitHub releases, нужно только зарегистрироваться в Atuin Hub (это бесплатно на старте). Логинитесь в desktop-приложении — и можете создавать runbook’и.

В планах у команды — больше интеграций (дополнительные клиенты для баз данных, инструменты мониторинга, API), а самое интересное — возможность автоматически генерировать runbook’и из истории команд. То есть вы делаете что-то в терминале, Atuin следит за последовательностью команд, и потом предлагает сохранить это как runbook с комментариями. Если это сработает хорошо - может стать киллер-фичей.

Документация как код

В индустрии последние годы популярна идея “documentation as code” — хранить доки в git, писать их в Markdown, собирать автоматически. Atuin Desktop предлагает как бы инверсию: код как документация. Ваши рабочие процессы становятся документами, которые можно читать, понимать и выполнять.

Возможно, это не заменит все ваши внутренние wiki и Confluence-страницы. Но для тех кейсов, где документация быстро устаревает, потому что процесс меняется — executable runbook’и выглядят как разумное решение.