Промпт от инженера Anthropic: как агент ведёт заметки о своей работе

Тарик Шихипар — инженер команды Claude Code в Anthropic — поделился промптом которым регулярно пользуется сам. Идея простая, но меняет то как вы контролируете агента во время длинных задач. За несколько часов промпт собрал больше 950 лайков и разошёлся по AI-сообществу.

Сам промпт

implement <SPEC> and while you do, keep a running implementation-notes.html file (or markdown) with decisions you had to make weren't in the spec, things you had to change, tradeoffs you had to make or anything else I should know

Просите агента реализовать спецификацию и одновременно вести файл implementation-notes.html — с заметками о решениях которых не было в спеке, изменениях и компромиссах на которые пришлось пойти.

Почему спецификации всегда неполные

Сколько бы детально вы ни описали задачу — всегда остаются неоднозначности. Агент сталкивается с ними в процессе и вынужден принимать решения самостоятельно. Обычно эти решения остаются невидимыми: вы получаете готовый результат, но не понимаете почему он именно такой.

Тарик описывает это так: как бы тщательно вы ни описали спецификацию, всегда всплывают непредвиденные нюансы. Этот подход даёт модели возможность принимать решения, но держит вас в курсе.

Вы не тормозите работу постоянными согласованиями — агент идёт вперёд, но фиксирует всё что отклонилось от исходного плана.

Что попадает в файл заметок

В расширенной версии промпта Тарик уточнил структуру. В файл должно попадать четыре типа информации:

Design decisions — решения принятые там где спека была неоднозначной. Агент выбрал один из вариантов и объясняет почему.

Deviations — места где агент намеренно отклонился от спеки. Не ошибка, а осознанное решение с обоснованием.

Tradeoffs — альтернативы которые рассматривались и почему выбрано то что выбрано. Это самое ценное — видно что агент думал о нескольких вариантах.

Open questions — вопросы которые агент хотел бы уточнить или пересмотреть. Место где агент честно говорит что не уверен.

Почему HTML а не Markdown

Тарик намеренно использует .html а не .md — хотя в промпте указал оба варианта на выбор. Это часть его более широкого подхода к работе с Claude Code.

HTML позволяет агенту создавать структурированный документ с таблицами, разделами и форматированием. Markdown остаётся плоским текстом. Если агент всё равно создаёт и редактирует файл, есть смысл использовать формат который выглядит и читается лучше.

Тарик говорит что полностью перестал редактировать Markdown-файлы вручную — просит Claude редактировать их. Если редактирует Claude, зачем оптимизировать формат под человеческое редактирование?

Как использовать на практике

Для коротких задач — достаточно одной сессии. Агент реализует спеку и ведёт заметки параллельно. В конце у вас есть результат и документ с объяснением всех неочевидных решений.

Для длинных задач в несколько сессий — файл заметок накапливается между сессиями. Вы всегда можете открыть его и понять на каком этапе находится реализация и что уже было решено. Тарик уточняет что обычно держит спеки достаточно сжатыми чтобы уложиться в один полный ответ ассистента.

Для командной работы — файл заметок становится артефактом который можно передать другому разработчику или приложить к PR. Он объясняет контекст решений без необходимости восстанавливать его из истории чата.

Для аудита и отладки — когда что-то пошло не так, заметки показывают в какой момент агент принял решение которое привело к проблеме. Это сокращает время на поиск причины.

Почему это особенно важно для агентных задач

Агенты в Claude Code сейчас могут работать часами. Стоимость одной сессии реальная. Когда что-то идёт не так на пятом часу работы — это дорого.

Тарик рассказывает об этом в своих воркшопах: агенты стоят реальных денег, когда что-то ломается далеко в процессе — это больно. Нужно оставаться в курсе без того чтобы постоянно нависать над агентом.

Этот промпт не останавливает агента на каждом шаге. Он создаёт trail который позволяет понять что происходило — и вмешаться в нужный момент, а не после того как всё сломалось.

Расширенная версия промпта

Тарик позже опубликовал более детальную версию:

Implement . As you work maintain a running implementation-notes.html file that captures anything I should know about how the implementation diverges from or interprets the spec, including: - Design decisions: choices you made where the spec was ambiguous - Deviations: places where you intentionally departed from the spec, and why - Tradeoffs: alternatives you considered and why you picked what you did - Open questions: anything you'd want me to confirm or revise

Эту версию удобно использовать как готовый шаблон — просто подставьте свою спецификацию вместо <SPEC>.