Когда пишешь код в Cursor или Windsurf, часто сталкиваешься с тем, что AI не понимает структуру проекта или продолжает использовать устаревшие команды сборки. В итоге сгенерированный код просто не запускается.
Причина в том, что
README.md по сути пишется для людей. В нем полно контекста, который человек понимает автоматически, но для модели он расплывчат и неполон — там нет точных инструкций для выполнения.Недавно на GitHub я наткнулся на проект
AGENTS.md — это опенсорс, цель которого дать AI-программным агентам отдельную «инструкцию по эксплуатации».Идея в том, чтобы четко разделить гайд для людей (quickstart, описание логики), и набор машинных инструкций по сборке, запуску тестов и кодстайлу. Они не мешают друг другу.
Логика очень простая: в корне проекта создается Markdown-файл, который явно объясняет AI, как собирать проект, как его тестировать и каким правилам оформления кода следовать.
Подход совместим с большинством современных AI-инструментов для разработки — VS Code, Cursor, Windsurf, Aider, GitHub Copilot и др.
Порог входа минимальный: достаточно создать файл
AGENTS.md, вписать туда краткий обзор проекта, команды для тестов и важные замечания по безопасности.В больших проектах можно раскладывать такие файлы по разным поддиректориям. AI будет автоматически читать ближайший по пути конфиг, что делает схему довольно гибкой.
По мере того как AI-ассистенты становятся стандартным инструментом разработки, наличие отдельной «машинной документации» может стать базовым навыком для каждого разработчика. Лучше начать пробовать уже сейчас.
📁 Language: #TypeScript 94.3%
⭐️ Stars: 9.9k
➡️ Cсылка на GitHub
📱 @git_developer