Как работать с Claude Code над проектом: 6 шагов до журнала решений

Что такое Claude Code?

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

Claude Code может пройти эту цепочку сам. Он ищет нужные файлы, читает их содержимое, вносит правки и запускает команды. Если проверка показывает ошибку, результат команды тоже попадает в контекст следующего действия.

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

Anthropic сначала выпустила Claude Code как инструмент командной строки для агентного программирования. В анонсе Anthropic его описывали так:

В анонсе Anthropic Claude Code описан как помощник, который ищет и читает код, редактирует файлы, пишет и запускает тесты, создаёт commit, отправляет код в GitHub и использует инструменты командной строки (источник).

Я бы держал в голове простую границу: Claude Code способен выполнять действия, но не отвечает за границы задачи вместо тебя. Чем точнее ограничение, тем меньше лишних изменений.

Зачем вести журнал решений, если Claude Code уже видит проект?

Я вижу это после первой сессии: вчера агент уже выяснил, где живёт авторизация, почему не подходит второй API-клиент и какой обработчик нельзя трогать. Сегодня открывается новая сессия. Приходится объяснять то же самое заново.

Anthropic пишет о такой причине:

Anthropic объясняет пользу постоянных файлов проекта тем, что без них в начале разговора приходится заново передавать архитектурные решения, требования к тестам и предпочтения к стилю кода (источник).

Для этого и нужен DECISIONS.md: подход к локальной памяти проекта разобран в отдельной инструкции. Файл хранит короткие записи о решениях, причинах и ограничениях. В него не стоит переносить каталог всех файлов или инструкцию на сотни строк.

Записывай туда четыре вещи:

• какое решение принято;
• почему выбран именно этот вариант;
• какой подход отвергнут;
• что нельзя менять без отдельного подтверждения.

Пример:

# Decisions

## Rules

- Не переписывать рабочие модули, если задача этого прямо не требует.
- Не заменять текущий auth-flow.
- Не менять схему базы данных без отдельного подтверждения.
- Не удалять существующие тесты.
- Выбирать самое маленькое изменение, которое закрывает задачу.

## Decisions

- Авторизация остаётся в `src/auth/`.
  Причина: текущий поток уже используется приложением и проверками.

- Используем существующий API-клиент.
  Отвергнутый вариант: добавить второй клиент для новой функции.
  Причина: он дублирует повторы запросов, обработку ошибок и настройки.

## Handoff

- Что изменено:
- Что проверено:
- Какое решение принято:
- Какие подходы отвергнуты:
- Следующий шаг:

Разделяй эти уровни: в CLAUDE.md лежат обзор проекта и общие правила, в DECISIONS.md собрана переносимая память о выборах и неудачных подходах. Процедуры, которые нужны только для конкретного workflow, лучше не добавлять в постоянный контекст.

Короткий файл полезнее энциклопедии. Каждая новая строка должна закрывать реальную повторяющуюся проблему. Если агент ни разу не сталкивался с ограничением, не добавляй его только на всякий случай.

Как Claude Code работает в терминале?

Запрос claude code cli означает тот же сценарий, только с акцентом на способ запуска. CLI - это программа, которой управляют через командную строку. Ты пишешь запрос в терминале, а агент отвечает там же и при необходимости вызывает команды.

Контекст сессии накапливается, а каждый прочитанный файл и вывод команды занимают место в доступном окне. Результат предыдущей команды остаётся частью разговора. Anthropic формулирует механику так:

Anthropic описывает сессию так: прочитанные файлы и вывод команд остаются частью разговора и снова учитываются на следующих ходах до конца сессии (источник).

Из этого следуют две команды.

• /clear очищает историю и начинает новую задачу. Используй её, когда переходишь к независимой работе.
• /compact сжимает разговор текущей задачи. История превращается в краткий пересказ, исходный текст при этом не сохраняется дословно.

Разница важна. /clear намеренно отделяет одну задачу от другой. /compact помогает продолжить ту же задачу с меньшим объёмом истории, но часть деталей может исчезнуть. Причина старого запрета или второстепенное предупреждение легко выпадет из краткого пересказа.

