# Руками в папке проекта ничего не трогаем: гигиена рабочего места агента

Переименовал папку руками - и агент перестал находить файлы. Разбираю, что в рабочей папке можно делать самому, что только через агента и как всё починить.

URL: https://posts.danashkin.ru/guides/gigiena-rabochey-papki-agenta
Обновлено: 2026-08-25

---

## Коротко

**Главное**

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

## Что ломается, когда ты переименовываешь файл руками?

**Главное**

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

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

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

Дело не в капризности инструмента. Агент работает по описанию, которое хранится в файлах проекта: какие есть разделы, где лежат данные, что от чего зависит. Ты поменял реальность, а описание осталось прежним - получилось расхождение, о котором знаешь только ты.

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

## Почему агент не замечает файл, который ты положил сам?

**Главное**

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

Это второе место, где ломается интуиция. Человек думает: раз файл в папке проекта, агент его видит. Не видит.

Правильный порядок - две реплики вместо одной:

1. **«Изучи файл с брифом, который я положил в папку с материалами, и пропиши его там, где это нужно».**
2. **«Проверь, пожалуйста: ты всё учитываешь?»**

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

**Признак, что файл не подхвачен**

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

Механика тут та же, что у [второго мозга](/concepts/vtoroy-mozg) проекта: агент опирается на описание, а не на содержимое диска. Что именно писать в этом описании, я разбирал в материале про [файл-память агента](/guides/chto-pisat-v-claude-md).

## Граница: руками или через агента

**Главное**

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

| Действие | Руками | Через агента |
|---|---|---|
| Открыть и прочитать файл | да | не нужно |
| Скопировать результат себе на рабочий стол | да | не нужно |
| Положить новый исходник в папку | да, но потом сказать агенту | можно и через него |
| Переименовать файл или папку | нет | да, с объяснением зачем |
| Перенести файл в другой раздел | нет | да |
| Удалить лишнее | нет | да, после вопроса «что сломается» |
| Править файлы, которые агент ведёт сам | нет | да |
| Навести порядок в структуре | нет | да, отдельной задачей |

Правило одной строкой: **структуру меняет агент, ты меняешь задачи**.

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

## Как правильно добавить свои материалы в проект?

**Главное**

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

1. **Положи файл в подпапку с материалами**

   Не в корень проекта. Одна папка под входящие документы, и в ней порядок понятен тебе, а не только агенту.

2. **Назови файл понятно и латиницей**

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

3. **Скажи агенту, что появилось и зачем**

   «Положил бриф клиента, он теперь основной источник требований, учитывай его при всех задачах по этому разделу».

4. **Попроси внести в описание проекта и проверь**

   «Пропиши это в файле правил проекта». Потом: «перечисли, что ты сейчас видишь». Файл должен быть в списке.

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

## Один проект - одна папка, а не десять чатов

**Главное**

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

Один участник обучения сформулировал своё открытие так: я просто заводил тут чаты, а тут нужно наоборот - создавать каждый раз папку, а потом уже в этой папке заводить чат. Это ровно та развилка, которую стоит пройти пораньше.

Разница в трёх вещах:

- **Память.** В папке живут правила проекта и история решений. В чате - только текущий разговор.
- **Материалы.** В папке лежат исходники: брифы, выгрузки, документы. В чат их приходится загружать заново каждый раз.
- **Результат.** В папке результат накапливается файлами. В чате он рассыпается по сообщениям, и через неделю ты его не найдёшь.

Это часть более общего подхода, который я называю сборкой контекста для агента. Подробно разбирал его в материале про [контекст-инжиниринг](/guides/kontekst-inzhiniring).

## Что делать, если уже наломал?

**Главное**

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

Порядок восстановления:

1. **Скажи честно, что менял.** «Я переименовал папку с документами и перенёс два файла, вот новые имена».
2. **Попроси сверку.** «Пройди по служебным файлам, найди ссылки на старые пути и приведи их в порядок».
3. **Попроси карту.** «Опиши текущую структуру проекта коротко, чтобы я видел, что ты видишь».
4. **Проверь на маленькой задаче.** Не на важной: убедись, что агент попадает в нужные файлы.

**Перед большими перестановками**

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

И последнее наблюдение. Желание «навести порядок руками» обычно возникает от тревоги: человеку кажется, что в папке хаос, потому что он в ней не разбирается. Правильная реакция - попросить агента объяснить структуру, а не переделывать её под свою привычку.

Тревога эта, кстати, предсказуемая: она приходит сразу после того, как первые задачи начали получаться. Человек перестаёт бояться, что сломает, и начинает бояться, что организовал всё неправильно. На обучениях это звучит как «правильно ли я всё настроил». Ответ обычно один: структура нормальная, просто ты её не читал.

Здесь же лежит и вторая причина беспорядка - привычка держать рабочие файлы там, где привык их искать: на рабочем столе, в загрузках, в переписке. Проект от этого не ломается сразу, но через месяц ты не сможешь сказать, какая версия документа настоящая, а агент будет читать ту, которую ему один раз показали. Проще с самого начала считать папку проекта единственным местом, где живут материалы, и не держать вторых копий. Как понять, что контекст пора чистить и переносить в новый чат, разбирал в материале про [гигиену контекстного окна](/guides/gigiena-kontekstnogo-okna).

## Частые вопросы

**Главное**

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

### Частые вопросы

**Открывать файлы проекта вообще нельзя?**

Открывать и читать можно сколько угодно. Опасно менять: переименовывать, переносить, править содержимое. Чтение ничего не ломает.

**У меня папка в облаке и синхронизируется. Это плохо?**

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

**Надо ли раскладывать файлы по красивой структуре?**

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

**Как быть, если проектов несколько?**

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

## Главный вывод

**Главное**

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

Вся статья сводится к одной картинке. Ты нанял исполнителя, который держит карту офиса в голове. Переставил мебель ночью - утром он ищет стол на прежнем месте.

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

Начни с простого: попроси агента перечислить материалы проекта. Если в списке не хватает половины того, что лежит в папке, ты нашёл причину его странных ответов.

### Источники

- [Claude Code - как агент читает файл памяти проекта и что туда попадает](https://code.claude.com/docs/en/memory)
- [Claude Code - официальная документация: обзор работы в папке проекта](https://code.claude.com/docs/en/overview)
- [Claude Code - типовые рабочие сценарии, включая работу с файлами проекта](https://code.claude.com/docs/en/common-workflows)
- [Pro Git - о фиксации состояния проекта и возврате к прошлой версии, русский перевод](https://git-scm.com/book/ru/v2)
- [Version control - зачем нужна история изменений, Википедия](https://en.wikipedia.org/wiki/Version_control)
- [Model Context Protocol - как агенту дают доступ к внешним данным и файлам](https://modelcontextprotocol.io/)