--- title: "Agent-friendly документация для npm-пакетов" description: "Разобрал Reddit-дискуссию и собственный эксперимент с `ai/AGENTS.md` для @teqfw/di: как дать агенту компактный, но полезный контекст по пакету." date: 2026-03-07 display_date: "7 марта 2026" image: "/img/blog/2026/20260307-01-photo-2026-03-07-13-13-51.jpg" image_alt: "Agent-friendly документация для npm-пакетов" --- # 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](https://www.reddit.com/r/codex/comments/1rmdaxp/agentfriendly_documentation_for_npm_packages_how/). Результат эксперимента в репозитории: [teqfw/di: ai/AGENTS.md](https://github.com/teqfw/di/blob/2.0.3/ai/AGENTS.md). В итоге в документации для `di` получилось шесть файлов и 4,164K токенов, включая индексный `AGENTS.md`. Документ можно было бы сделать и одним файлом, но я сознательно разбил его по темам, чтобы агенту было проще читать контекст по шагам. Пока это выглядит как рабочий паттерн: маленький входной файл, дальше - чтение по маршруту и только потом углубление в детали. Буду смотреть, насколько такая схема окажется устойчивой на практике.