Skip to content

AGENTS.md

Latest commit

 

History

History
205 lines (157 loc) · 16 KB

AGENTS.md

File metadata and controls

205 lines (157 loc) · 16 KB
Raw

AGENTS.md

Памятка для AI-агентов и инженеров, работающих в этом репозитории.

Интеграция с IDE (IntelliJ IDEA)

Предполагается, что параллельно запущен экземпляр IntelliJ IDEA с открытым этим проектом, в котором настроена MCP-интеграция, публикующая возможности IDE в виде инструментов. Агент обязан использовать эти IDE-инструменты как основной способ работы с lsFusion-кодом — поиск, правка и инспекции идут через них.

Интеграция опознаётся по набору предоставляемых инструментов — lsfusion_find_elements, инструмент правки файлов (apply_patch либо replace_text_in_file, см. ниже), create_new_file, get_file_problems — а не по имени MCP-сервера. Имя сервера / префикс пространства имён может отличаться от установки к установке; стабильны именно имена инструментов. Везде в этом документе (включая RUN-SERVER.md) инструменты указаны без префикса сервера — использовать тот подключённый MCP-сервер, который их предоставляет.

Справочник по lsFusion

Для справки по языку и парадигме lsFusion использовать инструменты IDE-интеграции lsfusion_retrieve_docs и lsfusion_get_guidance. Вызов lsfusion_get_guidance к тому же обязателен перед работой с .lsf — см. раздел ниже.

Конвенции репозитория

  • Источник правды для lsFusion-кода: */src/main/lsfusion. Файлы в out/production — генерируемые, править нельзя.

Обязательный вызов lsfusion_get_guidance перед работой с .lsf

lsfusion_get_guidance (как и lsfusion_retrieve_docs) предоставляется тем же IDEA MCP-сервером, что и инструменты из раздела «Интеграция с IDE».

Перед первой за сессию операцией с .lsf-файлом (поиск, чтение, анализ или правка) агент обязан один раз вызвать lsfusion_get_guidance и далее применять полученные правила. Без него даже просто корректно прочитать lsFusion-код почти невозможно — тонкости (трёхзначная логика, семантика сессий, конвенции именования) из самого кода не выводятся. Повторный вызов в той же сессии не нужен.

Если инструмент помечен как deferred — сначала подгрузить его схему через ToolSearch.

Приоритетные инструменты

Для любой работы с .lsf-кодом предпочитать эти три инструмента генерическим аналогам.

1. lsfusion_find_elements — поиск и анализ lsFusion-кода

  • Предпочитать его Grep / Glob для любого семантического поиска классов, свойств, действий, форм, модулей и метакода. Он понимает пространства имён, сигнатуры, раскрытие метакода и граф использований — текстовый поиск этого не умеет.
  • Grep использовать только для не-lsFusion-файлов или поиска буквального текста.
  • Замечание: читает in-memory индекс IDEA. См. раздел Устаревание индекса.

2. Инструмент правки — правка .lsf-файлов

Имя инструмента правки зависит от версии IDE: в 2026.2 это apply_patch (принимает формат Codex *** Begin Patch / *** Update File: и unified diff), в более ранних сборках — replace_text_in_file. Использовать тот, который есть в наборе. Для новых файлов — create_new_file.

  • Предпочитать их Edit / Write Claude Code. Инструмент правки пишет через собственный VFS IDEA, поэтому изменение сразу видно lsfusion_find_elements и остальным IDE-инструментам.
  • Правки через Edit / Write внешние по отношению к IDEA — индекс от них отстаёт (см. Устаревание индекса).
  • При использовании apply_patch в IDE версии 2026.2 Перед правкой открывать файл open_file_in_editor.
  • apply_patch по закрытому файлу пишет его напрямую и заменяет все переносы строк на LF; если файл был в CRLF (основная часть репозитория), весь файл попадёт в дифф как изменённый. По открытому файлу правка идёт через документ IDEA и переносы строк сохраняются.

3. get_file_problems — проверка после каждой правки

После каждой правки вызывать get_file_problems на каждом изменённом файле.

  • Запускает инспекции IntelliJ с полным семантическим анализом lsFusion — ловит синтаксические ошибки и неразрешённые ссылки (например, Property or action '…' not found), сообщает severity и строку/колонку.
  • Всегда актуален: отражает внешние правки немедленно, без оговорки про отставание индекса.
  • Оговорка: разрешение символов между файлами всё равно идёт через индекс, поэтому сразу после добавления символа в другом файле ссылка на него может ненадолго ложно показываться как «not found».
  • Оговорка: на свёрнутом метакоде (@metaName(args); без раскрытого тела) get_file_problems может выдавать ошибки на код, который метакод сгенерирует. Это ожидаемо — не разворачивать метакод ради «чистого» отчёта; см. раздел «Свёрнутый метакод в коммитах .lsf».

Стандартный рабочий процесс

  1. Найти — lsfusion_find_elements: локализовать целевые элементы и понять контекст.
  2. Править — инструмент правки (open_file_in_editor + apply_patch или replace_text_in_file) / create_new_file (не Edit / Write).
  3. Проверить — get_file_problems на каждом изменённом файле; исправить все сообщённые ошибки.