Я не считаю историю сессии журналом проекта. Она нужна для текущей работы. Решение, которое должно пережить новую сессию, записывай в файл.

Как работать с Claude Code над проектом?

Использование claude code лучше разбирать через короткую цепочку действий вместо большого промпта «собери приложение». На сессию выбери одну задачу. Для неё задай проверяемый этап и понятный критерий готовности.

1. Ограничь одну задачу.

   Назови конкретный результат: например, изменить текст кнопки на странице или добавить проверку к одному обработчику. Не смешивай в одной сессии дизайн, авторизацию, базу и деплой.

   Сформулируй границу прямо:

   Цель сессииСкопировать промпт

   Работай только над одной задачей: измени текст кнопки на странице оформления заказа.
   
   Не меняй структуру проекта, стили других страниц, обработку платежей и файлы, которые не нужны для этой правки.
   В конце покажи список изменённых файлов и результат проверки.

2. Попроси изучить нужные файлы.

   Сначала назови область поиска. Попроси не редактировать код до короткого отчёта о найденных файлах и текущей логике.

   • читать только файлы, связанные с этой задачей;

   • назвать найденный компонент или обработчик;

   • перечислить зависимости, которые могут затронуть правку;

   • не вносить изменения на этом шаге.

     Изучение перед правкойСкопировать промпт

     Сначала изучи только файлы, связанные с текстом кнопки на странице оформления заказа.
     
     Не редактируй файлы. Сначала сообщи:
     - какие файлы нашёл;
     - где находится нужный текст;
     - какие зависимости затрагивает изменение;
     - какие файлы менять не нужно.

3. Попроси план изменений.

   План должен быть коротким. В нём нужны файлы, действие и способ проверки. Если агент предлагает переписать большой модуль ради маленькой правки, на этом месте я останавливаюсь и сужаю задачу.

   План измененийСкопировать промпт

   Составь короткий план только для этой задачи.
   
   Для каждого шага укажи:
   - файл;
   - что именно изменится;
   - как проверить результат.
   
   Не предлагай рефакторинг, замену архитектуры или изменения за пределами задачи.
   Дождись моего подтверждения перед редактированием.

4. Выполни маленький этап.

   После плана разреши только перечисленные изменения. Не отдавай агенту право расширять задачу по ходу работы без нового согласования.

   Если список файлов изменился, попроси остановиться. Это простая граница, но она ловит большую часть самовольного расширения.

5. Проверь результат командой.

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

6. Обнови журнал решений.

   Перед завершением попроси добавить только новое: принятое решение, причину, отвергнутый вариант и следующий шаг. Не разрешай переписывать весь файл.

   Обновление журналаСкопировать промпт

   Обнови `DECISIONS.md` только добавлением фактов по текущей задаче.
   
   Запиши:
   - что изменено;
   - какое решение принято;
   - почему выбран этот вариант;
   - какой подход отвергнут и почему;
   - что проверено;
   - что делать следующим шагом.
   
   Не переписывай существующие записи и не удаляй решения.

Правило «одна заметная задача = одна сессия» не означает, что каждый клик требует нового окна. Речь о независимых целях. Когда задача закончена и проверена, новая функция или новый участок проекта лучше получают отдельную сессию.

Постоянные правила проекта храни в репозитории. Тогда файл доступен следующей сессии и остаётся видимым в истории изменений.

После этой сессии открой DECISIONS.md и внеси одну запись по шаблону выше.

Как Claude Code работает с GitHub?

Когда нужен claude code review, обычно хотят понять, можно ли поручить агенту не только написать правку, но и довести её до репозитория. Да, это можно поручить агенту, но я не отдаю ему commit вслепую. Claude Code работает с GitHub, создаёт commit и делает push.

Я делаю это в таком порядке:

1. Открой проект в его рабочей папке.
2. Попроси прочитать правила проекта и DECISIONS.md.
3. Ограничь список файлов для текущей задачи.
4. Дождись изменений и результата проверки.
5. Посмотри diff до правки.
6. Только после этого попроси создать commit и отправить код.

