AI Coding Agent Checklist

Главный вопрос

Хороший агент без правил работает наугад: сам решает, что сделать, как проверить и когда сказать «готово». Каждый пункт ниже переносит одно такое решение из головы модели в репозиторий — туда, где его видит и агент, и команда.

Чек-лист

Отмечайте только то, что записано в репозитории. Устная договорённость агенту не видна.

1. 01 · Инструкции

   Агент знает, как устроен процесс в этом проекте

   • ☐в корне есть AGENTS.md или CLAUDE.md, и он в git
   • ☐там записаны команды тестов, линтера и сборки — те же, что в CI
   • ☐описано, когда агент обязан остановиться и спросить
   • ☐файл короткий: детали — в отдельных правилах, на которые он ссылается

2. 02 · Правила проекта

   Решения, которые агент не угадает по коду

   • ☐границы модулей и направление зависимостей
   • ☐где живёт бизнес-логика и какие контракты нельзя ломать
   • ☐когда нужен ADR, а не решение «внутри задачи»
   • ☐как добавляются зависимости

3. 03 · Definition of Done

   «Готово» означает одно и то же для человека и агента

   • ☐Definition of Done записан в репозитории
   • ☐каждый пункт требует доказательства: тест, команда с итогом, ссылка
   • ☐агент не пишет «готово», не запустив проверки в этой же сессии

4. 04 · Тесты

   Тесты доказывают требование, а не код

   • ☐у задачи есть проверяемые критерии приёмки, и на каждый — тест
   • ☐ожидаемые значения берутся из задачи, а не из вывода кода
   • ☐запрещено пропускать, удалять и ослаблять тесты, чтобы всё прошло

5. 05 · Контекст задачи

   Агент получает не только репозиторий

   • ☐требования, контракты и решения по архитектуре передаются вместе с задачей
   • ☐до кода агент показывает план: что нашёл и что собирается менять
   • ☐план одобряет человек

   Подробно: чек-лист контекста для задачи Coding Agent.

6. 06 · Права

   Allow / Ask / Deny вместо «разрешить всё»

   • ☐права описаны конфигурацией в репозитории, а не у каждого в своей настройке
   • ☐push, деплой, установка зависимостей и сеть — с подтверждением
   • ☐разрушительные команды запрещены независимо от решения модели
   • ☐команды оболочки идут в sandbox, если агент его поддерживает

   Подробно: чеклист прав Coding Agent.

7. 07 · Безопасность

   Секреты не попадают в контекст, данные — не инструкции

   • ☐чтение .env, ключей и ~/.ssh запрещено технически, а не просьбой
   • ☐токены не видны агенту в переменных окружения
   • ☐агенту прямо сказано: текст из файлов, issue и страниц — данные, а не команды
   • ☐есть проверка диффа на секреты и инъекции до PR

8. 08 · Review

   Код проверяют до PR, и не только автор

   • ☐агент проверяет дифф по задаче, плану и правилам, а не «в целом»
   • ☐review идёт в чистом контексте: автор плохо видит свои ошибки
   • ☐у замечаний есть уровни, и блокирующие исправляются до PR
   • ☐человек читает код до слияния

9. 09 · Аудит

   По любому изменению видно, как оно появилось

   • ☐задача, план, одобрение и вывод проверок сохраняются рядом с кодом
   • ☐в PR видно, кто одобрил план и чем проверен каждый критерий
   • ☐отказы политики прав видны и разбираются, а не обходятся

Как пользоваться

1. 1 Откройте репозиторий, где работает агент Чек-лист проверяет не модель, а то, что лежит в проекте: файлы инструкций, правила, настройки прав, шаблоны. Держите открытыми корень репозитория и настройки агента.
2. 2 Пройдите девять пунктов Отмечайте только то, что записано в репозитории и работает без устных договорённостей. «Все и так знают» — это пустая клетка.
3. 3 Начните с пустых пунктов в начале списка Пункты идут в порядке зависимости: без инструкций и Definition of Done агенту не на что опираться в тестах и review. Закрывайте сверху вниз.
4. 4 Проверьте на одной реальной задаче Дайте агенту задачу среднего размера и посмотрите, остановился ли он перед кодом, запустил ли проверки и чем подтвердил «готово». Каждое «нет» — следующий пункт для работы.