architect/prospective/guidance-platform.md

type: standard
aspect: guidance
title: "Руководство по платформе"
version: 1.0.0
date: 2026-04-10
status: active
sources:
- guidance-fractal-architecture.md
- guidance-biz-it-boundary.md
- guidance-business-it-boundary.md
- guidance-biz-it-projects.md
- guidance-it-projects.md
- guidance-project-development-ai.md
- guidance-project-index.md
- guidance-agent-roles.md
- guidance-infra-bot.md

Руководство по платформе

Консолидированное руководство. Объединяет 9 guidance-документов в единый справочник.

Связанные документы:
- platform-architecture.md -- архитектура платформы, виды проектов, процессы
- document-system.md -- документная система
- filesystem.md -- файловая система

S1. ФРАКТАЛЬНАЯ АРХИТЕКТУРА

Концепция

Фрактальная архитектура -- рекурсивная структура проекта, где каждый уровень является микро-проектом с одинаковой структурой.

ПРОЕКТ = МОДУЛЬ = БЛОК = ПОКОЛЕНИЕ

Одна и та же структура на всех уровнях:
  CLAUDE.md + CACHE.yaml + planning/ + dev/ + testing/ + deploy/

Принцип рекурсии

ПРОЕКТ
  dev/
    МОДУЛЬ (микро-проект)
      dev/
        БЛОК (микро2-проект)
          dev/
            ПОКОЛЕНИЕ (микро3-проект)

Каждый уровень:
- Самодостаточен (можно разрабатывать независимо)
- Тестируем (имеет testing/)
- Деплоим (имеет deploy/ с результатом)
- Декомпозируем (имеет planning/ с описанием блоков)

Минимальная структура (любой уровень)

микро-проект/
├── CLAUDE.md          -- описание, метаданные, интерфейс
├── CACHE.yaml         -- входные данные, зависимости
│
├── planning/          -- планирование
│   ├── requirements.md   -- требования
│   ├── blocks.md         -- декомпозиция на под-блоки
│   └── criteria.md       -- критерии готовности
│
├── dev/               -- разработка
│   ├── [под-блоки]       -- рекурсия (микро-проекты)
│   └── [код]             -- или финальный код (атом)
│
├── testing/           -- тесты
│   ├── unit/
│   ├── integration/
│   └── criteria.md       -- результаты тестов
│
└── deploy/            -- результат (финальная сборка)
    ├── dist/             -- собранный продукт
    └── README.md         -- как использовать

Типы структур

Для CODE блока:

блок/
├── CLAUDE.md
├── CACHE.yaml
├── planning/
│   ├── requirements.md
│   ├── blocks.md      -- список функций/классов
│   └── criteria.md    -- coverage >80%, 0 bugs
├── dev/
│   ├── функция_1/     -- под-блок (если сложная)
│   ├── функция_2/
│   └── utils.py       -- вспомогательный код
├── testing/
│   ├── unit/
│   └── integration/
└── deploy/
    └── module.py      -- финальный модуль

Для DOCS блока:

блок/
├── CLAUDE.md
├── CACHE.yaml
├── planning/
│   ├── requirements.md    -- что документировать
│   ├── blocks.md          -- разделы документации
│   └── criteria.md        -- полнота, ясность
├── dev/
│   ├── раздел_1.md
│   └── диаграммы/
├── testing/
│   └── review.md          -- ревью документации
└── deploy/
    └── final.md           -- финальная документация

Для OPS блока:

блок/
├── CLAUDE.md
├── CACHE.yaml
├── planning/
│   ├── requirements.md    -- что автоматизировать
│   ├── blocks.md          -- шаги скрипта
│   └── criteria.md        -- надёжность, откат
├── dev/
│   ├── validation/
│   ├── backup/
│   └── cleanup/
├── testing/
│   ├── dry-run.sh         -- тест без изменений
│   └── rollback.sh        -- тест отката
└── deploy/
    └── script.sh          -- финальный скрипт

Рекурсивный цикл разработки

Фаза 1: ДЕКОМПОЗИЦИЯ (top-down)

Спускаемся вглубь, разбивая на всё более мелкие части.

