AI-промпт: "Объясни и задокументируй мой bash-скрипт"

Вы написали сложный скрипт. Через месяц вы сами с трудом вспомните, как он работает. А что уж говорить о коллегах. Хорошая документация — это не роскошь, а необходимость. Давайте заставим AI сделать скучную работу за нас.

Промпт (для ChatGPT/Gemini/Copilot):

Выступи в роли Senior Site Reliability Engineer (SRE) и эксперта по bash.
Проанализируй следующий bash-скрипт. Предоставь полный разбор в формате Markdown.

Скрипт:
bash

#!/bin/bash
BACKUP_DIR="/mnt/backups/postgres"
TIMESTAMP=$(date +"%F")
PG_USER="postgres"
DATABASE="production_db"
KEEP_DAYS=7

if ! pg_dump -U "$PG_USER" -d "$DATABASE" | gzip > "$BACKUP_DIR/$DATABASE-$TIMESTAMP.sql.gz"; then
    echo "Ошибка создания бэкапа" >&2
    exit 1
fi

find "$BACKUP_DIR" -type f -name "*.sql.gz" -mtime +"$KEEP_DAYS" -exec rm {} \;

Формат ответа:

Общее назначение: Опиши одним предложением, что делает скрипт.
Пошаговое объяснение: Детально объясни каждую команду и конструкцию (if, pipe, find -exec и т.д.).
Переменные: Опиши назначение каждой переменной.
Рекомендации по улучшению: Предложи 2-3 улучшения (например, добавить проверку на существование директории, улучшить логирование, добавить set -e).

Взгляд архитектора:
Архитектор думает не только о том, чтобы код работал, но и о его поддерживаемости (maintainability). AI в данном случае выступает как инструмент для автоматизации документирования и ревью кода. Это позволяет поддерживать высокое качество даже в небольшой команде, снижает порог входа для новых сотрудников и превращает "одноразовые" скрипты в надёжные и понятные инструменты.

#ai4admin #bash #documentation #automation #sre #промпты

AI-промпт: "Наследие". AI документирует чужой docker-compose.yml

Вы получили в наследство проект. Документации нет. Есть только один файл — docker-compose.yml на 150 строк, 10 сервисов, 5 сетей и 8 "volumes". Как в этом разобраться?

Заставим AI сделать за нас реверс-инжиниринг и создать документацию.

Промпт (для ChatGPT/Gemini/Copilot):

Выступи в роли Senior DevOps Engineer и эксперта по Docker.
Я передаю тебе `docker-compose.yml` из унаследованного проекта.

[...ВСТАВЬТЕ СЮДА ВЕСЬ КОД docker-compose.yml...]

Твоя задача — создать для меня Markdown-документацию:
1.  Общая архитектура: Опиши одним абзацем, что это за приложение (например, "Это стек WordPress, состоящий из веб-сервера Nginx, самого WordPress (PHP-FPM) и базы данных MariaDB").
2.  Разбор по сервисам: Для каждого сервиса (`nginx`, `wordpress`, `db`...):
     Назначение: Что он делает?
     Образ: Какой образ Docker используется?
     Порты: Какие порты и куда пробрасываются?
     Volumes: Какие директории монтируются и за что они отвечают?
     Зависимости: От каких других сервисов он зависит.
3.  Сетевое взаимодействие: Опиши, какие сети используются и кто с кем может общаться.
4.  Хранение данных: Перечисли все именованные `volumes` и объясни, что в них хранится.

Взгляд архитектора: Архитектор не тратит 3 часа на рутинный реверс-инжиниринг. Он использует AI как когнитивный разгрузчик (cognitive unloader). AI создает 90% базовой документации за 30 секунд. Инженер тратит 10 минут на проверку и дополнение этой базы, экономя часы драгоценного времени, которое он может потратить на проектирование, а не на раскопки.

#ai4admin #docker #devops #documentation #automation #промпты #sre

Архитектура: "Docs as Code". Почему ваша документация — это ваш главный актив

Реакция админа: "У меня нет времени писать документацию".
Мысль архитектора: "У меня нет времени НЕ писать документацию".

Документация — это не "скучные Word-файлы".
В современном IT, документация — это код.

Что такое "Docs as Code":

