Lat.md: Граф знаний на основе Markdown для кодовых баз

Lat.md — это инструмент, который строит граф знаний для вашей кодовой базы с использованием markdown-файлов. Он решает проблему плохой масштабируемости AGENTS.md — по мере роста проектов поддержка единого плоского файла становится непрактичной, что приводит к скрытым архитектурным решениям, недокументированной бизнес-логике и галлюцинациям контекста у ИИ-агентов.

Как это работает

Вы сжимаете предметные знания в граф взаимосвязанных markdown-файлов, хранящихся в директории lat.md/ в корне вашего проекта. Разделы связываются друг с другом через [[вики-ссылки]] вроде [[file#Section#Subsection]], markdown-файлы связываются с кодом через [[src/auth.ts#validateToken]], а исходные файлы ссылаются обратно с помощью комментариев, таких как // @lat: [[section-id]] в TypeScript или # @lat: [[section-id]] в Python. Команда lat check обеспечивает ссылочную целостность.

Ключевые возможности

• Более быстрая разработка для агентов: Вместо поиска по коду через grep, агенты ищут в графе знаний, чтобы последовательно находить архитектурные решения, ограничения и контекст предметной области.
• Более быстрый рабочий процесс для людей: Агенты поддерживают lat-файлы; при проверке изменений начинайте с семантических изменений в lat.md/, чтобы понять, что изменилось и почему, делая код-ревью вторичным.
• Сохранение знаний: Агенты фиксируют контекст и логику из промптов в графе по мере работы, поэтому будущие сессии начинаются с полного контекста вместо его повторного обнаружения.
• Спецификации тестов с проверкой: Тестовые сценарии могут быть описаны в разделах lat.md/, помеченных require-code-mention: true. Каждая спецификация должна быть упомянута в комментарии // @lat: в тестовом коде, а lat check помечает любую спецификацию без обратной ссылки.

CLI-команды

• lat init: Настраивает популярные кодирующие агенты с хуками и инструкциями для поддержания lat-файлов в актуальном и корректном состоянии.
• lat check: Обеспечивает ссылочную целостность; агенты автоматически вызывают её перед завершением работы.
• lat search и lat section: Агенты используют их для понимания промптов и навигации по графу вместо бесконечных вызовов grep.
• lat locate: Находит разделы по имени (точному или приблизительному).
• lat refs: Находит, что ссылается на раздел.
• lat expand: Раскрывает [[ссылки]] в промпте для агентов.
• lat mcp: Запускает MCP-сервер для интеграции с редактором.

Установка и настройка

Установите с помощью npm install -g lat.md, затем выполните lat init в вашем репозитории, чтобы создать структуру директории lat.md/. Пишите markdown-файлы, описывающие архитектуру, бизнес-логику или спецификации тестов, и связывайте их по мере необходимости.

Для семантического поиска (lat search) требуется ключ API OpenAI (sk-...) или Vercel AI Gateway (vck_...). Ключ определяется в следующем порядке: переменная окружения LAT_LLM_KEY (прямое значение), переменная окружения LAT_LLM_KEY_FILE (путь к файлу с ключом), переменная окружения LAT_LLM_KEY_HELPER (shell-команда, выводящая ключ с таймаутом 10 секунд) или конфигурационный файл, сохранённый lat.