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

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

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

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

Для этого необходимы:

• чёткие технические правила;

• актуальная архитектурная документация;

• прослеживаемая история изменений через Issues и Git;

• зафиксированные архитектурные решения;

• автоматические тесты и независимые проверки;

• стандартизированные отчёты о выполненной работе.

В этой статье я расскажу о практиках, которые я применяю в своей разработки. Я расскажу о том, как использовать Claude для ускорения разработки, не теряя собственного понимания проекта и контроля над ним.

Задавайте технические рамки

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

Определите рабочий стек

На старте разработки проекта зафиксируйте основные технологии и инструменты:

• языки программирования и их версии;

• фреймворки и основные библиотеки;

• систему управления базами данных;

• инструменты сборки и управления зависимостями;

• подходы к конфигурации и работе с секретами;

• способы запуска, тестирования и развёртывания приложения.

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

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

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

Зафиксируйте стандарты кода

Следующий шаг — определить единые правила написания и организации кода.

Не нужно описывать все правила вручную, так как Claude уже знает общие стандарты написания кода на всех популярных языках.

Используйте литеры и статические анализаторы для соблюдения стандартов написания кода.

При таком подходе Claude будет ориентироваться не только на текстовые инструкции, но и на проверяемые требования проекта.

Настраивать проверки качества кода необходимо на этапе локальной разработки, через Git Hooks и в репозитории через CI.

Примеры Bash скриптов для Git Hooks — https://github.com/prog-time/git-hooks

Примеры CI конструкций — https://github.com/prog-time/workflows

Документируйте архитектуру

Claude может достаточно быстро разобраться в конкретном участке проекта, найти нужные файлы и внести изменения, но с ростом кодовой базы, разработчику становится труднее понимать архитектуру проекта.

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

Используйте C4-модель для описания архитектуры

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

Для большинства проектов полезно начать с трёх уровней.

1. System Context — контекст системы.

На этом уровне описывается система в целом. Кто является пользователями? С какими внешними системами происходит взаимодействие? 

Такая схема помогает понять границы проекта.

Например, веб-приложение может работать с платёжным сервисом, внешним API, почтовым провайдером и системой идентификации пользователей.

2. Container — основные части системы.

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

Схема показывает, за что отвечает каждый компонент и как он взаимодействует с другими частями продукта.

3. Component — внутреннее устройство отдельных частей.

На этом уровне описываются компоненты, устройство которых важно понимать при разработке и сопровождении.

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

C4 — модель особенно полезна тем, что позволяет обсуждать изменения на правильном уровне.

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

Отдельно документируйте структуру базы данных

Если вы использует реляционную базу данных в своём проекте, следующим обязательным элементом становится ERD (Entity Relationship Diagram).

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

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

На ERD стоит отражать как минимум:

• основные сущности и таблицы;

• первичные и внешние ключи;

• связи и их кратность;

• важные ограничения целостности;

• значимые особенности модели данных.

При этом реальная схема, миграции и ограничения в самой СУБД остаются частью реализации, которую необходимо проверять. Диаграмма помогает человеку понять модель данных, но не заменяет проверку фактической структуры базы.

Важно обновлять данную схему при изменении структуры БД: добавлении таблиц, изменении связей, разделении сущностей или переносе данных.

Добавляйте схемы для сложных сценариев

C4 и ERD дают представление о структуре, но не всегда объясняют поведение системы во времени.

Для сложных сценариев полезны дополнительные диаграммы.

Диаграммы последовательностей 

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

Диаграммы состояний 

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

Схемы потоков данных 

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

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

Синхронизируйте документацию с изменениями кода

Архитектурная документация постоянно устаревает, поэтому важно обновлять документацию при каждом изменение проекта.

При каждой существенной задаче Claude должен определить:

1. Меняется ли структура системы или границы компонентов?

2. Появляются ли новые зависимости или интеграции?

3. Меняется ли модель данных?

4. Нужно ли обновить C4, ERD или диаграмму конкретного сценария?

5. Какие документы необходимо изменить вместе с кодом?

Это нужно закрепить в инструкциях для Claude и в критериях приёмки задачи, иначе весь смысл хранения данных схем теряется!

Для хранения схем можно использовать Mermaid, PlantUML или другие форматы, позволяющие держать описание диаграммы в текстовых файлах.

Фиксируйте архитектурные решения

По мимо описания существующей архитектуры, я также рекомендую описывать причины принятия решений.

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

Для этого существует подход Architecture Decision Records (ADR).

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

ADR можно хранить в репозитории, например в каталоге docs/adr/. Каждому решению присваивается отдельный номер и краткое название:

• 0001-choose-database.md;

• 0002-authentication-strategy.md;

• 0003-caching-approach.md.

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

1. Контекст. Какую проблему нужно решить и какие ограничения существуют?

2. Решение. Какой подход выбран и почему?

3. Альтернативы. Какие варианты рассматривались и почему от них отказались?

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

5. Статус. Решение предложено, принято, заменено другим или отклонено.

Такая запись позволяет оценить решение не только с точки зрения реализации, но и с учётом условий, в которых оно принималось.

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

Организуйте работу с Issues и Git

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

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

Создавайте Issues

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