Формат: Вы пишете в Markdown (.md). Это простой, чистый текст.

Хранилище: Вы храните .md файлы в Git-репозитории (на том же Gitea, что мы ставили) вместе с вашими скриптами и IaC-конфигами.

Инструменты: Вы используете MkDocs, Hugo или просто VS Code для рендеринга.

Почему это меняет всё:

Версионность: Ваша документация имеет историю. Вы видите, кто и когда изменил IP-адрес сервера в "runbook".

Runbooks: Вы не "чините по памяти". Вы открываете restore_db.md и копируете проверенные команды.

Схемы как Код: Вы рисуете диаграммы с помощью PlantUML или Mermaid — прямо текстом!

Масштабирование: Вы можете "форкнуть" документацию, предложить изменения через Pull Request.

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

#architect #devops #gitops #documentation #sre #стратегия #гайд

🗺️ Карта сокровищ: Почему схема важнее твоей памяти

Представь: 3 января. Ты на даче, без связи. Падает критический сервис. Дежурный админ открывает консоль и видит мешанину из IP-адресов, контейнеров и балансировщиков. Он звонит тебе, но ты недоступен.

Ошибка Джуна: Держать архитектуру в голове. "Я же всё помню".
Правило Сеньора: То, что не задокументировано — не существует.

Перед праздниками сделай команде подарок — актуальную схему.

Почему это важно:

1. Bus Factor: Если завтра тебя переманят в Google, проект не должен встать.

2. Скорость траблшутинга: По схеме проблема локализуется за 5 минут ("Ага, это отвалился Redis-кэш"), в консоли — за час.

3. Онбординг: Новички скажут тебе спасибо.

Не обязательно рисовать в Visio. Используй draw.io или Mermaid (схемы как код). Главное — чтобы это было.

#skills #architecture #documentation #devops #mindset #busfactor

🏛️ Пятничный лонгрид: Искусство «ленивого» админа или почему твоя документация — это код

Все мы знаем классику: админ, который работает 24/7, постоянно в мыле и с красными глазами, считается «героем». Но в 2026 году настоящий герой — это тот, кто в пятницу вечером спокойно пьёт кофе, потому что его инфраструктура умеет «лечить» сама себя. ☕🧘‍♂️

Давай разберем три столпа, на которых держится спокойный сон сисадмина.

1. Документация в стиле README.md
Забудь про Word-файлы в папке «Общее». Если инструкции нет в Git-репозитории рядом с кодом или скриптами — её не существует.

Правило: Любое изменение в системе = коммит в репозиторий с описанием.

Инструмент: Изучи Obsidian или Logseq для личной базы знаний (Zettelkasten). Это позволяет связывать ошибки (например, «Падение БД») с их решениями графами связей.

2. Bash/PowerShell как «внешняя память»
Если ты ввел команду в консоли дважды — запиши её в скрипт. Если трижды — параметризируй её (сделай переменные).

Bash: Используй history | grep "что-то_сложное", чтобы вспомнить тот самый длинный конвейер из awk и sed, который ты мучил в прошлый вторник.

PowerShell: Создай свой модуль MyCompany.Utils.psm1 и храни там функции для сброса паролей, очистки квот и выгрузки отчетов.

3. Сетевая топология — карта твоего мира
Самый быстрый способ найти проблему в сети — взглянуть на актуальную схему. Но рисовать её в Visio руками — это ад. В 2026-м мы используем Diagrams as Code.

Попробуй Mermaid.js: Ты просто пишешь текст, а Git-лаборатория или Obsidian рисуют схему:

graph TD
    User-->Internet
    Internet-->Firewall[pfsense]
    Firewall-->Switch(L3 Switch)
    Switch-->Server1[Proxmox Node 1]
    Switch-->Server2[Proxmox Node 2]
    Server1-->VM1[Nginx Proxy]

🚀 Пятничный совет «на миллион»:
Прежде чем уйти домой, проверь три вещи:

* Бэкапы: Зайди и посмотри глазами, что сегодняшний бэкап весит не 0 байт.

* Snapshot-ы: Удали старые снапшоты виртуалок. В понедельник они превратятся в «тормоза» дисковой подсистемы.

* Уведомления: Убедись, что телефон не в режиме «Не беспокоить» для критических алертов от Zabbix/Grafana.

