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

> Claude Code работает с файлами проекта прямо из терминала: читает код, вносит изменения, запускает проверки и работает с Git. Показываю, как сохранить решения между сессиями через DECISIONS.md.

Источник: https://vibeceh.ru/guides/claude-code-zhurnal-resheniy-dlya-proekta
Автор: Сергей Мазур · опубликовано 2026-08-19

Claude Code - агент для работы с проектом в терминале. Он читает файлы, меняет их, запускает команды и проверки, работает с Git и GitHub. Проблема начинается после первой сессии: история заканчивается или сжимается, а причина старого решения исчезает. Поэтому проекту нужен короткий журнал решений.

## Что такое Claude Code?

этот `claude code гайд` рассматривает Claude Code как агентный инструмент в терминале. Он получает доступ к файлам проекта, читает код, редактирует файлы, запускает тесты и команды, а также работает с Git, включая commit и push в GitHub. В отличие от обычного чата, он не ждёт, пока ты вручную принесёшь каждый фрагмент: сам собирает контекст и действует в рабочей папке.

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

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

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

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

В анонсе Anthropic Claude Code описан как помощник, который ищет и читает код, редактирует файлы, пишет и запускает тесты, создаёт commit, отправляет код в GitHub и использует инструменты командной строки ([источник](https://www.anthropic.com/news/claude-3-7-sonnet?__from__=talkingdev)).

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

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

Claude Code видит текущие файлы и историю активной сессии, но это не равно памяти о причинах решений. Между сессиями и после `/compact` часть деталей может не попасть в пересказ, включая объяснение, почему выбран один подход и отвергнут другой. Короткий `DECISIONS.md` переносит через границу сессий решения, причины, запреты и неудачные варианты без превращения проекта в архив переписки.

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

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

Anthropic объясняет пользу постоянных файлов проекта тем, что без них в начале разговора приходится заново передавать архитектурные решения, требования к тестам и предпочтения к стилю кода ([источник](https://claude.com/blog/using-claude-md-files)).

Для этого и нужен `DECISIONS.md`: подход к локальной памяти проекта разобран в [отдельной инструкции](/guides/mcp-memory-pamyat-proekta-dlya-claude-code). Файл хранит короткие записи о решениях, причинах и ограничениях. В него не стоит переносить каталог всех файлов или инструкцию на сотни строк.

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

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

Пример:

```md
# Decisions

## Rules

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

## Decisions

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

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

## Handoff

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

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

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

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

терминал - это окно, где ты вводишь команды и видишь их результат. Claude Code запускается там как CLI, читает файлы в рабочей папке и переносит в контекст содержимое файлов, вывод команд и результаты предыдущих действий. `/clear` начинает новую задачу, а `/compact` сжимает старую историю, поэтому после compact детали могут пропасть.

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

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

Anthropic описывает сессию так: прочитанные файлы и вывод команд остаются частью разговора и снова учитываются на следующих ходах до конца сессии ([источник](https://claude.com/blog/maximizing-the-value-of-your-claude-code-sessions)).

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

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

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

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

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

раздели работу на одну заметную задачу, сначала попроси Claude Code изучить нужные файлы, затем получить план, выполнить небольшой этап и показать результат проверки. После каждого принятого решения обновляй `DECISIONS.md`. Такой порядок уменьшает область изменений и не заставляет новую сессию восстанавливать архитектуру по памяти.

![Кот смотрит на три карточки с этапами работы Claude Code.](https://s3.regru.cloud/crossmark/statejnik/images/guides/claude-code-zhurnal-resheniy-dlya-proekta/kadr-1.webp)

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

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

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

   

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

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

   

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

   

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

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

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

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

   

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

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

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

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

Claude Code может читать проект, менять файлы, запускать проверки, создавать commit и отправлять код в GitHub. Это не отменяет ручного контроля: перед фиксацией изменений проверь diff и убедись, что в commit попала только текущая задача. `CLAUDE.md`, `DECISIONS.md` и другие правила проекта храни в репозитории вместе с кодом.

![Собака проверяет карточку diff перед commit и отправкой кода.](https://s3.regru.cloud/crossmark/statejnik/images/guides/claude-code-zhurnal-resheniy-dlya-proekta/kadr-2.webp)

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

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

1. Открой проект в его рабочей папке.
2. Попроси прочитать правила проекта и `DECISIONS.md`.
3. Ограничь список файлов для текущей задачи.
4. Дождись изменений и результата проверки.
5. Посмотри [diff до правки](/guides/claude-code-prosit-agenta-pokazat-diff-do-pravki).
6. Только после этого попроси создать commit и отправить код.

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

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

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

skills отделяют процедуры от постоянных правил проекта. `CLAUDE.md` хранит обзор, общие требования и границы, а в начале сессии у skills загружаются имя и описание; полная инструкция загружается при вызове. Такое разделение сохраняет постоянный контекст коротким и не смешивает архитектурные решения с чеклистом конкретной операции.

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

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

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

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

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

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

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

```text
CLAUDE.md
DECISIONS.md
.claude/
  skills/
```

В `CLAUDE.md` достаточно указать, где лежит журнал решений и когда его читать. В самом журнале не нужно дублировать весь обзор проекта. Структура и проверка Skills разобраны в [отдельной инструкции](/guides/skills-v-claude-code-upakovat-komandnye-standarty), а workflow не нужно загружать в каждую сессию, если текущая задача с ним не связана.

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

не пытайся лечить потерю решений просьбой «запомни это». После важного выбора запиши решение, причину, отвергнутый вариант и запрет в `DECISIONS.md`, затем проверь diff и историю Git. Журнал направляет агента, но не блокирует Edit и Write технически, поэтому для критичных файлов нужны отдельные разрешения и механические проверки.

![Мужчина закрывает лицо ладонью рядом с журналом решений и git diff.](https://s3.regru.cloud/crossmark/statejnik/images/guides/claude-code-zhurnal-resheniy-dlya-proekta/kadr-3.webp)

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

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

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

```md
## Решения

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

## Запреты

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

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

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

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

Журнал не является техническим замком. Запись «не менять файл» может направить модель, но не гарантирует соблюдение. В issue [#22055](https://github.com/anthropics/claude-code/issues/22055) описан отдельный bug report о сценарии, где правила `permissions.ask` не срабатывали для `Edit` и `Write`. Критические файлы нельзя защищать только записью в Markdown.

`DECISIONS.md` объясняет намерение и сохраняет причины, но не останавливает действие инструмента. Перед commit проверяй diff, держи рабочие изменения обратимыми и не отдавай агенту широкое разрешение на переписывание проекта.

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

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

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

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

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

Начни с одной небольшой задачи в существующем проекте. Попроси Claude Code сначала изучить связанные файлы, затем показать план, после этого разреши правку и потребуй вывод проверки. В конце запиши решение и результат в `DECISIONS.md`. Не начинай с команды «собери всё приложение»: у такой задачи нет узкой границы и простого критерия готовности.

Если нужна claude code инструкция с нуля, учитывай: статья предполагает проект с файлами и терминал, из которого запускается Claude Code. Для первой сессии выбери изменение, результат которого легко проверить. Попроси агента назвать файлы, которые он собирается читать и менять, и не разрешай расширять список без нового согласования. Установку, вход и системные требования я здесь не расписываю: подтверждённых шагов для них нет в фактуре статьи.

Опиши цель, границы, разрешённые файлы и критерий готовности. Добавь запрет на рефакторинг, если он не нужен для задачи. Хороший prompt просит сначала изучить проект, затем показать план, потом выполнить один этап и вывести результат проверки. Формулировка «сделай красиво» слишком широкая: по ней агент сам выбирает область работы и способ проверки.

Для управления историей сессии здесь нужны две команды. `/clear` начинает новую задачу и отделяет её от старой истории. `/compact` сжимает историю текущей задачи и заменяет её кратким пересказом, поэтому часть деталей может потеряться. Полный список CLI-команд в этой инструкции не приводится: подтверждённые факты здесь есть только для терминала, `/clear` и `/compact`.

Поручай задачи с небольшой областью и проверяемым результатом: прочитать связанные файлы, изменить конкретный компонент, запустить проверку, показать diff, записать принятое решение. Большую работу разбивай на этапы. Не отдавай одной командой неопределённую задачу вроде «перепиши проект лучше»: агент может выбрать слишком широкий объём изменений.

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

Не считай текстовую запись в `DECISIONS.md` техническим ограничением. В отдельных сценариях правила разрешений для `Edit` и `Write` могли не срабатывать. Для критичных файлов проверяй diff, используй принятую в проекте схему Git-контроля и отдельно проверяй, что запрос подтверждения действительно появился. Журнал объясняет агенту намерение, но не заменяет механическую защиту.

`CLAUDE.md` хранит обзор проекта и общие правила, которые нужны в каждой сессии. В него не стоит складывать всю историю решений и длинные workflow-чеклисты. Решения и отвергнутые подходы вынеси в `DECISIONS.md`, а процедуры загружай через skills только тогда, когда они нужны для текущей работы. Так постоянный контекст остаётся коротким.

- [Claude 3.7 Sonnet and Claude Code](https://www.anthropic.com/news/claude-3-7-sonnet?__from__=talkingdev)
- [Maximizing the value of your Claude Code sessions](https://claude.com/blog/maximizing-the-value-of-your-claude-code-sessions)
- [Using CLAUDE.md files](https://claude.com/blog/using-claude-md-files)
- [Steering Claude Code: when to use CLAUDE.md, skills, hooks, rules, and subagents](https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more)
- [Long-running Claude for scientific computing](https://www.anthropic.com/research/long-running-Claude?gh_src=LinkedIn)
- [Scaling Agentic Coding Across Your Organization](https://resources.anthropic.com/hubfs/Scaling%20agentic%20coding%20across%20your%20organization.pdf)
- [Using Claude Code: session management and 1M context](https://claude.com/blog/using-claude-code-session-management-and-1m-context)
- [Edit/Write tools bypass permissions.ask rules](https://github.com/anthropics/claude-code/issues/22055)
- [My Claude Code workflow after months of daily use](https://www.reddit.com/r/ClaudeCode/comments/1vmey7d/my_claude_code_workflow_after_months_of_daily_use/)
- [Claude Code releases](https://github.com/anthropics/claude-code/releases)