Для каждой значимой задачи создавайте Issue в системе управления репозиторием, например GitHub или GitLab.

Крупные задачи лучше разделять на более мелкие, чтобы было проще контролировать код и проводить ревью.

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

Сохраняйте связь на всём пути изменения

Названия веток стоит стандартизировать заранее. Например:

• issues-123

• feature/issues-123-add-user-auth

• fix/issues-456-payment-error

Конкретный формат зависит от предпочтений команды. Важнее, чтобы он был единообразным и включал номер Issue.

Такая договорённость упрощает навигацию по репозиторию. Это даёт большой плюс, когда Claude работает над несколькими задачами последовательно или когда к проекту подключаются другие разработчики. 

Чтобы история оставалась понятной, важно последовательно связывать все этапы разработки.

Рабочая цепочка выглядит так:

Issue -> Branch -> Commits -> Pull Request -> CI -> Merge -> Release

Для соблюдения всех этих правил вы можете настроить проверки через Git Hooks. Git позволяет отлавливать любые события, внедрять свои проверки или корректировать результат.

Например, при создание коммита можно автоматически подставлять номер задачи в текст, коммита, чтобы в истории коммитов было понятно к какой задаче относится коммит.

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

CI должен запускать согласованный набор проверок и совпадать с Git Hooks проверками. По мере роста проекта процесс можно усложнять!

Поддерживайте документацию проекта в актуальном состоянии

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

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

README.md

README — один из первых документов, к которым обращается пользователь знакомясь с проектом.

Его задача объяснить, что представляет собой проект и как с ним работать.

README должен описывать возможности проекта, краткое описание архитектуры, требования к запуску и инструкцию по установке.

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

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

CHANGELOG.md

CHANGELOG.md — описывает то, как изменялся проект с появлением новых релизов.

В нем описываются новые возможности и изменения существующего поведения. CHANGELOG должен дать понятное описание того, что изменилось и почему это важно.

Дополнительные документы по мере роста проекта

Помимо README и CHANGELOG, полезно определить ещё несколько документов.

ARCHITECTURE.md — описывает основные архитектурные принципы, границы компонентов и ключевые зависимости. Если в проекте используются C4-диаграммы и ERD, документ может содержать ссылки на них и объяснять, как читать эти схемы.

CONTRIBUTING.md — определяет правила внесения изменений: создание Issues, именование веток, требования к коммитам, порядок работы с Pull Request и обязательные проверки.

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

Для небольшого проекта не обязательно создавать все эти документы сразу, можно начать с README, CHANGELOG и архитектурных схем, а остальные добавлять тогда, когда появляется реальная потребность.

Требуйте объяснения после изменения кода

Чтобы понимать в процессе выполнения задач, что было сделано, необходимо требовать от Claude добавлять краткий список изменений:

1. Что изменилось. Какие файлы, модули, функции или компоненты были добавлены, удалены или переработаны.

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

3. Почему выбрано такое решение. Какие архитектурные ограничения учитывались, какие альтернативы рассматривались и почему был выбран конкретный подход, если это существенно для понимания реализации.

4. Как проверен результат. Какие тесты и другие проверки запускались, что они показали и какие проверки остались невыполненными.

5. Что осталось сделать. Какие ограничения, риски или дополнительные задачи обнаружились в процессе работы.

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

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

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

Объедините всё в единый рабочий процесс

Все описанные практики работают лучше, как единая система управления изменениями.

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

Практический рабочий цикл может выглядеть следующим образом.

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

Шаг 2. Анализ. Попросите Claude изучить текущую реализацию, определить затрагиваемые компоненты, выявить ограничения и предложить план изменений.

Шаг 3. Проверка решения. Убедитесь, что предложенный подход соответствует архитектуре проекта. Если требуется существенное архитектурное решение, зафиксируйте его в ADR.

Шаг 4. Реализация. Claude вносит изменения в рамках согласованного плана, соблюдая правила проекта и не расширяя задачу без необходимости.

Шаг 5. Проверки. Запустите подходящие тесты, статический анализ, линтер и сборку.

Шаг 6. Документация. Актуализируйте архитектурные схемы, описание сценариев, README, ADR и CHANGELOG.

Шаг 7. Отчёт. Попросите Claude перечислить выполненные изменения, объяснить принятые решения, сообщить фактические результаты проверок и указать оставшиеся ограничения.

Шаг 8. Проверка и слияние. Сопоставьте результат с критериями приёмки, проведите необходимый code review и объедините изменения в соответствии с правилами репозитория.

Шаг 9. Сохранение знаний. Если в ходе работы обнаружились новые архитектурные ограничения, важные особенности системы или причины нестандартного поведения, зафиксируйте их в подходящем месте.

Ключевое отличие состоит в том, что изменение кода перестаёт быть единственным результатом работы, ведь вместе с ним вы получаете понятное обоснование, проверяемые результаты и актуальные знания о проекте.

Итог

Использование Claude позволяет значительно ускорить разработку, но скорость не гарантирует качества программного продукта.

Главный риск заключается в том, что код меняется быстрее, чем человек успевает понять последствия этих изменений.

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

В конечном счёте хороший результат работы с ИИ — это система, устройство которой можно объяснить, проверить, проследить.