Помни: Лучший сисадмин — это тот, чьего имени в компании не знают, потому что «всё просто работает».

Хороших выходных, коллеги! И пусть ваш uptime стремится к бесконечности. 📈☕

#friday #longread #sysadmin #lifehack #documentation #automation #admin_future #it_culture

🧠 Skill: Документация для «себя из будущего» (и почему Word — это зло) 📝

Давайте честно: админы ненавидят писать документацию. Обычно это вордовский файл `.docx`, щедро усыпанный скриншотами, который устаревает на следующий день после создания.

Но если ты ведешь несколько проектов, отсутствие нормальной документации — это гарантированное выгорание. Главный скилл сеньора — писать доки так, чтобы через год, разбуженный в 3 ночи, ты сам понял, что там наворотил.

3 правила нормальной IT-документации в 2026 году:

1. Никакого Word. Документация должна быть в Markdown (`.md`). Это текст, который легко искать, он весит килобайты, его можно хранить в Git вместе с конфигами.
2. Пиши «ПОЧЕМУ», а не только «КАК». Команду для поднятия туннеля ты нагуглишь за минуту. А вот *почему* ты пробросил именно порт 8443 и зачем отключил проверку сертификатов для этого конкретного шлюза — ты забудешь уже в пятницу. Фиксируй логику решений.
3. Docs as Code (Документация как код). Идеально — развернуть легковесную wiki (например, BookStack или Outline) и приучить себя: закрыл сложный тикет ➔ набросал заметку на 5 строчек с куском конфига.

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

#skills #documentation #sysadmin #mindset #devops #markdown #admin_future

🧠 Skill: «Фактор автобуса» (Bus Factor) — почему незаменимость это плохо

В админской среде есть опасное заблуждение: «Если только я знаю, как это работает, меня не уволят».
На самом деле, высокая «незаменимость» — это ловушка, которая мешает тебе расти, уходить в отпуск и получать бюджеты.

Техническая суть:
«Фактор автобуса» — это количество членов команды, которых должен переехать автобус, чтобы проект/инфраструктура встали колом. Если твой Bus Factor равен 1 (это ты) — у компании огромные риски, а у тебя — вечный стресс.

Как прокачать этот скилл:

1. Документация «для идиота»: Пиши инструкции так, чтобы твой сменщик мог поднять упавший сервис в 3 часа ночи без твоего звонка.

2.Infrastructure as Code (IaC): Твои знания должны быть зафиксированы в коде Ansible/Terraform, а не только в твоей голове.

3. Shared Secrets: Используй командные менеджеры паролей (Vault, Passbolt). Никаких личных блокнотов с паролями от рута.

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

#skills #management #career #documentation #sysadmin #mindset #admin_future

🧠 Skill: Doc-as-Code — почему твоя документация должна лежать в Git 📖

Старые Word-файлы с инструкциями и пыльные страницы в Wiki умирают в тот момент, когда их создали. В 2026 году админ использует подход Documentation as Code (DaC). Это значит, что документация пишется в Markdown, хранится в Git и живет рядом с кодом или конфигами.

Техническая суть:

1. Версионность: Ты всегда видишь, кто и когда изменил инструкцию по восстановлению бэкапа.
2. Peer Review: Ты можешь создать Pull Request с описанием новой схемы сети, а коллеги проверят его на ошибки.
3. Автоматизация: При пуше в Git документация может сама собираться в красивый статический сайт (через MkDocs или Hugo).

Простой пример Markdown-структуры:

```markdown
# Инструкция: Восстановление БД из бэкапа
## Шаги:
1. Зайти на сервер `db-backup-01`.
2. Выполнить команду: `cat backup.sql | psql database`.
> Важно: Перед этим проверьте наличие свободного места в `/var/lib/postgresql`.

```

Вывод: Навык работы с Markdown и Git-флоу для документации делает тебя системным инженером нового уровня, чьи знания не потеряются при сбое Wiki-сервера.

#skills #documentation #markdown #git #devops #sysadmin #admin_future

🚀 Skills: Твоя вторая память — Зачем админу личная Wiki

