AGENTS.md — 60-flows

Назначение уровня

Раздел описывает систему как построено (current, as-built), сверено с кодом. Целевой дизайн — в ../30-services/ и ../10-business/scenarios/; не смешивать. Здесь фиксируются реальные точки входа, реальные пути выполнения и реальные символы кода (file:line) на момент проверки.

Содержание

60-flows/
├── AGENTS.md              # ← вы здесь
├── README.md              # человеческий вход: что это, как читать
├── entry-points.md        # сквозная карта точек входа во все слои
├── 10-ingestion/
│   └── README.md          # обзор слоя ingestion (as-built)
└── 20-analogs/
    └── README.md          # сквозной конвейер подбора аналогов (as-built)

Ключевые концепции уровня

• As-built — описание того, что реально исполняется в текущем коде, а не того, что запланировано или задумано. Каждый факт снабжён ссылкой на символ и файл.
• Точка входа (entry point) — место, откуда управление впервые попадает в систему извне или по расписанию: HTTP-хендлер, Kafka-consumer, тикер, CLI-команда, boot-процесс.
• Сверено на commit — маркер в шапке файла, фиксирующий, на каком коммите проверялись факты. Если код изменился после этого коммита, факт может устареть — сверяйте перед использованием.

Когда смотреть сюда

• Нужно понять, что реально происходит в коде прямо сейчас, а не что задумано в target-дизайне.
• Нужна отправная точка для трассировки конкретного потока выполнения (например, «как Russvet долетает до БД»).
• Готовите impact-анализ или дебаг и хотите начать с проверенной карты точек входа, а не с догадок.

Когда НЕ смотреть сюда

• Нужен целевой дизайн сервисной границы → ../30-services/<service>/README.md.
• Нужны бизнес-правила и доменные сценарии → ../10-business/scenarios/.
• Нужна схема БД/Kafka/API → ../20-architecture/schemas/.
• Нужен runbook эксплуатации → ../40-operations/.

Связано

• README.md
• entry-points.md
• 10-ingestion/README.md
• ../AGENTS.md — корневой индекс
• ../30-services/ingestion/AGENTS.md — целевая сервисная граница ingestion (не путать с этим разделом)

Соглашения

• Каждый файл раздела начинается с маркера «Статус: current (as-built), сверено на commit <hash>».
• Факты подтверждаются ссылкой на код в формате Символ — путь/к/файлу.go:строка. Без такой ссылки факт в этот раздел не попадает.
• Если факт устарел (код изменился), документ обновляется, а не дублируется новой версией.
• Новые use-case файлы добавляются под соответствующий слой (10-ingestion/, далее по мере разбора других слоёв) и обязательно регистрируются в entry-points.md и в README слоя.