11 - Integrating Claude Code into a Real Project

Integrating Claude Code into a Real Project: Play The Event

In the first 10 articles of this series, we explored Claude as a technical partner, from initial setup to deployment and maintenance. Now it's time to see all of this applied to a real production project: Play The Event, an enterprise multi-stack platform with DDD, Hexagonal, and CQRS architecture.

In this article, I share the hands-on experience of integrating Claude Code into the daily development workflow, showing how it radically transforms productivity on a project with Java/Spring Boot backend, Angular 19 frontend, and Python/FastAPI analytics.

1. Project Configuration with CLAUDE.md

The core of Claude Code integration in Play The Event is the CLAUDE.md file, placed in the repository root. This file defines the complete project context, allowing Claude to automatically inherit the architecture, conventions, and constraints at every session.

# CLAUDE.md - Play The Event

## Architecture
- Domain-Driven Design (DDD)
- Hexagonal Architecture (Ports & Adapters)
- CQRS (Command Query Responsibility Segregation)

## Development Commands
### Backend (Java/Spring Boot)
- mvn spring-boot:run -pl backend
- mvn test -pl backend

### Frontend (Angular 19)
- npm start --prefix frontend
- npm run build --prefix frontend

### Analytics (Python/FastAPI)
- uvicorn main:app --reload --port 8001

## Naming Conventions
- Source code: ITALIAN (Evento, Partecipante, creaEvento())
- REST APIs: ENGLISH (/api/v1/events, /api/v1/participants)
- Database: snake_case English (event_participants)

## Accessibility (MANDATORY)
- WCAG 2.1 AA for every UI change
- Minimum contrast 4.5:1
- Aria-labels on all interactive elements
- Complete keyboard navigation

## Commit Format
- [fe] - Frontend Angular changes
- [be] - Backend Spring Boot changes
- [py] - Analytics Python changes
- [deploy] - Deployment configuration
- [docs] - Documentation

Thanks to this file, Claude Code doesn't need repeated explanations about the architecture. At every new session, it reads the CLAUDE.md and operates with full awareness of the stack, conventions, and project constraints.

2. Custom Slash Commands

For repetitive tasks, Claude Code supports custom slash commands that automate common operations. In Play The Event, we use several to maintain consistency and speed.

# The /create-aggregate command automatically generates:

## Domain Layer
src/main/java/com/pte/domain/model/Evento.java         # Entity
src/main/java/com/pte/domain/model/EventoId.java       # Value Object ID
src/main/java/com/pte/domain/repository/EventoRepository.java  # Port

## Application Layer
src/main/java/com/pte/application/command/CreaEventoCommand.java
src/main/java/com/pte/application/handler/CreaEventoHandler.java
src/main/java/com/pte/application/query/GetEventoQuery.java

## Infrastructure Layer
src/main/java/com/pte/infrastructure/persistence/EventoJpaRepository.java
src/main/java/com/pte/infrastructure/persistence/EventoEntity.java

## Interface Layer
src/main/java/com/pte/interfaces/rest/EventoController.java
src/main/java/com/pte/interfaces/rest/dto/EventoRequest.java
src/main/java/com/pte/interfaces/rest/dto/EventoResponse.java

Every command generates code that respects the conventions defined in CLAUDE.md: Italian class names, English REST endpoints, strict Hexagonal structure.

3. Iterative Development Workflow

The development cycle with Claude Code follows a natural iterative pattern that starts from a natural language request and arrives at verified code.

# User request:
"Improve the CSS of the expense-analytics section"

# Claude Code:
1. Reads expense-analytics.component.scss
2. Reads expense-analytics.component.html
3. Analyzes the existing design system
4. Proposes improvements: grid layout, spacing, responsive
5. Applies the changes
6. Runs: npm run build --prefix frontend
7. Result: Build OK, 0 errors

# Second iteration:
"The export should be in Excel, not JSON"

# Claude Code:
1. Identifies the need for an external library
2. Installs: npm install xlsx --prefix frontend
3. Modifies the export function
4. Creates 8 structured Excel sheets (one per analytics section)
5. Verifies the build: OK

4. Complex Task Management

When a task is too large to be completed in a single step, Claude Code automatically subdivides it into trackable subtasks, completing them sequentially with verification.

# Request: "Dashboard Analytics improvements"

Claude automatically subdivides into:
  [1/6] Empty States for sections with no data
  [2/6] Quick Actions Bar with frequent actions
  [3/6] Visual improvements to KPI cards
  [4/6] Comparative trends with previous month
  [5/6] Upcoming events section
  [6/6] Sparklines in KPIs for quick trends

Each subtask is:
- Implemented individually
- Verified with build
- Committed separately

This approach ensures that each change is isolated, verifiable, and easily reversible in case of issues.

5. Multi-Stack Knowledge

Play The Event operates on three different technology stacks in the same repository. Claude Code understands the relationships between layers and operates on all three with awareness of mutual dependencies.

Claude understands that a backend DTO corresponds to a TypeScript model in the frontend and a response schema in analytics. When modifying an entity, it propagates changes across all involved layers.

6. Built-in Accessibility

