docs: AGENTS.md — памятка для ИИ-агентов, agent=laptop-agent

2026-08-03 06:45:18 +00:00
parent 4bfad7475f
commit 8337ab6b96
1 changed files with 41 additions and 0 deletions
@@ -0,0 +1,41 @@
+# 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/*` — источники данных для карт в этом репозитории.