# Работа с этим репозиторием

Здесь описано состояние серверов: один файл на хост в `servers/`, стеки
docker-compose в `stacks/`, индекс в `AGENTS.md`.

## Главное правило

**Тронул сервер — обнови `servers/<хост>.md` в том же прогоне, до отчёта
пользователю.** Не «потом», не «если попросят». Расхождение описания с
фактом опаснее отсутствия описания: по доке принимают решения, и неверная
строка стоит дороже пустой.

Это относится к любому изменению состояния: поднял или погасил сервис,
поменял конфиг, удалил каталог, завёл ключ, отключил юнит. Если менял
что-то в `stacks/`, проверь, что описание сервиса в `servers/` ему не
противоречит.

## Перед тем как что-то описывать — проверь

Доке не верь, сверяй с живым сервером. При последней сверке (2026-09-08)
десяток утверждений в `servers/fr1.md` оказались неверными: версии,
размеры, «не работает» про то, что уже работало.

Подробный чеклист и метод — в скилле `server-audit`
(`.claude/skills/server-audit/`), инвентаризация одной командой —
`scripts/snapshot.sh <ssh-хост>`.

## Как писать

Стиль этого репо — не список фактов, а факт плюс причина и грабли:

- **Почему так, а не иначе.** «`node-exporter` в host-network» бесполезно
  без «иначе видел бы только сеть docker-бриджа».
- **Что сломается молча.** Помечай `⚠️`. Такие места — главная ценность
  файла: `ufw` не управляет docker-портами; путь монтирования обязан
  совпадать с абсолютными путями в БД; `HISTORY=7` у sysstat хранит неделю.
- **Дату и прежнее значение** при изменении: «поднято до 365 (было 7)».
- **Незакрытое — в «Открытые хвосты»**, а не в никуда. Если оставил
  токен, задачу или сомнительные права — запиши, иначе это потеряется.
- **Секретов здесь нет.** Токены, пароли, ключи — только на сервере.
  Ссылаться на путь к секрету можно, содержимое — нельзя.
- Роль хоста поменялась — поправь и строку в `AGENTS.md`.

## Чего не делать

- Не описывай планы как факт. «Планируется» и «сделано» — разные разделы.
- Не удаляй ⚠️-заметку, потому что «выглядит устаревшей». Сначала проверь
  на сервере, потом переписывай, указав дату проверки.
- Не коммить в `main` напрямую, если пользователь не просил.