1. ПРОЕКТ
   ├── Определить стадии (planning, dev, testing, deploy)
   ├── Для dev/ -- определить модули/компоненты

2. МОДУЛЬ (микро-проект)
   ├── CLAUDE.md -- описать модуль
   ├── CACHE.yaml -- входные данные
   ├── planning/ -- требования, блоки, критерии

3. БЛОК (микро2-проект)
   ├── То же, декомпозировать на ПОКОЛЕНИЯ

4. ПОКОЛЕНИЕ (микро3-проект, АТОМ)
   ├── planning/ -- требования, критерии
   └── dev/ -- КОД (атомарный уровень, влезает в контекст)

Критерий остановки: уровень влезает в контекст Claude (~300 строк кода).

Фаза 2: УТОЧНЕНИЕ (на каждом уровне)

# CLAUDE.md -- интерфейс уровня
block:
  name: "..."
  type: CODE|DOCS|OPS
  inputs: [...]     -- что требует
  outputs: [...]    -- что производит

# CACHE.yaml -- входные данные
dependencies: [...]
inputs: {...}
resolved: {...}

# planning/requirements.md -- требования
# planning/blocks.md -- декомпозиция
# planning/criteria.md -- критерии

Фаза 3: РЕАЛИЗАЦИЯ (bottom-up)

Поднимаемся снизу вверх, собирая результаты.

НАЧАТЬ С САМОГО ГЛУБОКОГО УРОВНЯ (атом):

Уровень N (атомарный):
  1. Загрузить контекст CLAUDE.md
  2. dev/ -- реализовать код
  3. testing/ -- написать и запустить тесты
  4. FAILED -- вернуться к dev/
  5. PASSED -- deploy/ собрать результат
  6. ПРОДУКТ УРОВНЯ N ГОТОВ

Уровень N-1 (использует результаты N):
  1. CACHE.yaml -- resolved += deploy/ уровня N
  2. dev/ -- интегрировать под-блоки
  3. testing/ -- тесты интеграции
  4. PASSED -- deploy/ собрать результат

Продолжать до КОРНЯ (проект).

Ключевой принцип: Уровень N не знает внутреннее устройство уровня N+1, только использует его deploy/.

Фаза 4: ИНТЕГРАЦИЯ и ВАЛИДАЦИЯ

ДЛЯ КАЖДОГО УРОВНЯ (снизу вверх):

1. СБОРКА deploy/ -- собрать результаты под-уровней
2. ТЕСТИРОВАНИЕ -- unit/ + integration/ + criteria.md
3. ВАЛИДАЦИЯ -- все тесты PASSED? критерии выполнены?
4. ФИКСАЦИЯ -- обновить CLAUDE.md (status: completed)
5. ПОДЪЁМ НА УРОВЕНЬ ВЫШЕ

Почему это работает

Принцип Результат
Полная декомпозиция Каждая часть влезает в контекст Claude
Уточнение параметров Нет неопределённости, всё зафиксировано
Тестирование на каждом уровне Ошибки найдены рано
Bottom-up сборка Каждый уровень использует протестированные компоненты
Изоляция Уровни независимы
Рекурсивная проверка Тесты на каждом уровне + интеграционные

Метрики качества

На каждом уровне:

metrics:
  planning:
    requirements_coverage: 100%
    blocks_defined: YES
    criteria_defined: YES
  development:
    code_size: < 500 строк (если атом)
    dependencies_resolved: 100%
  testing:
    unit_tests_passed: 100%
    integration_tests_passed: 100%
    criteria_met: 100%
  deployment:
    build_success: YES
    documentation: YES

На уровне проекта:

project_metrics:
  levels_total: 4
  levels_completed: 4
  atoms_total: 12
  atoms_passed: 12
  overall_coverage: 87%
  bugs_found: 0
  quality_score: A+

Workflow: от идеи до безупречного продукта

1. ИДЕЯ
2. ДЕКОМПОЗИЦИЯ -- до атомарного уровня
3. УТОЧНЕНИЕ -- CLAUDE.md, CACHE.yaml, planning/ на каждом уровне
4. РЕАЛИЗАЦИЯ (bottom-up) -- dev/ -> testing/ -> deploy/
5. ВАЛИДАЦИЯ -- тесты + критерии на каждом уровне
6. БЕЗУПРЕЧНЫЙ ПРОДУКТ

