Как организовать проект для работы с Claude Code

В прошлом посте я рассказывал про приёмы работы с Claude Code — управление контекстом, субагенты, планирование. Но все эти приёмы работают заметно лучше, если проект правильно организован. Здесь расскажу, как я структурирую рабочее пространство, чтобы выжать из Claude максимум.

Одна папка — один проект

Главный принцип: всё, что относится к проекту, должно лежать в одной корневой папке. Фронтенд, бэкенд, мобильное приложение, документация, рабочие заметки — всё вместе.

Claude Code работает с тем, что видит в рабочей директории. Если бэкенд лежит в отдельном репозитории где-то в другом месте — агент о нём не знает. Не может проверить контракт API, не может найти баг на стыке фронта и бэка, не может понять, почему запрос возвращает не то, что ожидает клиент.

Типичная структура:

Запускаешь Claude Code в корне my-project/ — и у него есть полный контекст. Он знает, как устроен API, как его вызывает фронт, что ожидает мобилка, что написано в требованиях, и как это всё проверить end-to-end тестами.

CLAUDE.md в корне — карта проекта

На уровне корневой папки нужен CLAUDE.md, который объясняет, где что лежит. Не подробная документация — именно карта: какой репозиторий за что отвечает, как запускать, какие есть особенности.

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

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

Сценарий: расследование бага

Вот конкретный пример, зачем это нужно. Клиент сообщает: «при сохранении формы данные теряются». Что делать?

Первый вопрос — а как вообще должно работать? Если в проекте есть документация с требованиями, Claude идёт туда и проверяет: это баг или ожидаемое поведение? Может, поле и не должно сохраняться — его ещё не реализовали, или это сознательное ограничение.

На маленьком проекте все требования можно держать в голове. Но если проект тянется несколько лет — никакой головы не хватит. Документация становится не роскошью, а необходимостью. И с Claude Code обращаться к ней действительно легко — если она лежит рядом с кодом, в той же папке.

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

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

Можно пойти дальше: попросить проанализировать git-историю и найти коммит, в котором поведение сломалось. Какая задача, какой разработчик, что именно было изменено. После этого — спросить у разработчика, было ли так задумано или дефект внесли случайно. Раньше таким расследованием никто не занимался — слишком дорого по времени. С Claude Code это занимает минуты.

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

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

Сценарий: full-stack разработка

Когда все части проекта в одном workspace, Claude работает как full-stack разработчик.

Нужно добавить новое поле в профиль пользователя? Одна задача: модель бэкенда, миграция, эндпоинт API, вызов на фронтенде, обновление формы, тест. Claude делает всё последовательно, в одном контексте, не теряя нить.

Нужно изменить формат ответа API? Claude видит и серверный код, и клиентский. Меняет эндпоинт на бэке и сразу адаптирует вызовы на фронте — не забудет ни один.

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

Сценарий: документация и код

Документация рядом с кодом — это не про порядок. Это рабочий инструмент, и связь работает в обе стороны.

Код → документация. Написали новый модуль — просите Claude разобраться в нём по исходникам и сгенерировать документацию. Не абстрактные комментарии в коде, а нормальное описание: что делает, как использовать, какие есть ограничения. Claude прочитает код, поймёт логику и напишет.

Документация → код. Работает и наоборот. Сначала описываете требования в документации — что нужно, как должно работать, какие есть ограничения. Потом даёте Claude задачу: реализуй на основе этого описания. Он идёт в документацию, читает требования и последовательно реализует. Не нужно каждый раз заново объяснять, что от него хотят — всё описано в файлах.

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

End-to-end тесты. Отдельная папка e2e/ с тестами, которые проверяют продукт целиком — от фронтенда до бэкенда. Ключевой момент: эти тесты должны соответствовать документации и покрывать функционал, который живёт в разных репозиториях. По сути, это ещё одно представление требований — но исполняемое. Claude может запустить их после фикса, чтобы убедиться, что ничего не сломалось. Может написать новый тест на основе пользовательской истории. Может обновить существующий тест после изменения требований. И всё это работает, потому что тесты, код и документация лежат рядом — в одном workspace.

Это особенно удобно для больших задач, которые не помещаются в одну сессию. Описал требования в .md-файлах, разбил на подзадачи — и Claude может работать над ними в разных сессиях, не теряя контекста. Требования лежат в файлах, а не в чате.

Скиллы — глобальные и проектные

Если какой-то процесс повторяется из сессии в сессию — оформите его в скилл. Это markdown-файл с пошаговой инструкцией, который вызывается одной командой.

Скиллы бывают двух видов. Глобальные — лежат в ~/.claude/skills/, работают во всех проектах. Например, скилл для сбора SEO-метрик или для написания постов в блог (этот пост написан именно так). Один раз настроил — используешь везде.

Проектные — лежат в .claude/skills/ внутри проекта, коммитятся в git и доступны всем, кто работает на проекте. Сюда идёт то, что специфично именно для этого продукта. Например, скилл для деплоя, который знает конкретный сервер, конкретный процесс сборки и конкретные проверки после деплоя. Или скилл для тестирования, который знает, как создать тестового пользователя, как залогиниться на тестовом окружении и как дойти до нужной страницы.

Папки для долгосрочных активностей

Отдельный приём — создавать папки под конкретные крупные активности внутри проекта. Например, проектируется новый модуль, и работа предполагается итеративная: сначала аутлайн, потом подробная документация, потом разработка.

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

Итого

Структура проекта для Claude Code — это не про чистоту ради чистоты. Это про то, чтобы дать агенту полный контекст:

• Одна папка со всеми частями проекта — фронт, бэк, мобилка, документация
• CLAUDE.md в корне — карта, которая объясняет, где что лежит
• CLAUDE.md в подпроектах — специфика каждой части
• Документация рядом с кодом — чтобы связь работала в обе стороны
• Скиллы — глобальные и проектные, чтобы не повторять одно и то же
• Папки под активности — чтобы не терять контекст между сессиями

Я экспериментировал с разными подходами к организации рабочего пространства, но остановился на этом как на наиболее мощном и удобном. Чем лучше организован проект, тем меньше нужно объяснять в каждой сессии — и тем больше Claude может сделать самостоятельно.