Именование — это тоже промпт
Агент читает ваш код как контекст. Переменная `data2` и функция `process()` говорят ему ровно столько же, сколько вам, — то есть ничего.
Кодовый агент не знает вашей системы. Всё, что у него есть, — это текст файлов, которые попали в контекст. Имена в этом тексте несут больше смысла, чем комментарии: их гораздо больше и они встречаются в каждом обращении.
Отсюда наблюдение, которое я долго не формулировал: в проектах с честным именованием агенты работают заметно лучше, и это не совпадение с «в хороших проектах всё лучше».
Механика прямая. Функция calculateRefundAmount задаёт агенту предметную
область, тип результата и границу ответственности — три факта из одной
строки. process() не задаёт ничего, и агенту приходится восстанавливать
смысл из тела функции, тратя контекст и ошибаясь.
Особенно дорого обходятся имена, которые врут. Переменная userId,
в которой лежит адрес электронной почты, собьёт агента надёжнее, чем
отсутствие имени вообще: он не станет читать тело, потому что имя
выглядит однозначным. Человека, кстати, тоже собьёт — просто человек
чаще спотыкается и идёт проверять.
То же касается структуры файлов. Модуль, лежащий не там, где его ищут, не попадёт в контекст, и агент напишет второй такой же рядом.
Вывод, который мне нравится своей неромантичностью: подготовка проекта к работе с агентами — это не установка инструментов и не написание правил. Это те же вещи, которые делают код понятным человеку, просто теперь у них появился второй бенефициар и измеримый эффект.