Устаревание индекса

lsfusion_find_elements читает in-memory индекс IDEA. Правки, сделанные вне IDEA (Edit / Write Claude Code или любой не-IDE-инструмент), не отражаются, пока IDEA не обновит VFS — задержка от секунд до десятков секунд (обновление при фокусе окна / «Synchronize files on frame activation»).

Правка инструментом IDE снимает это полностью: индекс актуален в момент возврата вызова. Это и есть главная причина, по которой он приоритетный.

Если файл был изменён через Edit / Write — не доверять первому результату lsfusion_find_elements: подождать и повторить запрос либо попросить пользователя сфокусировать окно IDEA.

Чего не делать

  • Не использовать MCP-инструменты, публикуемые claude.ai (имена с префиксом mcp__claude_ai_*) — работать через IDE-интеграцию, описанную выше.
  • Не использовать Grep / Edit / Write для .lsf-кода там, где применимы инструменты выше.

Свёрнутый метакод в коммитах .lsf

В коммит должны попадать только свёрнутые обращения к метакоду — одна строка вида @metaName(arg1, arg2, ...);. Развёрнутая форма (когда плагин lsFusion в IDEA «расклеил» тело метакода в исходник) в репозиторий идти не должна: она дублирует сгенерированный код, ломает дальнейшие правки шаблона и засоряет diff.

Признак раскрытого метакода — фигурная скобка { сразу после @metaName(args) (вместо ;). По синтаксису lsFusion корректный вызов метакода — это всегда @metaName(args); без блока; форма @metaName(args){ … } появляется только когда плагин IDEA вставил тело метакода в исходник.

При обнаружении @name(args){ — не коммитить. Сообщить пользователю с указанием файла и попросить выполнить в IDEA Hide Meta for File (или Reenable meta, если плагин не схлопнул автоматически). Прямого MCP-инструмента для сворачивания метакода нет — действие доступно только из плагина lsFusion в IDEA.

Никогда не разворачивать метакод самостоятельно ради правок «пары строк внутри». Если нужно изменить то, что генерируется, — менять сам META-шаблон, а не его раскрытый результат.

Обратная связь (lsfusion_report_feedback)

Тот же MCP-сервер предоставляет lsfusion_report_feedback — отправку обезличенного сигнала о качестве документации, правил и инструментов.

Правило: если по ходу работы накопилось, что отправлять, — отправлять feedback всегда, без согласования с пользователем. Этот раздел и есть заранее выданное согласие: отдельно спрашивать разрешение на каждую отправку не нужно. Не решать за пользователя, что находка «мелкая», и не пропускать отправку из-за того, что он занят другим.

Поводом считать, в частности:

  • lsfusion_retrieve_docs не нашёл ответа или выдал нерелевантное по вопросу, который в документации быть должен;
  • документация или правила lsfusion_get_guidance разошлись с фактическим поведением платформы (проверенным на запуске службы или через /eval);
  • правило из guidance оказалось неточным, неполным или приводящим к ошибке;
  • инструмент IDE-интеграции повёл себя не так, как описано (ложные ошибки, пустой результат, расхождение с индексом);
  • в процессе выяснился неочевидный факт о платформе, которого в документации нет и который стоил заметного времени.

Как отправлять:

  1. Отправлять в конце задачи, одним вызовом на находку, не прерывая ради этого основную работу.
  2. В отчёте пользователю упомянуть одной строкой, что было отправлено, — чтобы он мог поправить формулировку или попросить не отправлять такое впредь.
  3. Содержимое отправки держать обезличенным: суть проблемы с платформой, документацией или инструментом — без бизнес-данных, учётных данных, имён клиентов и фрагментов прикладного кода. Это ограничение самого инструмента, и предварительное согласие его не снимает.
  4. Если пользователь в конкретном случае просит не отправлять — не отправлять.

Сопутствующие подпроекты

Если рядом с erp присутствует подпроект custom-logics (то есть файл ../custom-logics/AGENTS.md доступен на чтение) — прочитать его и применять описанные там правила в дополнение к этому файлу. Если такого подпроекта нет (стандартный случай открытой erp) — пропустить, всё необходимое уже здесь.

Проверка результата правок .lsf: только запуск службы

В lsFusion успешная компиляция модуля не гарантирует корректность кода — критерий «задача решена» для .lsf — это успешный запуск службы. Процедура запуска, источники лога, маркеры StartLogger и трактовка исходов вынесены в отдельный файл — RUN-SERVER.md. Читать его только по необходимости, когда нужно проверить результат правок .lsf, но до первого запуска службы в сессии.

Redmine (support.luxsoft.by)

Работа с внутренним Redmine (чтение задач, поиск, вложения, комментарии, перевод статусов) описана в отдельном файле — REDMINE.md. Читать его только по необходимости, когда задача действительно требует обращения к Redmine по ссылке или номеру задачи, но до первого обращения к Redmine в сессии.