Инструменты

Инструмент Назначение
claude-loader.py Компиляция CLAUDE.md с кешем
fractal-init.py Создание фрактальной структуры (TODO)
fractal-validate.py Проверка полноты рекурсии (TODO)

S2. BIZ / IT ГРАНИЦА

Принцип

БИЗНЕС и IT -- ДВЕ РАЗНЫЕ МЕРНОСТИ

БИЗНЕС планирует ЧТО -> IT реализует КАК

Граница: REQUIREMENTS (требования от бизнеса к IT).
BIZ не лезет в код. IT не принимает решений по ассортименту и каналам.

Две иерархии

Бизнес-иерархия (ЗАЧЕМ, ЧТО, КТО):

@org-{name}/
  @biz-{name}/          -- коммерческое направление
    BRIEF.md             -- зачем
    CONCEPT.md           -- что
    REQUIREMENTS.md      -- требования к IT  <-- ГРАНИЦА

Ответственность: Маркетинг / Бизнес.

IT-иерархия (КАК, ЧЕМ, ГДЕ):

@org-{name}/
  @it-site-{domain}/    -- IT-реализация
    DESIGN.md            -- архитектура
    GUIDE.md             -- как делать
    README.md            -- как запустить
    LAUNCH.md            -- деплой

Ответственность: IT.

Цепочка переходов

BIZ пишет REQUIREMENTS.md
    | ГРАНИЦА 1: BIZ -> IT
IT получает требования -> пишет DESIGN.md
    | ГРАНИЦА 2: IT -> Кодер
Кодер получает DESIGN.md + GUIDE.md -> пишет код

BIZ -> IT:
1. BIZ заполняет REQUIREMENTS.md (что нужно от IT)
2. IT создаёт подпроект @it-{тип}-{имя}/
3. IT пишет DESIGN.md со ссылкой на BIZ/REQUIREMENTS.md
4. IT декомпозирует на модули -> GUIDE.md по каждому

IT -> Кодер:
1. IT создаёт specs/ с SPEC.yaml + CODE-PROMPT.md для каждого модуля
2. Кодер читает SPEC + CODE-PROMPT -> реализует код
3. Кодер отчитывается по критериям готовности

Структура документов

BIZ (требования):

@biz-{name}/
├── BRIEF.md            -- зачем проект, для кого
├── CONCEPT.md          -- что делаем, ценность
├── REQUIREMENTS.md     -- что нужно от IT (функционал, контент, метрики)
└── ANALYTICS.md        -- KPI, отчёты (опционально)

IT (реализация):

@it-site-{domain}/
├── DESIGN.md           -- архитектура (ссылка на BIZ/REQUIREMENTS.md)
├── GUIDE.md            -- как делать (или GUIDE-{тема}.md)
├── README.md           -- как запустить
├── LAUNCH.md           -- деплой
└── specs/              -- ТЗ для кодера
    └── {модуль}/
        ├── SPEC.yaml        -- конфигурация, зависимости
        └── CODE-PROMPT.md   -- задача кодеру

Разделение ответственности

Кто Пишет Формат
BIZ BRIEF.md, CONCEPT.md, REQUIREMENTS.md Markdown
IT DESIGN.md, GUIDE.md, specs/ Markdown + YAML
Кодер Код в implementation/ PHP / JS / Python

Границы

Кто Что НЕ делает
BIZ НЕ пишет технические решения (платформа, стек)
BIZ НЕ создаёт specs для кодера
IT НЕ определяет цели канала, ЦА, контент-стратегию
Кодер НЕ решает что реализовывать (получает specs)

Обязательные связи

  1. IT/DESIGN.md обязательно ссылается на @biz-.../REQUIREMENTS.md
  2. specs/CODE-PROMPT.md обязательно ссылается на DESIGN.md
  3. specs/SPEC.yaml содержит version и dependencies

Форматы ключевых документов

BRIEF.md (BIZ):

# BRIEF -- {Название}

