project-maps/AGENTS.md

# project-maps — правила для ИИ-агентов

Автогенерируемые структурные карты всех репозиториев Gitea владельца `german`: на каждый репо — `MAP.md` (назначение, модули, маршруты, связи), сверху — сводный `INDEX.md` и межсервисный Mermaid-граф. Слой сейчас двухуровневый: структурный (греп-анализ, без LLM) плюс семантический (архитектура, dead-code, топ-функций через codebase-memory-mcp), см. `HANDOFF-lilia.md`. Агенты флота используют этот репо, чтобы быстро понять состав и связи любого проекта без клонирования и ручного грепа.

> Контекст флота — vault `german/fleet-vault` (`00-MOC/HOME.md`), правила работы с ним — `knowledge/skill-vault-workflow.md`. Здесь — только специфика этого репозитория.

## Структура — ключевые папки/файлы, куда класть новое

- `INDEX.md` — сводная таблица по всем репо (язык, LOC, модули, маршруты, связи) + межсервисный Mermaid-граф.
- `repos.json` — машиночитаемый реестр репозиториев-источников.
- `<repo>/MAP.md` — по одной папке на каждый закартированный репозиторий; в семантической фазе дополняется секциями `## Архитектура`, `## Тех-долг`, `## Ядро (топ-функций)` и снапшотом `graph.db.zst`.
- `HANDOFF-lilia.md` — протокол передачи задачи между структурным и семантическим агентом.

## Как пользоваться

**Содержимое автогенерируемое — руками `MAP.md`/`INDEX.md` не редактировать.** Любая правка вручную будет затёрта при следующей генерации. Если карта устарела или неверна — чинить генератор (скрипт греп-анализа / вызовы codebase-memory-mcp), а не сам файл. Для чтения — открывай `INDEX.md` для обзора, `<repo>/MAP.md` для деталей по конкретному проекту.

## Зона ответственности

Структурный слой ведёт агент-«песочница» (греп/Mermaid, без LLM-семантики); семантический слой (`get_architecture`, dead-code, cross-service links) — агент Лилия через codebase-memory-mcp, см. `HANDOFF-lilia.md`. Правило флота: один узел/заметку не пишут два агента одновременно — сверяйся с `owner_agent` и делай свежий `git pull` перед запуском генерации.

## Git-воркфлоу

- `git pull --rebase` до начала работы.
- После каждого атомарного изменения (перегенерация карт, добавление репо в реестр): `git add -A && git commit -m "<что/зачем>, agent=<имя>" && git push`.
- Коммитить мелко и часто — по репо или по логическому шагу генерации, не одним гигантским коммитом.
- В markdown-конфликтах сохранять обе правки.

## Что НЕ коммитить

Приватные ключи, токены, пароли, файлы `*.env` (кроме `*.env.example`). Секреты — на Я.Диске, в репозитории только ссылка на путь.

## Куда писать наработки

Скрипты генерации карт и вспомогательный код — сюда, в репозиторий. Решение/факт/грабля общего значения — заметкой в `fleet-vault/memory/` со ссылкой из нужного `00-MOC/*.md`. Копия знаний — Я.Диск `servaki.online\_vault-copy`.

## Связанное

- `fleet-vault` — общий vault флота, точка входа `00-MOC/HOME.md`.
- `agent-sync` — точка синхронизации хендоффов между структурным и семантическим агентом (см. `HANDOFF-lilia.md`).
- Все остальные репо `german/*` — источники данных для карт в этом репозитории.