AGENTS.md — корневой индекс проекта

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

Корневая точка входа для AI-агентов, работающих с этим проектом. Даёт общую карту документации и направляет в нужный слой в зависимости от задачи.

Содержимое

docs/
├── AGENTS.md              # ← вы здесь
├── README.md              # вход для человека: обзор проекта
├── GLOSSARY.md            # глоссарий доменных терминов
│
├── 00-overview/           # vision, high-level concept, roadmap, open questions
├── 10-business/           # доменная модель, бизнес-правила, сценарии (Business Layer)
├── 20-architecture/       # ADR, схемы БД/ES/Kafka/API, архитектурные паттерны
├── 30-services/           # README.md на каждый сервис/модуль/коннектор
├── 40-operations/         # эксплуатация, runbooks, observability, rate limits
└── 50-processes/          # стандарты документации, contributing, runbook подключения поставщика

Ключевые понятия этого уровня

Эти понятия нужно знать до погружения в любой слой:

Canonical Product — наша единая нормализованная единица товара. См. GLOSSARY.md.
Supplier Offer — нормализованное предложение поставщика. См. GLOSSARY.md.
Identity Profile — шаблон критических характеристик, определяющий идентичность. См. 10-business/product-identity.md.
Connector — модуль, подключающий конкретного поставщика к ядру. См. 30-services/ingestion/connectors/AGENTS.md.

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

Обращайся к корневому AGENTS.md, когда:

начинаешь новую задачу и не знаешь, в каком слое лежит ответ;
нужна общая ориентация по структуре проекта;
ищешь глоссарий или стандарт документации.

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

НЕ ищи здесь:

конкретные таблицы БД → 20-architecture/schemas/postgres/
как работает сервис X → 30-services/<X>/AGENTS.md
как добавить нового поставщика → 50-processes/adding-new-supplier.md
формулировки бизнес-правил → 10-business/

Навигация по типовым задачам

Задача	Куда идти
Понять доменное понятие	`GLOSSARY.md` → `10-business/ubiquitous-language.md`
Понять, почему принято архитектурное решение	`20-architecture/adr/`
Добавить нового поставщика	`50-processes/adding-new-supplier.md`
Посмотреть схему БД	`20-architecture/schemas/postgres/`
Поменять маппинг ES	`20-architecture/schemas/elasticsearch/`
Понять, что делает конкретный сервис	`30-services/<name>/README.md`
Понять формат Kafka-событий	`20-architecture/schemas/events/`
Изменить бизнес-правило ценообразования	`10-business/contexts/pricing.md` + соответствующий сервис

Связано

README.md (для человека, не для AI)
GLOSSARY.md
50-processes/documentation-standard.md — формальные требования к документации

Конвенции

Все AGENTS.md следуют единому шаблону (см. 50-processes/documentation-standard.md, §2.2).
Все ссылки относительные от корня docs/.
Предпочтение — искать AGENTS.md перед чтением кода.

Tracium

Разделы