23 - Claude Code 2.0 and VS Code Extension: Checkpoints, Named Sessions, .claude/rules

# Nel terminale Claude Code, durante una sessione:

# 1. Salvare un checkpoint manualmente
/checkpoint save "after-initial-refactoring"

# 2. Elencare tutti i checkpoint disponibili
/checkpoint list

# Output atteso:
# Checkpoint disponibili:
# 1. after-initial-refactoring     [2025-10-29 14:32:15]
# 2. auto-checkpoint-iter-10       [2025-10-29 14:25:43]
# 3. auto-checkpoint-iter-20       [2025-10-29 14:18:22]
# 4. start-of-session              [2025-10-29 14:00:01]

# 3. Rollback a uno specifico checkpoint
/checkpoint restore "after-initial-refactoring"

# Attesa: 5-15 secondi (dipende dalla size del checkpoint)
# Output:
# Checkpoint restored successfully.
# 42 files restored, 8 files removed, 120 lines changed in memory

# 4. Visualizzare differenze tra checkpoint
/checkpoint diff "after-initial-refactoring" "start-of-session"

# 5. Eliminare un checkpoint per risparmiare spazio
/checkpoint delete "auto-checkpoint-iter-10"

#!/bin/bash
# Scenario: refactor 50 file in monorepo

# 1. Avvia Claude Code in una sessione dedicata
claude --session "monorepo-refactor-naming-2025-10-29"

# 2. Dentro la sessione Claude:
> [Shift+Tab+Tab] Refactor 50 file del monorepo per rinominare tutti i service
> seguendo il pattern ServiceName.service.ts e aggiungi commenti JSDoc

# Claude inizia a lavorare...
# Dopo 20 file completati, salva manualmente un checkpoint:
> /checkpoint save "20-files-done-patterns-consistent"

# Continua per altri 30 file...
# Dopo 50 file, chiedi revisione:
> /checkpoint save "all-50-files-complete"
> Mostra un riepilogo di tutti i file cambiati

# A questo punto scopri che i test sono broken:
> /checkpoint list
> Vedi: "20-files-done-patterns-consistent"
> /checkpoint restore "20-files-done-patterns-consistent"

# Ora sei al punto di 20 file. Chiedi approccio diverso:
> Ripeti il refactoring dei prossimi 30 file, ma stavolta
> crea un script di refactoring automatico per i test,
> non modificare i test manualmente.

# Continua...
> /checkpoint save "30-more-files-with-test-automation"
> Concludi con i restanti 20 file
> /checkpoint save "all-50-with-automated-tests"

# Metodo 1: VS Code Marketplace UI
# 1. Apri VS Code
# 2. Vai a Extensions (Ctrl+Shift+X / Cmd+Shift+X)
# 3. Cerca "claude-code" o "Anthropic"
# 4. Clicca Install sul risultato ufficiale (logo Anthropic)
# 5. Al primo avvio, VS Code aprirà un flusso di login browser

# Metodo 2: Command Palette
# 1. Premi Ctrl+Shift+P (Cmd+Shift+P su macOS)
# 2. Digita: Extensions: Install Extensions
# 3. Cerca "claude-code"
# 4. Installa

# Metodo 3: CLI (se disponibile)
code --install-extension anthropic.claude-code

# 1. Apri VS Code con un progetto
code ~/projects/my-app

# 2. Clicca icon Claude nel sidebar sinistro (o Ctrl+L)
# → Appare il Claude Sidebar panel

# 3. Trascinare file nel sidebar per caricare nel contesto
# oppure digitare nel prompt Claude

# Esempio prompt nella sidebar:
> Aggiungi validazione email al form di registrazione
> Usa Angular reactive forms e i validatori built-in
> Aggiungi test per la validazione

# 4. Claude lavora sui file, visualizza diff nel editor
# Vedi un diff viewer che mostra:
#   LEFT:  old code
#   RIGHT: new code (highlighted)

# 5. Per ogni diff, scegli:
#   [✓ Accept] [✗ Reject] [↻ Request Change]

# 6. Una volta accettato, il file si modifica in tempo reale
# 7. Puoi continuare a chattare senza uscire dall'editor

# 1. Durante una sessione, rinominala:
> /rename "spring-boot-cache-layer-refactor"

# Ora la sessione ha un nome permanente

# 2. Al termine della sessione (dopo 2 ore di lavoro):
> Salvo i progressi. A domani!
# Premi Ctrl+D per uscire

# 3. Il giorno dopo, puoi riprendere esattamente dove eri:
claude --resume "spring-boot-cache-layer-refactor"

# Output:
# Resuming session: spring-boot-cache-layer-refactor
# Last activity: [2025-12-03 17:45:22]
# Context: 42 files loaded, 15 checkpoint disponibili
# Conversation history: 87 messages

