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/* — источники данных для карт в этом репозитории.