**Зачем:** {цель проекта, бизнес-задача}
**Для кого:** {целевая аудитория}
**Контекст:** {предпосылки, текущая ситуация}

## Метрики успеха
- KPI 1: значение
- KPI 2: значение

REQUIREMENTS.md (BIZ -> IT):

# REQUIREMENTS

## Функциональные
- [ ] Требование 1
- [ ] Требование 2

## Контентные
- [ ] Тексты для категорий

## Технические ограничения
- Скорость < 2 сек
- Uptime > 99%

DESIGN.md (IT):

# DESIGN

## Входящие требования
[REQUIREMENTS.md](../@biz-.../REQUIREMENTS.md)

## Платформа
{платформа, версия}

## Модули
| Модуль | Назначение | Зависимости |
|--------|-----------|-------------|

SPEC.yaml (IT -> Кодер):

module: {name}
type: {тип: drupal-module / cscart-addon / django-app}
version: 1.0.0
dependencies:
  {платформа}: ^{версия}
features:
  - feature1
  - feature2

CODE-PROMPT.md (IT -> Кодер):

# Модуль: {название}

## Контекст
[ссылки на REQUIREMENTS и DESIGN]

## Задача
{что создать}

## Требования
{детальный список с алгоритмами}

## Структура кода
{файлы и что в каждом}

## Критерии готовности
- [ ] критерий 1
- [ ] тесты

Чеклисты

BIZ:
- [ ] BRIEF.md заполнен (зачем, для кого)
- [ ] REQUIREMENTS.md содержит конкретные требования (не общие слова)
- [ ] Метрики указаны (конверсия, скорость, uptime)

IT:
- [ ] DESIGN.md ссылается на BIZ/REQUIREMENTS.md
- [ ] specs/ созданы для каждого модуля
- [ ] SPEC.yaml содержит version, dependencies, features
- [ ] CODE-PROMPT.md содержит структуру кода, тесты, критерии готовности

Связи:
- [ ] DESIGN.md -> REQUIREMENTS.md (ссылка работает)
- [ ] CODE-PROMPT.md -> DESIGN.md (ссылка работает)

S3. IT-ПРОЕКТЫ

Три состояния проекта

ZERO        VANILLA         WORKING         PRODUCTION
Установка   Голый дистр     Версии v0.x     Релиз v1.0+
из коробки  v0.0.0          с изменениями   в проде
НЕ работает ОТКАТ точка    git tags        боевой

Два пути создания проекта

PATH A: Создание с нуля
Zero -> Vanilla (v0.0.0) -> Working (v0.1.0+) -> Production (v1.0.0+)

PATH B: Онбординг существующего
Получение -> Онбординг (v1.0.0) -> Working (v1.1.0+)

Версионирование

Формат: MAJOR.MINOR.PATCH (v1.2.3)

PATH A:

v0.0.0 = Vanilla (чистый дистрибутив)
v0.1.0 = Первая фича
v0.x.x = Разработка (не в проде)
v1.0.0 = Релиз в production

PATH B:

Если есть версия -- сохранить (v2.3.1 -> v2.3.2)
Если нет версии  -- v1.0.0 (онбординг завершён)

Что менять:
- MAJOR (1.0.0 -> 2.0.0): Breaking changes
- MINOR (1.0.0 -> 1.1.0): Новая фича
- PATCH (1.0.0 -> 1.0.1): Баг-фикс

Принцип отката

ЗАПРЕЩЕНО:
- Править ядро (core) системы
- Чинить сломанное на месте
- Накручивать workarounds

ПРАВИЛЬНО:
- Откатиться к предыдущей рабочей версии
- Продолжить с чистого состояния
- Искать где именно поломка

1. ПЕРЕД изменением -- backup (контрольная точка)
2. ДЕЛАТЬ изменение -- одно за раз
3. ЕСЛИ сломалось -- СТОП! Откат
4. НИКОГДА не менять ядро CMS

Принцип записи

Обязательно после каждой операции:
1. DEVLOG.md -- что сделано, что работает
2. Git commit -- зафиксировать изменения
3. Git tag -- поставить версию (v0.x.x)

