Agent-friendly документация для npm-пакетов
7 марта я написал в Reddit-подтред Codex вопрос о том, есть ли уже устоявшиеся практики, как объяснять агентам, каким образом нужно использовать пакет: Maven, Composer, npm и другие.
Ответов по сути не было. По крайней мере, у меня сложилось впечатление, что в этой области пока нет общепринятой практики. Поэтому пришлось вместе с GPT-чатиком собирать свой вариант с нуля.
В качестве эксперимента я оформил для @teqfw/di компактный агентский интерфейс в виде
ai/AGENTS.md и набора коротких тематических файлов. Идея простая: README.md
остаётся для людей, а AGENTS.md и соседние документы дают агенту концентрированный контекст
о том, как именно использовать пакет.
Исходный Reddit-пост: Agent-friendly documentation for npm packages. Результат эксперимента в репозитории: teqfw/di: ai/AGENTS.md.
В итоге в документации для di получилось шесть файлов и 4,164K токенов, включая индексный
AGENTS.md. Документ можно было бы сделать и одним файлом, но я сознательно разбил его по
темам, чтобы агенту было проще читать контекст по шагам.
Пока это выглядит как рабочий паттерн: маленький входной файл, дальше - чтение по маршруту и только потом углубление в детали. Буду смотреть, насколько такая схема окажется устойчивой на практике.