Як писати документацію для ШІ-агентів: поради від українського розробника

Автор ·

Кирило Сулімовський, український керівник розробки, проаналізував, як ШІ-агенти, зокрема Claude Code, Codex, Gemini CLI та Cursor, взаємодіють із документацією. Виявилося, що хоча вони читають файли CLAUDE.md та AGENTS.md, це не завжди призводить до виконання інструкцій.

Основні висновки дослідження

Сулімовський опублікував відео на YouTube, де поділився результатами дослідження, проведеного науковцями Пекінського університету, яке охоплювало 557 сесій із coding-агентами та понад 33 000 pull request'ів. З'ясувалося, що:

  • Агенти звертаються до документації у 33% випадків.
  • 1328 читань документів призвели лише до трьох редагувань коду.
  • Зміни в документації часто впливають на подальшу роботу агентів.

Сулімовський рекомендує:

  • Не ховати критичні вимоги за посиланнями.
  • Зробити інструкції максимально конкретними.
  • Включати автоматичну перевірку, якщо це можливо.

Проблеми з документацією

Дослідження показало, що агенти рідко переходять за посиланнями між документами. Тому важливо, щоб усі необхідні інструкції були доступні в одному місці. Наприклад, замість загальної інструкції про API, краще вказати конкретні дії.

При troubleshooting агенти лише в 5% випадків зверталися до документації, частіше вони намагалися виправити помилки самостійно. Сулімовський радить включати основні кроки для діагностики безпосередньо в інструкції.

Редагування документації

ШІ-агенти активно редагують документацію, зміни були в 41,5% випадків. Це означає, що агенти можуть отримувати нові правила як частину контексту в наступних сесіях. Тому важливо перевіряти зміни в CLAUDE.md та AGENTS.md, оскільки вони можуть впливати на поведінку агентів.

Раніше dev.ua також розглядав дослідження, яке виявило проблеми в документації, зокрема наявність застарілих або суперечливих інструкцій, що можуть погіршувати роботу ШІ-агентів.

Джерело: dev.ua (https://dev.ua/news/yak-propysuvaty-dokumenty-dlia-shi-1789032585)