## [v0.2.0] 2026-02-13 14:30

СДЕЛАНО:
- Установлен модуль dru_lider_catalog
- Включены базовые блоки

РАБОТАЕТ:
- /admin/modules -- модуль active
- /admin/structure/block -- блоки видны

ОТКАТ:
git checkout v0.1.0

Принцип атомарности

ОДИН ШАГ = ОДНА ПРОВЕРКА

НЕПРАВИЛЬНО:
1. Установить 5 модулей -> 2. Изменить конфиг -> 3. Деплой -> 4. Проверить всё

ПРАВИЛЬНО:
1. Установить модуль 1 -> проверка -> git commit
2. Установить модуль 2 -> проверка -> git commit
3. Изменить конфиг -> проверка -> git commit

Принцип безопасных изменений

Правило READ-MODIFY-WRITE для удалённых серверов:

1. READ:   cat конфиг > backup.conf
2. MODIFY: vim конфиг (локально)
3. TEST:   nginx -t (проверка синтаксиса)
4. WRITE:  загрузить на сервер
5. CHECK:  nginx -t && service nginx reload
6. VERIFY: curl http://site.ru

Для БД:

1. READ:   mysqldump db > backup.sql
2. MODIFY: создать миграцию
3. TEST:   проверить на локальной копии БД
4. WRITE:  применить миграцию на prod
5. CHECK:  проверить результат
6. VERIFY: проверить работу сайта

Быстрая справка

Действие Команда
Контрольная точка tar -czf vanilla-$(date +%Y%m%d).tar.gz project/
Откат к Vanilla tar -xzf vanilla-YYYYMMDD.tar.gz
Создать версию git tag v0.1.0 && git push --tags
Проверка nginx nginx -t
Backup БД mysqldump db_name > backup-$(date +%Y%m%d).sql

S4. РАЗРАБОТКА С AI

Зачем

При росте проекта AI теряет контекст -- путается в зависимостях, держит в голове лишнее.
Решение: разбивать работу на независимые контекстблоки, каждый из которых помещается в контекст за один сеанс.

Четыре измерения проекта

1. СТАДИИ (Stages)         -- этапы жизненного цикла
2. БЛОКИ (Blocks)          -- единицы работы (контекстблоки)
3. ПОКОЛЕНИЯ (Generations) -- версии одного блока
4. ВОЛНЫ (Waves)           -- релизы продукта

Стадии

Стадия -- этап жизненного цикла. Это структура проекта, не единица работы.

planning -> infra -> install -> setup -> dev -> testing -> deploy -> monitor -> maint
Стадия Назначение
planning Roadmap, требования
infra Сервер, домены, БД
install Установка платформы
setup Конфиги, переменные окружения
dev Разработка (блоки)
testing Unit, e2e, интеграционные тесты
deploy CI/CD, staging -> production
monitor Логи, алерты, метрики
maint Обслуживание, очистка

Блоки (контекстблоки)

Блок = квант работы, помещающийся в контекст AI за один сеанс.

Критерий Значение
Размер 150-300 строк кода / 200-400 строк docs
Автономность Работает независимо
Тестируемость Тестируется изолированно
Полнота Решает одну законченную задачу

Типы блоков:

Тип Что Примеры
CODE Код приложения API, UI компоненты, скрипты
DOCS Документация концепция, руководство
OPS Операции деплой, бэкап, миграции
DESIGN Архитектура схемы, модели данных
TEST Тесты unit, e2e, интеграция
CONTENT Контент тексты, данные

Логическое vs Физическое:

Сначала описать логически. Физическую папку создавать только если блок >300 строк.

# Малый блок (< 300 строк) -- логически в CLAUDE.md стадии:
dev/
├── CLAUDE.md       -- описывает блоки filters, search
└── catalog.py      -- код всех блоков в одном файле

# Большой блок (> 300 строк) -- физическая папка:
dev/
├── CLAUDE.md
└── import/
    ├── CLAUDE.md   -- описание блока
    ├── CACHE.yaml  -- входные данные / зависимости
    └── lib/        -- результаты (код)

Структура физического блока:

блок/
├── CLAUDE.md      -- ЧТО ЭТО (описание, метаданные, поколения)
├── CACHE.yaml     -- ВХОД (зависимости, параметры, кешированные данные)
└── [результаты]   -- ВЫХОД
    ├── lib/       -- код
    ├── tests/     -- тесты
    └── README.md  -- документация

Поколения

Поколение = версия одного блока (v1, v2, v3...).
Применять если блок > 300 строк -- разбить на инкрементальные части.

Принципы:
- Каждое поколение добавляет функциональность к предыдущему
- Каждое поколение помещается в контекст (~300-500 строк)
- Каждое поколение можно задеплоить отдельно

Схема в YAML (в CLAUDE.md блока):

block:
  name: import
  type: CODE
  status: in_progress
  current_version: v2

generations:
  v1:
    description: "MVP: базовый парсинг CSV"
    size: 300 строк
    deliverables: [парсинг, базовая категоризация]
    status: deployed
  v2:
    description: "Модульная lib/ архитектура"
    size: 400 строк
    deliverables: [lib/parser, lib/mapper, lib/loader]
    status: in_progress
    depends_on: [v1]

Физическая организация:

import/
├── CLAUDE.md       -- описание всех поколений
├── lib/            -- текущее поколение (v2)
│   ├── parser.py
│   └── loader.py
└── arh/
    └── v1/         -- архив v1
        └── import.py

Волны

Волна = версия всего продукта в определённый момент (набор блоков x поколений).

Волна /= Поколение:
  Поколение -- версия одного блока  (import v1, v2, v3)
  Волна     -- версия всего проекта (Product 1.0, 2.0, 3.0)

Схема в ROADMAP.md:

waves:
  v1.0:
    name: "MVP"
    status: deployed
    blocks:
      import: v1
      infra: v1
  v2.0:
    name: "Каталог"
    status: in_progress
    blocks:
      import: v3
      catalog: v1
      seo: v1

Иерархия CLAUDE.md

CLAUDE.md (workspace)
    |
projects/org/CLAUDE.md
    |
projects/org/{name}/CLAUDE.md     -- L3: проект (стратегия)
    |
{name}/dev/CLAUDE.md              -- L4: стадия (блоки стадии)
    |
{name}/dev/import/CLAUDE.md       -- L5: блок (поколения, кеш)

Что содержит CLAUDE.md блока:

---
block:
  name: import
  type: CODE
  status: in_progress
  current_version: v2

cache:
  db_config: "host=localhost, db=lideravto"
  api_url: "https://api.bazon.ru/v2"

generations:
  v1: { status: deployed, date: 2026-01 }
  v2: { status: in_progress, date: 2026-02 }
---

Алгоритм работы с блоком

1. Определить стадию: dev / testing / ...
2. Определить блок: import / catalog / ...
3. Определить поколение: v1 / v2 / ...
4. Загрузить контекст: CLAUDE.md + CACHE.yaml
5. Реализовать поколение: в рамках блока
6. Проверить: размер <= 300 строк? тесты проходят?
7. Обновить статус в CLAUDE.md
8. Зафиксировать (git commit)

Чеклисты

Создание нового блока:
- [ ] Определить тип (CODE/DOCS/OPS/DESIGN/TEST)
- [ ] Оценить размер
- [ ] Если > 300 строк -- спланировать поколения
- [ ] Создать CLAUDE.md с метаданными
- [ ] Создать CACHE.yaml с зависимостями
- [ ] Добавить блок в CLAUDE.md стадии

Реализация поколения:
- [ ] Прочитать CLAUDE.md блока и родительской стадии
- [ ] Прочитать CACHE.yaml
- [ ] Реализовать только то, что в deliverables этого поколения
- [ ] Написать тесты
- [ ] Обновить статус в CLAUDE.md
- [ ] Коммит: feat({блок}): {поколение} - {описание}

Релиз волны:
- [ ] Все блоки волны в статусе deployed
- [ ] Тесты прошли
- [ ] ROADMAP.md обновлён
- [ ] Версия зафиксирована тегом (git tag vX.Y.Z)

S5. INDEX.md -- НАВИГАЦИЯ ПО СТАНДАРТАМ ПРОЕКТА