Понедельник — отличное время, чтобы навести порядок в голове. Самая большая ошибка админа — полагаться на свою память. Фраза «я это точно запомню» — самая большая ложь, которую мы себе говорим. Через полгода ты не вспомнишь, какой «костыль» применил для настройки того странного принтера.

Почему личная база знаний (Wiki) — это твой главный скилл:

1. Скорость решения: Ты не гуглишь проблему заново, а открываешь свою заметку, где уже есть готовый конфиг.
2. Спокойный отпуск: Если ты передаешь дела коллеге, тебе достаточно скинуть ссылку на документацию, а не висеть на телефоне.
3. Структура: Описывая решение в Markdown, ты сам лучше понимаешь, как оно работает.

Что использовать:

1. Obsidian или Logseq — для тех, кто любит локальные файлы и связи между заметками.
2. Notion или Wiki.js — если нужна командная работа и красивый интерфейс.
3. Обычные .md файлы в Git-репозитории — путь настоящего минималиста.

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

#skills #documentation #productivity #knowledgebase #markdown #admin_future

🧠 Skills: Ты единственный, кто знает как это работает. Поздравляю, ты создал себе тюрьму

Коллеги, давайте честно. У каждого из нас есть тот самый сервис, скрипт или конфиг, про который знает только один человек. Ты. И каждый раз, когда ты уходишь в отпуск — телефон не замолкает. Это не уважение к твоей экспертизе. Это Bus Factor = 1, и он убивает и команду, и тебя.

Я это называю "знаниевый монополизм". Он возникает не из жадности — он возникает из того, что некогда было написать документацию, некогда объяснить коллеге, некогда сделать нормальный runbook. И вот ты незаменим. Звучит как комплимент, пока не звонит телефон в 23:47 в субботу.

Хороший runbook — это не просто список шагов. Это живой документ с метаданными: кто владелец, когда последний раз тестировался, какой канал для эскалации, сколько времени займёт выполнение. Именно это отличает документ, который реально используют, от того, что пылится в Confluence с 2021 года.

Шаблон runbook, который реально работает:

---
title: Перезапуск кластера PostgreSQL при split-brain
id: RB-DB-003
version: 1.2.0
last_updated: 2026-04-15
last_tested: 2026-03-01
owner: @your_name
slack_channel: "#infra-oncall"
estimated_duration: 20-40 минут
risk_level: high
requires_approval: true (Роман или тимлид)
---

## Когда использовать
- Alert: "PostgreSQL replication lag > 300s"
- Alert: "Primary node unreachable"
- Симптом: приложение пишет ошибки "could not connect to server"

## Шаг 1 — Диагностика (5 мин)
Проверяем состояние кластера:
  $ patronictl -c /etc/patroni/config.yml list
Ожидаемый вывод: один Leader, остальные Replica

## Шаг 2 — Проверка репликации
  $ psql -h localhost -U postgres -c "SELECT * FROM pg_stat_replication;"
Если пусто на мастере — реплика отстала или отвалилась.

## Шаг 3 — Failover (только если мастер недоступен)
  $ patronictl -c /etc/patroni/config.yml failover --master <node> --candidate <replica>
ВНИМАНИЕ: действие необратимо без ручного вмешательства.

## Шаг 4 — Проверка после failover
  $ patronictl -c /etc/patroni/config.yml list
  $ psql -h <new_master> -U postgres -c "SELECT pg_is_in_recovery();"
Ожидаемый результат: false (мы на новом мастере)

## Контакты эскалации
- L2: @colleague_name (Telegram)
- L3: вендор поддержки (тикет в портале)

## История изменений
- 1.2.0 (2026-04-15): добавлен шаг проверки pg_stat_replication
- 1.1.0 (2026-02-01): обновлён путь конфига Patroni

Зачем это нужно:
Системы меняются, но документация часто — нет. Решение: триггеры на ревью runbook при изменении инфраструктуры. Когда меняется инфраструктурный код — автоматически флагируются связанные runbook-ы для обновления. Это не бюрократия. Это то, что позволяет тебе нормально спать в отпуске.

Итог: Незаменимых специалистов не бывает — бывают люди, которые не успели или не захотели передать знания. Runbook — это не слабость. Это признак зрелого инженера, который думает о команде, а не только о своей незаменимости.

#skills #documentation #runbook #sysadmin #teamwork #admin_future