WCAG 2.1 AA guidelines are integrated directly into the CLAUDE.md. Claude Code applies them automatically during every UI change, without needing manual reminders.

## Accessibility Checklist (MANDATORY for every UI change)

### Contrast and Colors
- Minimum ratio 4.5:1 for normal text
- Minimum ratio 3:1 for large text (18px+ or 14px+ bold)
- DO NOT use #F39C12 on white background (insufficient contrast)
- Accessible colors documented in design system

### HTML Structure
- Correct heading hierarchy (h1 > h2 > h3, never skip levels)
- Semantic elements: nav, main, section, article, aside
- Aria-labels on all interactive elements without visible text
- Role attributes where necessary

### Interaction
- Logical and sequential tab order
- Visible focus on all interactive elements
- Touch targets minimum 44x44px
- Complete keyboard navigation support

When Claude Code generates a new component or modifies an existing template, it automatically verifies compliance with these rules, adding aria-labels, checking contrast ratios, and ensuring keyboard navigation.

7. Contextual Refactoring

Claude Code understands cross-file dependencies in the project. When modifying a model, service, or component, it automatically propagates changes to all related files.

# Request: "Rename 'dataEvento' to 'dataInizio' in the Evento entity"

# Claude Code automatically propagates:
1. domain/model/Evento.java         → dataEvento → dataInizio
2. interfaces/rest/dto/EventoResponse.java → field updated
3. infrastructure/persistence/EventoEntity.java → mapped column
4. frontend/models/evento.model.ts  → TypeScript property
5. frontend/components/evento-detail.component.html → template binding
6. frontend/components/evento-list.component.html   → table column
7. resources/db/migration/V12__rename_data_evento.sql → ALTER TABLE

8. External Library Integration

Claude Code manages the entire lifecycle of integrating new libraries, from identifying the need to verifying the final build.

# Request: "The report export should be in Excel, not JSON"

# Step 1 - Identify
Claude: "Generating Excel files requires the xlsx library"

# Step 2 - Install
$ npm install xlsx --save --prefix frontend

# Step 3 - Implement
import * as XLSX from 'xlsx';

exportToExcel(data: ReportAnalytics): void {{ '{' }}
  const workbook = XLSX.utils.book_new();

  // Create 8 structured sheets
  XLSX.utils.book_append_sheet(workbook,
    XLSX.utils.json_to_sheet(data.kpiSummary), 'KPI');
  XLSX.utils.book_append_sheet(workbook,
    XLSX.utils.json_to_sheet(data.participants), 'Participants');
  // ... 6 more sheets

  XLSX.writeFile(workbook, `report-${{ '{' }}data.eventName{{ '}' }}.xlsx`);
{{ '}' }}

# Step 4 - Verify
$ npm run build --prefix frontend
Build completed successfully. 0 errors.

9. Bilingual Naming Conventions

A distinctive feature of Play The Event documented in CLAUDE.md: source code uses Italian names, while REST APIs follow English conventions. Claude Code respects this distinction automatically.

// Claude generates the controller respecting both conventions

@RestController
@RequestMapping("/api/v1/events")  // English for API
public class EventoController {{ '{' }}  // Italian for class

    private final CreaEventoHandler creaEventoHandler;  // Italian

    @PostMapping
    public ResponseEntity<EventoResponse> createEvent(  // English for HTTP method
        @RequestBody CreaEventoRequest request) {{ '{' }}  // Italian for internal DTO
        return ResponseEntity.ok(
            creaEventoHandler.esegui(request)  // Italian for logic
        );
    {{ '}' }}
{{ '}' }}

10. Debugging and Problem Solving

Claude Code analyzes errors and proposes targeted fixes. It doesn't just suggest: it identifies the cause, implements the solution, and verifies it works.

# Report: "The Export Report button doesn't work"

# Claude Code analyzes the code:
exportReport() {{ '{' }}
  console.log('Export report clicked');  // Just a log!
{{ '}' }}

# Diagnosis: The function was never implemented,
# it only contains a placeholder console.log

# Fix implemented by Claude Code:
exportReport() {{ '{' }}
  const reportData = this.analyticsService.getFullReport();
  const blob = new Blob([JSON.stringify(reportData, null, 2)],
    {{ '{' }} type: 'application/json' {{ '}' }});
  const url = URL.createObjectURL(blob);
  const link = document.createElement('a');
  link.href = url;
  link.download = `report-${{ '{' }}this.event.name{{ '}' }}.json`;
  link.click();
  URL.revokeObjectURL(url);
{{ '}' }}

11. Persistent Memory (Auto Memory)

Claude Code maintains a persistent memory directory that survives across sessions. This allows accumulating incremental knowledge about the project, documenting recurring patterns, and solutions to common errors.

/home/user/.claude/projects/play-the-event/memory/
  MEMORY.md              # Main file (loaded into system prompt)
  debugging.md           # Common errors and solutions
  patterns.md            # Recurring architectural patterns
  conventions.md         # Project-specific conventions

# Play The Event - Project Memory

## Recurring Patterns
- DDD aggregates always follow: Entity + ValueObject ID + Repository Port
- Angular components use Signals, never manual subscribe
- Flyway migrations follow V{{ '{' }}number{{ '}' }}__{{ '{' }}description{{ '}' }}.sql