С чего начать

Вопрос Файл
Что такое проект? Структура файлов PROJECT_STANDARD.md
Какой тип проекта у меня? PROJECT_TYPOLOGY.md
Какие файлы нужны для моего типа? PROJECT_DOCUMENTS.md

По задаче

Задача Файл
Создать новый проект с нуля PROJECT_BOOTSTRAP.md
Назвать проект / папку / модуль PROJECT_NAMING.md
Вести проект: стадии, переходы, LOG PROJECT_PROCESSES.md
Разрабатывать IT-проект (git, стеки) PROJECT_STANDARD_IT.md
Вести BIZ-направление PROJECT_STANDARD_BIZ.md
Разделить BIZ и IT PROJECT_BIZ_IT.md
Работать с AI: блоки, поколения, волны PROJECT_DEVELOPMENT_AI.md

Справочники

Файл Что внутри
PROJECT_TYPOLOGY.md Дерево типов: org/biz/it/ops/hr/fin/mkt/rd/phys
PROJECT_DOCUMENTS.md Матрица: тип -> обязательные файлы
PROJECT_PROCESSES.md S11 Статусы артефактов: draft/dev/test/prod/archive
PROJECT_BIZ_IT_GUIDE.md Детальные переходы BIZ->IT->Кодер, примеры

Карта зависимостей

PROJECT_STANDARD       -- базовые правила (читать первым)
    |
PROJECT_TYPOLOGY       -- какой тип?
    |
PROJECT_DOCUMENTS      -- какие файлы?
    |
PROJECT_PROCESSES      -- как вести?
    |
PROJECT_BOOTSTRAP      -- как создать / санировать?

PROJECT_STANDARD_IT    -- расширение для IT
PROJECT_STANDARD_BIZ   -- расширение для BIZ
    |
PROJECT_BIZ_IT         -- граница BIZ <-> IT
PROJECT_BIZ_IT_GUIDE   -- детальный гайд

PROJECT_NAMING         -- именование (в любой момент)
PROJECT_DEVELOPMENT_AI -- разработка с AI (в любой момент)

S6. РОЛИ И АГЕНТЫ

Базовое описание Роль vs Агент вынесено в platform-architecture.md S2.
Ниже -- дополнительные детали, не вошедшие в основной стандарт.

Как различать в разговоре

"переключись в режим Архитектор"   -- роль
"запусти агент coder-agent"        -- агент
"запусти архитектора"              -- неясно (уточнять!)

Как различать в логах

# Роль (диалог с человеком):
[2026-03-27 10:00] роль=Архитектор сессия=abc123: обновил PLATFORM.md

# Агент (автономно):
[2026-03-27 10:00] агент=architect-agent задача=task-042: обновил PLATFORM.md

В конфигах (schedule.yaml)

# Агент -- можно ставить в cron:
schedule:
  - cron: "0 3 * * *"
    agent: infra-agent      # правильно

# Роль -- нельзя ставить в cron (нет человека):
schedule:
  - agent: Архитектор       # НЕПРАВИЛЬНО, роль не процесс

Связанные документы

S7. ИНФРА-БОТ

Назначение

Telegram бот для безопасного управления сервером через мобильный телефон.
Принцип: Бот может делать только БЕЗОПАСНЫЕ операции. Опасные -- ТОЛЬКО через SSH.

Матрица безопасности

Каждая операция классифицируется по 3 параметрам:

1. Уровень риска:

Уровень Критерий Подтверждение Пример
L0 SAFE Не влияет на production Нет Чтение статуса, tmp cleanup
L1 MEDIUM Удаляет неиспользуемые данные Да (кнопка) Docker prune, старые venv
L2 DANGER Влияет на production Двойное Volumes, БД, конфиги
L3 FORBIDDEN Может сломать систему ЗАПРЕЩЕНО БОТУ rm -rf, DROP, useradd

2. Обратимость:

Категория Можно откатить? Разрешено боту?
Обратимые Да (перезапуск, recreate) L0-L1
Частично обратимые Да, но сложно (из бэкапа) Только L1 с предупреждением
Необратимые Нет (потеря данных) ЗАПРЕЩЕНО