CLAUDE.md и связанные файлы проекта стоит проверять в Git. Это часть договорённостей проекта. Если файл не попал в репозиторий, следующая сессия или другой участник не получит ту же опору.

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

Что такое skills и зачем они нужны?

Запрос claude code skills появляется, когда один файл начинает разрастаться. В него складывают правила форматирования, инструкцию релиза, порядок проверки миграций, сценарий ревью и историю решений. Через некоторое время агент получает слишком много постоянного текста.

Здесь полезно разделить два слоя:

• CLAUDE.md - что это за проект, какие есть общие правила и какие ограничения действуют всегда;
• skills - что делать в конкретной процедуре, например при ревью или подготовке релиза.

Anthropic описывает границу коротко:

Anthropic рекомендует оставлять в CLAUDE.md постоянные инструкции, а workflow переносить в skills, которые подключаются при необходимости (источник).

DECISIONS.md тоже не стоит превращать в склад процедур. Его задача уже: сохранить выбор и причину. Чеклист действий относится к workflow. Обзор проекта и постоянные правила относятся к CLAUDE.md. История сессии не относится ни к одному из этих файлов целиком.

Я бы держал структуру так:

CLAUDE.md
DECISIONS.md
.claude/
  skills/

В CLAUDE.md достаточно указать, где лежит журнал решений и когда его читать. В самом журнале не нужно дублировать весь обзор проекта. Структура и проверка Skills разобраны в отдельной инструкции, а workflow не нужно загружать в каждую сессию, если текущая задача с ним не связана.

Что делать, если Claude Code забывает решения или снова переписывает рабочий код?

Длинная сессия увеличивает объём контекста, стоимость и шум. Старые файлы и вывод команд снова участвуют в следующих ходах. Когда история становится слишком большой, /compact заменяет её кратким пересказом. Это удобнее, чем упереться в предел контекста, но пересказ может потерять второстепенное решение.

Проблема выглядит так: три сессии назад агент предложил вариант, ты его отверг, а сегодня он снова предлагает почти то же самое. История событий может сохраниться частично. Структура рассуждений - почему вариант отвергнут и при каких условиях к нему нельзя возвращаться - уже потеряна.

Запись должна быть конкретной:

## Решения

- Авторизация остаётся в `src/auth/`.
  Причина: текущий поток уже используется приложением и проверками.
  Отвергнутый вариант: перенос авторизации в middleware.
  Запрет: не менять auth-flow без отдельного подтверждения.

## Запреты

- Не добавлять второй API-клиент.
  Причина: он дублирует повторы запросов, обработку ошибок и настройки.
  Отвергнутый вариант: отдельный клиент для новой функции.

- Не переписывать рабочий обработчик платежей ради унификации.
  Причина: текущая версия уже покрыта проверками.
  Запрет: сначала показать план и diff.

Если агент снова переписывает рабочий код, останови задачу и проверь границу изменений:

1. останови текущую задачу;
2. посмотри git diff;
3. сравни изменённые файлы со списком из плана;
4. вернись к последней рабочей версии через обычный Git-сценарий, который принят в проекте;
5. начни новую сессию с чтения DECISIONS.md;
6. повтори задачу с меньшим объёмом изменений.

Журнал не является техническим замком. Запись «не менять файл» может направить модель, но не гарантирует соблюдение. В issue #22055 описан отдельный bug report о сценарии, где правила permissions.ask не срабатывали для Edit и Write. Критические файлы нельзя защищать только записью в Markdown.

Минимальное правило на каждую сессию:

## Правило работы

- Одна заметная задача = одна сессия.
- Не просить «запомни» без записи в файл.
- Перед завершением задачи обновить `DECISIONS.md`.
- Не переписывать `DECISIONS.md` целиком без явного разрешения.
- Перед commit проверить diff.

Я бы не пытался сохранить в журнал всю переписку. Сохраняй только то, что пригодится следующей сессии: выбранный путь, причину, отказ от альтернативы, запрет и следующий шаг. Всё остальное пусть остаётся историей конкретной работы.

Вопросы и ответы