## Common Errors Resolved
- Angular: "NG0100 ExpressionChangedAfterItHasBeenChecked"
  → Solution: use signal computed() instead of getter
- Spring Boot: "LazyInitializationException" in queries
  → Solution: use JOIN FETCH or @EntityGraph

## Architectural Decisions
- Chose CQRS to separate reads (analytics) from writes (commands)
- FastAPI for analytics because ML libraries are Python-native

The memory is automatically consulted at the beginning of each session, allowing Claude Code to build on knowledge from previous sessions without starting from scratch.

12. Structured Work Plan

For complex tasks requiring changes across multiple files or architectural decisions, Claude Code enters Plan Mode: a structured workflow that ensures alignment with the developer before writing code.

# Plan Mode - Phases

## Phase 1: Exploration
- Claude Code explores the codebase
- Identifies involved files
- Analyzes dependencies and impact

## Phase 2: Design
- Proposes detailed plan with priorities
- Lists files to create/modify
- Identifies risks and alternatives

## Phase 3: Review
- Presents the plan to the developer
- Answers questions and clarifications
- Modifies the plan if needed

## Phase 4: Approval
- The developer approves the plan
- Claude Code starts implementation
- Executes step by step with verification

Measurable Benefits

Integrating Claude Code into the Play The Event workflow has produced concrete and measurable improvements in daily productivity.

Claude Code Tools and Resources

Claude Code does not exist in isolation: a rich ecosystem of extensions, community tools, SDKs, and educational resources has grown around it, amplifying its capabilities. Understanding this ecosystem allows you to maximize Claude Code's potential in any development context.

IDE Extensions

Integration with code editors represents the most direct point of contact between Claude Code and the daily workflow. Claude Code Chat for VS Code provides a native chat interface directly within the editor, complete with conversation history and full support for MCP servers. This means you can interact with Claude without ever leaving your development environment, keeping the project context always active. As a complement, the Claude VSCode Theme offers a collection of dark themes designed to reduce visual fatigue during extended pair programming sessions with the assistant.

Claude for Chrome

For those who frequently work in the browser, Claude for Chrome (currently in Beta) brings agent capabilities directly into web navigation. This extension supports automatic task scheduling, allowing you to schedule recurring operations, and introduces a planning mode for structuring complex workflows before executing them. Multi-tab management enables coordinating actions across multiple tabs simultaneously, while smart navigation allows Claude to interact with web pages autonomously. This feature requires the Max plan and is particularly useful for research tasks, web interface testing, and browser-based workflow automation.

Community Guides

The developer community has produced exceptionally valuable resources for mastering Claude Code. The guide "Claude Code Everything You Need to Know" stands as the most comprehensive reference available, covering initial setup, prompt engineering, commands, hooks, automation workflows, MCP server configuration, and the BMAD method for structured project management. For those who prefer a more concise approach, "40+ Claude Code Tips" gathers over forty practical and immediately applicable suggestions, from optimal configuration to advanced techniques for interacting with the agent.

MCP Server Ecosystem

The Model Context Protocol (MCP) has spawned an ecosystem of integrations that extends Claude Code's capabilities far beyond the terminal. The awesome-mcp-servers repository catalogs an impressive landscape of over 2,500 API integrations organized by category. The main categories include:

• Browser Automation: Microsoft Playwright for programmatic browser control
• Cloud Platforms: AWS, Cloudflare, Terraform, and Pulumi for infrastructure management
• Databases: Connectors for PostgreSQL, MongoDB, Redis, and other persistence systems
• Developer Tools: Integrations with GitHub, GitLab, Jira, and CI/CD tools
• Security: Vulnerability scanners, static analysis, and security auditing

For developing and testing custom MCP servers, the MCP Inspector provides an interactive debugging environment that greatly simplifies the process of developing and validating your own servers.

Agent SDK for Autonomous Agents

For developers who want to build custom agents based on Claude, official SDKs are available for both Python and TypeScript. These development kits provide the primitives needed to create autonomous agents capable of reasoning, planning, and executing complex tasks independently.

The community has responded enthusiastically: the awesome-claude-agents repository gathers a curated collection of agents built with these SDKs, while awesome-claude-code-subagents catalogs over 100 specialized agents designed for specific tasks such as code generation, review, testing, documentation, and deployment. These sub-agents can be combined into sophisticated pipelines, creating fully automated workflows.

Official Courses

Anthropic offers a structured learning path for developers who want to master the entire Claude ecosystem:

These courses cover the full spectrum of possibilities offered by the Claude platform, from assisted code writing to building complex agentic systems, through to deployment on enterprise cloud platforms.

Conclusion

Integrating Claude Code into Play The Event demonstrates that Claude Code is not a simple autocomplete: it's a pair programmer that understands the project architecture, applies team conventions, and maintains consistency across an enterprise multi-stack codebase.

The key to success is treating Claude Code as a team member: providing it with clear context, explicit conventions, and iterative feedback. The result is a radically more efficient development workflow, where code quality and delivery speed grow together.