3. Влияние на доступность:

Категория Влияет на работу? Разрешено боту?
Нулевое Сервисы работают L0
Временное Restart (секунды) L1
Длительное Downtime минуты ЗАПРЕЩЕНО
Критическое Может не восстановиться ЗАПРЕЩЕНО

Команды бота

L0: Мониторинг (всегда доступно):

/status          -- общий статус (диск, память, CPU, сервисы)
/disk            -- детали использования диска
/memory          -- детали использования памяти
/services        -- статус systemd сервисов
/docker          -- статус Docker контейнеров
/logs <service>  -- последние 20 строк лога
/uptime          -- время работы сервера
/who             -- кто залогинен
/help            -- список команд

L0: Автоматическая очистка (при disk >= 90%):
- Автоматически запускает cleanup-L0.sh
- Очищает: /tmp (>7 дней), apt/pip/npm cache, Docker dangling, journald
- БЕЗ уведомления если успешно
- С уведомлением если не помогло

L1: Интерактивная очистка (при disk >= 95%):
- Отправляет интерактивное меню с кнопками
- Опции: Docker images, Snapd, старые бэкапы, старые venv/node_modules, Git gc
- Выбор нескольких опций + кнопка "Выполнить"

L1: Управление сервисами:

/restart nginx   -- перезапуск (только белый список: nginx, postgresql, redis, docker)

Архитектура

Telegram
    |
InfraBot (system/bots/infra/)
    |
CommandHandler (белый список команд)
    |
ActionExecutor (выполнение с таймаутом)
    |
ResponseFormatter (форматирование ответа)

Безопасность:

Уровень Защита
Аутентификация Только разрешённые chat_id из конфига
Белый список Только команды из белого списка
Таймаут Любая команда -- максимум 30 секунд
Логирование Все команды логируются
Подтверждение L1 операции требуют подтверждения
Rate limit Max 10 команд в минуту

Конфигурация

# system/config/telegram.yaml
bots:
  infra:
    token: "..."
    username: "infra_bot"
    allowed_users:
      - 1318367261       # operator
    allowed_services:
      - nginx
      - postgresql
      - redis
      - docker
    rate_limit:
      max_commands: 10
      per_seconds: 60
    timeouts:
      command: 30
      cleanup: 300

Сценарии

Рутинная проверка: /status -> статус диска, памяти, CPU, сервисов.

Автоочистка (90%): Monitor обнаружил 91% -> автоматически cleanup-L0.sh -> освободил 3%. Если не помогло -- уведомление.

Интерактивная очистка (95%): Monitor обнаружил 95% -> меню с кнопками -> выбрал опции -> кнопка "Выполнить" -> отчёт (до/после, освобождено).

Критическая (98%): Уведомление "Подключись через SSH, запусти cleanup-L2.sh".

Развёртывание

# 1. Создать бота: @BotFather -> /newbot
# 2. Узнать chat_id:
python3 library/connectors/api/telegram/client.py infra
# 3. Запустить:
sudo systemctl start infra-bot
sudo systemctl enable infra-bot

Эволюция

Добавить новую команду:
1. Добавить в белый список: system/bots/infra/commands.py
2. Реализовать handler: system/bots/infra/handlers/
3. Обновить help и документацию

Добавить сервис: отредактировать allowed_services в telegram.yaml.

Логирование

/var/log/infra-bot/commands.log

2025-12-30 14:23:45 | chat_id=1318367261 | cmd=/status | result=ok | time=0.5s
2025-12-30 14:24:10 | chat_id=1318367261 | cmd=/cleanup L1 | options=[1,5] | result=ok | time=45s | freed=8.5GB
2025-12-30 14:26:15 | chat_id=9999999999 | cmd=/status | result=DENIED | reason=unauthorized

Интеграция

Вывод: Бот для рутинных задач, SSH для сложных.

СВЯЗАННЫЕ ДОКУМЕНТЫ

Документ Назначение
platform-architecture.md Архитектура платформы, проекты, процессы
document-system.md Документная система
filesystem.md Файловая система

Статус: active 1.0.0
Дата: 2026-04-10