# 4. Sei dentro la stessa sessione, stessa conversazione
> Ricordi dove eravamo rimasti? Ricapitoliamo ultimi 3 step
# Claude ha il contesto completo della conversazione

# 5. Elencare tutte le named session:
claude --list-sessions

# Output:
# Named Sessions:
# 1. spring-boot-cache-layer-refactor    [2025-12-03]
# 2. angular-standalone-migration        [2025-11-28]
# 3. database-optimization               [2025-11-15]
# ...

# 6. Riprendere sessione diversa:
claude --resume "angular-standalone-migration"

# 7. Eliminare una sessione (se non ti serve più):
/session delete "angular-standalone-migration"

.claude/
├── rules/
│   ├── 00_root.md              # Root rules applicate a tutto
│   ├── frontend/
│   │   ├── 01_typescript.md    # TypeScript + Angular specific
│   │   ├── 02_components.md    # Component structure
│   │   ├── 03_styling.md       # CSS/design system rules
│   │   └── 04_testing.md       # Frontend unit test conventions
│   ├── backend/
│   │   ├── 01_java.md          # Java/Spring Boot specific
│   │   ├── 02_architecture.md  # Clean arch layers
│   │   ├── 03_testing.md       # Backend integration test
│   │   └── 04_database.md      # SQL/schema migrations
│   ├── security/
│   │   ├── 01_secrets.md       # Secret management
│   │   ├── 02_authentication.md # Auth patterns
│   │   └── 03_compliance.md    # GDPR, OWASP
│   ├── devops/
│   │   ├── 01_docker.md        # Dockerfile + compose
│   │   ├── 02_ci_cd.md         # GitHub Actions, pipelines
│   │   └── 03_monitoring.md    # Prometheus, alerts
│   └── shared/
│       ├── 01_git_workflow.md  # Commit, PR, branching
│       ├── 02_documentation.md # Writing standards
│       └── 03_code_style.md    # Immutability, naming
├── settings.json
└── settings.local.json

# TypeScript Rules per Frontend Angular

## Strict Mode
- Abilita sempre `strict: true` in tsconfig.json
- Non usare `any` - preferisci types espliciti o `unknown`
- Niente `Object` come tipo - usa `Record` o type specifico

## Naming Conventions
- **Files:** kebab-case.component.ts, kebab-case.service.ts
- **Classes:** PascalCase (UserComponent, AuthService)
- **Methods/Properties:** camelCase (getUserData, isLoggedIn)
- **Constants:** UPPER_SNAKE_CASE (MAX_RETRIES, API_URL)
- **Privates:** prefisso # oppure private keyword (preferito: #)

