Наприкінці січня 2026 року я приєднався до команди Spatie як back-end розробник і одразу занурився у великий клієнтський проєкт. Його розробляли з червня 2025-го, і на момент моєї появи він був готовий лише наполовину, маючи понад 150 000 рядків коду (LoC).
Це величезний обсяг інформації, яку потрібно було швидко опанувати.
За останні місяці агентне програмування зробило величезний стрибок. Проте замість того, щоб змушувати ШІ генерувати ще більше коду, я спробував інший підхід: використав його, щоб розібратися в уже існуючій базі.
З чого я почав
На щастя, мої колеги вже налаштували якісний AI-воркфлоу для проєкту:
- Laravel Boost
- Набір Claude Skills (як специфічних для проєкту, так і загальних)
- Детальні файли
AGENTS.mdтаCLAUDE.md - Папку
docs/з нотатками про бізнес-логіку, яку, судячи з усього, закинули за кілька тижнів після старту 😅
Два інструменти виявилися найбільш корисними.
Laravel Boost — недооцінена річ. Це MCP-сервер, який надає Claude прямий доступ до schema, routes, config, artisan та tinker. Тож на питання «Чи є вже сервіс для X?» Claude використовував Boost, а не просто вгадував за назвами файлів.
Щодо скілів, я найбільше спирався на php-guidelines-from-spatie для дотримання наших PHP та Laravel конвенцій, а також на laravel-inertia-react-structure для фронтенду. Завдяки їм Claude знає наш стиль коду та стандарти без зайвих нагадувань у кожному промпті.
Це надійна база, але вона не замінює реального розуміння системи. Тому я попросив Claude скласти високорівневий опис усієї кодової бази.
З чого почати знайомство
Насамперед рекомендую спробувати codebase-onboarding skill. Після встановлення та запуску на проєкті він генерує два файли:
- Onboarding guide: опис технологічного стеку, архітектури, точок входу, життєвого циклу запиту, конвенцій та типових завдань.
- Проєктний
CLAUDE.md: дані про стек, стиль коду, тестування та команди збірки.
Альтернативний варіант — Repomix. Він збирає всю кодову базу в один файл, зручний для ШІ. Увімкніть output.compress, щоб видалити неструктурний код (використовує Tree-sitter, що зменшує кількість токенів приблизно на 70%), та output.tokenCountTree для контролю контексту. Віддайте цей файл вашій LLM — і їй не доведеться щоразу сканувати одні й ті самі файли.
Це найкраща точка входу, після якої можна переходити до точкових запитів щодо конкретних доменів.
Промпти, які я використовував найчастіше
Важливе зауваження: сприймайте все, що Claude каже про код, як гіпотезу, а не як істину. Завжди перевіряйте будь-які нетривіальні твердження в реальному коді.
Ось запити, які допомагали мені протягом перших тижнів роботи (принаймні ті, якими не соромно поділитися).
Для знайомства з проєктом:
Give me a map of this codebase. What are the main domains/modules,
what does each own, and how do they relate to each other?
Describe the core data model. What are the most important entities,
their relationships, and any non-obvious design decisions?
Give me a dependency map of all domains/modules. Which depend on
which, any circular dependencies, and places where boundaries seem violated.
Порада: просіть діаграму, а не просто текст. Скіл fireworks-tech-graph перетворює структурний опис на готові SVG або PNG. Циклічну залежність на графіку помітити значно легше, ніж у масиві тексту.
Коли потрібно зануритися глибше:
What does this codebase assume about its environment that isn't
obvious from the code itself? (config values, external services,
queue/cache drivers, DB assumptions, etc.)
Для конкретного домену:
Look at the [X] domain. What problems was it clearly designed to
solve and how does it solve them?
Це здається очевидним, але наявність готових промптів позбавила мене потреби щоразу вигадувати нові формулювання.
Де Claude помилявся
Протягом перших тижнів Claude часто помилявся з великою впевненістю. Не довіряйте ШІ наосліп, особливо якщо у вас обох бракує контексту. 😉
Наочний приклад: наше локальне оточення працює через Docker, а більшість команд (npm, composer, php artisan) обгорнуті у Makefile. Про це не було згадок ні в CLAUDE.md, ні в AGENTS.md. Коли Claude намагався щось запустити, він використовував стандартний шлях Laravel — php artisan прямо на хості, а не через make. Результат: не той хост, не та версія PHP і купа помилок.
## Artisan Commands
.PHONY: artisan
artisan: ## Run artisan command (Usage: make artisan route:list)
docker-compose -f $(COMPOSE_FILE) exec $(APP_CONTAINER) php artisan $(if $(CMD),$(CMD),$(filter-out $@,$(MAKECMDGOALS)))
## Package Management Commands
.PHONY: composer
composer: ## Run composer command (Usage: make composer require package)
docker-compose -f $(COMPOSE_FILE) exec $(APP_CONTAINER) composer $(if $(CMD),$(CMD),$(filter-out $@,$(MAKECMDGOALS)))
## Frontend Commands
.PHONY: npm-dev
npm-dev: ## Start Vite development server
docker-compose -f $(COMPOSE_FILE) exec $(APP_CONTAINER) npm run dev
# ...
Це наша провина, а не Claude. В офіційному гайді Anthropic щодо CLAUDE.md чітко сказано: команди для збірки та запуску мають бути там. Ми виправили це, але цей випадок нагадує: ШІ завжди обирає стандартний шлях фреймворку. Якщо ваш проєкт використовує кастомні рішення (Docker, Makefile, devcontainers), зафіксуйте це документально перед онбордингом людини чи ШІ.
Для якісного аналізу коду важливо, щоб ШІ отримував коректні дані. Розбийте воркфлоу на промпти або контекст і підтримуйте цю інформацію в актуальному стані.
Домени як крива навчання
Проєкт побудований за принципом domain-driven layout. Кожен домен має чітко визначені межі, тому після того, як Claude їх структурує, ви можете вивчати їх по черзі.
Коротко про архітектуру: у «стандартному» Laravel файли групуються за типом (моделі в app/Models, контролери в app/Http/Controllers тощо). Щоб відстежити логіку, наприклад, замовлення, доводиться стрибати між п’ятьма папками.
Domain-driven development змінює це. Файли групуються за бізнес-концепціями. Кожен домен (Identity, Orders, Billing) має власну папку з моделями, actions, events та іншим. Вивчення однієї папки дає повну картину без зайвих переходів.
// Одна папка домену на бізнес-концепцію
src/Domain/Invoices/
├── Actions
├── Commands
├── QueryBuilders
├── Collections
├── DataTransferObjects
├── Events
├── Exceptions
├── Listeners
├── Models
├── Rules
└── States
src/Domain/Customers/
// …
Ми детально розбираємо це у курсі Laravel Beyond CRUD. Перевага в тому, що домен достатньо малий для опрацювання за один підхід як людиною, так і ШІ. Саме так Claude і групує свій аналіз.
Звісно, такий підхід працює і для класичної структури Laravel, але доменний поділ зробив мій онбординг значно простішим.
Аналіз моделі даних
Для проєктування баз даних ми використовуємо Luna Modeler. Файли .dmm, які він генерує, — це JSON. Їх можна просто закинути в Claude і попросити розібрати архітектуру. Разом із кодом це дає ШІ потужний контекст для роздумів.
Корисною була не лише схема, а й історія її змін. Тривалі проєкти накопичують сліди «змін курсу»: таблиці розширювалися, розділялися або ставали deprecated через нові вимоги клієнта.
Claude помітив розбіжності між файлом .dmm та міграціями. На діаграмі Luna стало зрозуміло, які частини схеми змінювалися найчастіше.
Цей контекст допоміг мені при розробці нових фіч. Розуміння того, які таблиці стабільні, а які перероблялися тричі, дозволило приймати кращі рішення: де розширювати код, де проводити рефакторинг, а що краще не чіпати до наступних великих змін.
Підсумок
Раніше вхід у проєкт, що триває сім місяців, означав тижні «притирання» до того, як станеш по-справжньому продуктивним. З правильними інструментами цей час скоротився в рази. У перші дні Claude перетворив моноліт на зрозумілу структуру, а вже за кілька тижнів я створював великі фічі, що органічно вписувалися в існуючі патерни.
Без попереднього аналізу та структурованого підходу ця робота зайняла б значно більше часу, а результат міг би випадати із загальної стилістики проєкту.