Files

T

gilfanovrandClaude Opus 5 b56c137b5c Механизм поддержания описаний в актуальном состоянии

Сверка fr1 показала, что дока расходится с фактом по десятку пунктов —
значит нужен не разовый проход, а контракт и инструмент.

  CLAUDE.md — правило «тронул сервер, обнови servers/<хост>.md в том же
  прогоне» плюс стиль: факт + причина + что сломается молча. Лежит именно
  в CLAUDE.md, потому что AGENTS.md автоматически агенту не подгружается.

  .claude/skills/server-audit/ — метод сверки и накопленные грабли: где
  дока врёт чаще всего, почему ufw не отвечает на вопрос об открытых
  портах, почему нужен up -d --dry-run, почему «executed successfully»
  не доказывает работу задания.

  scripts/snapshot.sh — инвентаризация живого состояния за один проход:
  только чтение, без sudo, секретов не печатает, недоступное под root
  помечает и подсказывает команду.

Первый же прогон скрипта нашёл две вещи, обе описаны:

  - IPv6 не «починился», а мигает: за один день FAILED -> REACHABLE ->
    FAILED без единой правки конфига. Описан как мигающий, с выводом
    ничего на него не завязывать.
  - В основном sshd_config стоит PermitRootLogin yes (правка шаблона
    Contabo). Root-вход закрыт только потому, что Include дроп-инов
    стоит выше, а sshd берёт первое значение. Уберёшь дроп-ин —
    включится.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-08 16:52:22 +03:00

3.5 KiB

Raw Permalink Blame History

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

Здесь описано состояние серверов: один файл на хост в 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 напрямую, если пользователь не просил.