## Import Order
1. Angular framework (@angular/*)
2. RxJS (rxjs/*)
3. Third-party libraries
4. Blank line
5. Project modules (@services/*, @models/*)

## Reactive Forms Mandatory
```typescript
// WRONG:
form = new FormGroup({
  email: new FormControl('')
});

// CORRECT:
form = new FormGroup({
  email: new FormControl('', [Validators.required, Validators.email])
});
```

## Change Detection OnPush
```typescript
@Component({
  selector: 'app-user-card',
  template: '...',
  changeDetection: ChangeDetectionStrategy.OnPush  // Sempre questo!
})
```

## No Unsubscribe Pattern
Usa `takeUntil` o `takeUntilDestroyed` (Angular 16+):
```typescript
// AVOID:
subscription = this.service.data$.subscribe(d => this.data = d);

// CORRECT:
private destroy$ = new Subject<void>();
data$ = this.service.data$.pipe(
  takeUntil(this.destroy$)
);
// E nel ngOnDestroy:
ngOnDestroy() { this.destroy$.next(); }
```

# Java / Spring Boot Rules per Backend

## Clean Architecture Layers
Rispetta i 4 livelli:
1. **Domain:** Business rules, entity, port/interface
2. **Application:** Use case, DTO, exception
3. **Infrastructure:** Repository impl, service integration
4. **Presentation:** Controller, filter, advice

Nessuno strato deve dipendere da strati sopra di lui (dipendenze top-down).

## Immutability
- Preferisci record (Java 14+) per DTO e ValueObject
- Se usi class, fai constructor-only assignment, no setters
- Per entity, preferisci builder pattern

```java
// CORRECT:
public record UserCreateRequest(
  String email,
  String password
) {}

// AVOID:
public class UserCreateRequest {
  private String email;
  public void setEmail(String e) { ... }
}
```

## Error Handling
- Crea custom exception per ogni dominio (UserNotFoundException, etc.)
- Lancia sempre con messaggio user-facing + log server-side
- Global exception handler in @RestControllerAdvice

```java
throw new UserNotFoundException(
  "Utente con ID " + userId + " non trovato"
);
// Log automatico nel handler + HTTP 404
```

## Database Transactions
- Usa @Transactional sui service, non su controller
- Read-only transaction per query non modificanti
- Fallback a JDBC/raw SQL solo se JPA insufficiente

## Testing
- Unit test service (mock repo)
- Integration test controller (Testcontainers PostgreSQL)
- Coverage target: 80%+
- Test nome: methodName_scenario_expectedResult()

# Metodo 1: Sintassi &@
> Genera test per tutti i service in src/services/ &@

# Output immediato:
# Background agent started: bg-agent-1729993847
# Use 'claude --attach bg-agent-1729993847' to monitor

# Continui a usare Claude normalmente
> Implementa il nuovo componente UserProfile

# Nel frattempo, l'agente in background genera i test

# Metodo 2: Avvia e monitora
> &@ Refactor 200 file del monorepo
# Ottieni ID agente
# Usa un'altra finestra di terminale:
claude --attach bg-agent-1729993847

# Vedi lo stato in tempo reale

# Metodo 3: Elencare tutti i background agent
claude --list-agents

# Output:
# Background Agents:
# 1. bg-agent-1729993847  [running] 32% - Refactor 200 files
# 2. bg-agent-1729992103  [completed] - Generate tests (132 file)
# 3. bg-agent-1729990001  [failed] - Migration script

# Metodo 4: Attendere il completamento di uno specifico agente
claude --wait bg-agent-1729993847

# Blocca il tuo terminale fino al completamento dell'agente

# Terminal 1: Avvia background agent
claude
> &@ Genera unit test con Jasmine per tutti i 87 service in src/app/services/
> Ogni test deve coprire: metodo principale, error handling, mock HTTP
> File output: {serviceName}.spec.ts nello stesso dir del service

# Output:
# Background Agent started: bg-test-gen-001
# Estimated time: 40-60 minutes
# You can now return to work in this or another terminal

# Terminal 1: Continua lavoro
> /clear
> @src/app/pages/user-profile.component.ts
> Implementa il form di editing profilo con validazione

# Terminal 2 (opzionale): Monitora l'agente in background
claude --attach bg-test-gen-001
# Vedi progresso in tempo reale

# Dopo 45 minuti, Terminal 2 mostra:
# Background Agent COMPLETED
# Generated 87 test files
# Total lines: 12,340
# Coverage: 83%
# Time elapsed: 47 minutes 23 seconds

# Torna a Terminal 1, continua il tuo lavoro
# I test sono già generati e salvati sul filesystem

# Metodo 1: Comando slash
> /model claude-sonnet-4-20250514
# Switching from claude-opus-4 to claude-sonnet-4
# Model changed successfully. Contesto preservato.

# Metodo 2: Shortcut Alt+P (Option+P su macOS)
# Apre un dropdown dei modelli disponibili, seleziona uno, applica

# Metodo 3: Visualizzare modello corrente
> /status
# Output:
# Session: spring-boot-cache-layer-refactor
# Current Model: claude-opus-4-20250514
# Context Window: 47,382 / 200,000 tokens (23.7%)
# Files Loaded: 12
# Checkpoint: 4 available

# Modelli disponibili (a seconda del piano):
# - claude-haiku-4-20250904        (fastest, cheapest, 200k context)
# - claude-sonnet-4-20250514       (balanced, 200k context)
# - claude-opus-4-20250514         (strongest, 200k context)
# - claude-opus-4-mini-20250903    (mid-tier, 200k context, new!)

# Status line in fondo al terminale Claude Code:

[2025-12-05 15:32:18] Model: claude-opus | Context: 67,234/200,000 (33.6%) | Files: 15 | Checkpoint: 3

# Cosa significa:
# - Modello corrente: claude-opus-4-20250514
# - Token usati: 67,234 su 200,000 disponibili
# - Percentuale: 33.6% - sei a metà strada
# - File nel contesto: 15
# - Checkpoint salvati: 3

# Se scende sotto il 10%, Claude ti avverte:
# ⚠️ WARNING: Context window usage > 90%
# Consider: /clear + /add file specifici, o /checkpoint restore

# Avvio sessione per refactor complesso (3 giorni di lavoro)
claude --session "monorepo-major-refactor"

# Primi step: pianificazione e design (reasoning critico)
> /model claude-opus-4-20250514
> [Plan Mode] Crea un piano dettagliato per refactorare i 50 service

# Claude usa Opus, analizza architettura, produce piano
# Status: Context 42,000/200,000 (21%)

# Phase 2: Implementazione routine (Sonnet efficiente)
> /model claude-sonnet-4-20250514
> Implementa i primi 10 service seguendo il piano

# Status: Context 78,000/200,000 (39%)
# Tempo: ridotto perché Sonnet è più veloce

# Phase 3: Testing e debug
> /model claude-haiku-4-20250904
> Genera test per i 10 service implementati

# Status: Context 95,000/200,000 (47.5%)
# Costo: minimo, task semplice

# Status del contesto è sotto 50%, puoi continuare
# Phase 4: Refactor avanzato (torna a Opus)
> /model claude-opus-4-20250514
> Torna indietro al checkpoint "10-services-done"
> Implementa i prossimi 20 service con refactoring conservativo

# SWITCH intelligente basato su criticità del task = minimizzare cost

# Nel CLI:
> Aggiungi validazione [TAB]

# Claude suggerisce automaticamente:
# Suggerimenti contestuali:
# 1. Aggiungi validazione email al form di registrazione
# 2. Aggiungi validazione numero di telefono
# 3. Aggiungi validazione password (strength check)
# 4. Aggiungi validazione IBAN

# Premi freccia su/giù per navigare, Enter per selezionare
# Oppure digita le prime lettere del numero

# Nel VS Code Extension (sidebar Claude):
# Digita: "Genera..."
# Tab mostra:
# 1. Genera test per questo file
# 2. Genera documentazione API
# 3. Genera changelog entry
# 4. Genera seed data

# Tab copia il suggerimento, puoi modificare prima di inviare

# 1. Avvia sessione nominata
claude --session "major-refactor-2025-12-05"

# 2. Accedi VSCode Extension (Ctrl+L), carica file radice
# Drag-drop CLAUDE.md + package.json + pom.xml nella sidebar

# 3. Attiva Plan Mode e usa Opus per il planning
> [Shift+Tab+Tab] Crea piano dettagliato per refactorare 50 servizi
> Il piano deve coprire 3 giorni di lavoro, include test, commit strategy

# Claude (Opus) genera piano di 2000 righe
# Status: Context 45,000 / 200,000 (22.5%)

# 4. Salva checkpoint per il piano
> /checkpoint save "day1-planning-complete"

# 5. Rinomina il piano in file:
> Salva il piano in docs/refactor-plan-2025-12-05.md

# End of Day 1
> /session rename "major-refactor-planning-done"

# 1. Riprendi sessione
claude --resume "major-refactor-planning-done"

# 2. Passa a Sonnet per implementazione routine
> /model claude-sonnet-4-20250514

# 3. Avvia background agent per i primi 20 servizi
> &@ Refactor i primi 20 servizi seguendo il piano
> Includi: rinominare, aggiornare test, aggiornare import

# Background agent avviato: bg-refactor-1
# Continua il tuo lavoro mentre Claude lavora in background

# 4. Nel frattempo, refactor manuale file critici con VS Code Extension
# Usa Sidebar, drag-drop file singoli, fai diff review prima di accept

# 5. Monitora progresso
claude --attach bg-refactor-1
# Vedi: 12/20 servizi completati... 15/20... 20/20 DONE

# 6. Checkpoint al completamento dei primi 20
> /checkpoint save "20-services-refactored"

# 7. Continua con i prossimi 20 in background
> &@ Refactor i servizi 21-40 seguendo il piano
# bg-refactor-2 avviato

# End of Day 2
> /session rename "major-refactor-40-services-done"

# 1. Riprendi sessione
claude --resume "major-refactor-40-services-done"

# 2. Ultimi 10 servizi + testing integrazione
> /model claude-opus-4-20250514  # Torna a Opus per quality

# 3. Refactor ultimi 10 servizi
> Refactor i servizi finali 41-50
> Run test suite - se failures, debug e fix

# 4. Salva checkpoint "all-50-refactored"
> /checkpoint save "all-50-services-complete"

# 5. Full regression test
> /model claude-haiku-4-20250904  # Torna a Haiku per test routine
> Genera uno smoke test che verifica tutti i 50 servizi in azione

# 6. Code review finale (Opus reasoning)
> /model claude-opus-4-20250514
> Fai una code review completa di tutti i 50 file refactorizzati
> Cerca: error handling inconsistency, missing JSDoc, stile code

# 7. Genera changelog
> /model claude-haiku-4-20250904
> Genera un CHANGELOG entry con tutti i cambiamenti

# 8. Final checkpoint
> /checkpoint save "refactor-complete-ready-for-pr"

# End of Day 3
> Completed! Tutto pronto per PR. Summary:
# - 50 servizi refactorizzati
# - 50 test file aggiornati
# - 0 broken imports
# - CHANGELOG generato
# - Code review completo eseguito