📘 Istruzioni per Claude — v3.0

Guida completa per aggiornare, creare e gestire i progetti su sviluppo.mclmedia.eu

1. Cos'è Sviluppo Hub

Sviluppo Hub è il portale centralizzato di MCL Media SRL dove vengono tracciati tutti i progetti in corso. Ogni progetto è un file JSON nella cartella /projects/. Il portale mostra una dashboard con KPI, stato di avanzamento, task completate e prossimi step per ogni progetto.

Questo portale viene aggiornato dagli agenti Claude a fine sessione. Il proprietario è Luca Macaluso.

2. Il nuovo flusso operativo (v3.0)

I 6 tasti della Claude Bar

🚀 Copia Brief + ToDo — Per iniziare una NUOVA conversazione. Copia il brief narrativo + task pendenti + scadenze. Non contiene JSON crudo, solo testo leggibile.

📋 Copia JSON Completo — Per fine sessione. Include il JSON completo del progetto + istruzioni dettagliate per Claude con le 5 Regole Anti-Caos.

✅ Copia Solo Tasks — Per aggiornare solo le task senza toccare il resto del progetto.

📥 Incolla JSON — Area dove incollare il JSON che Claude restituisce.

📄 Copia README / 📝 Incolla README — Per la documentazione tecnica completa del progetto.

3. Il campo "brief" — Il cuore del v3

Ogni progetto ha ora un campo brief nel JSON. È un paragrafo narrativo in italiano (200-500 parole) che spiega:

→ Cos'è il progetto e a cosa serve
→ A che punto siamo (percentuale, cosa manca)
→ Cosa abbiamo fatto nell'ultima sessione
→ Decisioni prese e perché
→ Qual è il prossimo step concreto

Il brief viene aggiornato automaticamente ogni volta che Claude genera il JSON completo a fine sessione. Può anche essere modificato manualmente dalla pagina progetto (tasto ✏️ nel pannello Brief).

4. Le 5 Regole Anti-Caos

Queste regole sono incorporate automaticamente nel prompt "Copia JSON Completo". Claude DEVE rispettarle:

1. NON aggiungere task che Luca non ha esplicitamente detto di voler fare. Se in conversazione è emersa una possibilità, non è una task. Solo ciò che è stato concordato.

2. NON trasformare ogni frase in una deadline. Solo date esplicite ("entro venerdì", "per il 20 marzo") diventano deadline.

3. Le deadline devono avere una data ESPLICITA. "Sarebbe bello fare X" NON è una deadline. "Devo fare X entro il 25" SÌ.

4. Il changelog deve avere entry AGGREGATE. "Implementato sistema X con Y e Z" — non una riga per ogni file toccato. Max 3-5 entry per sessione.

5. Il brief è il campo PIÙ IMPORTANTE. Deve essere perfetto e autosufficiente.

5. File e upload per progetto

Ogni progetto può avere file allegati (zip, PDF, immagini, codice). I file vengono salvati in /files/{slug}/ e sono scaricabili dalla pagina progetto.

Casi d'uso: zip del codice sorgente, export database, screenshot, documenti di design, business plan, contratti.

6. GitHub integration

Se un progetto ha un repository GitHub, aggiungere il campo "github_repo": "https://github.com/..." al JSON. Il portale mostrerà un link diretto al repo nella pagina progetto.

A cosa serve GitHub per MCL Media:

→ Versioning: storia completa di tutte le modifiche al codice (chi ha cambiato cosa e quando)
→ Backup: il codice non vive solo sul server, hai una copia sicura
→ Collaborazione: se Alessandro o altri devono vedere il codice, non serve accesso SSH
→ Rollback: se un deploy rompe qualcosa, puoi tornare alla versione precedente in 2 secondi
→ Webhook: possibilità futura di auto-aggiornare il changelog del gestionale ad ogni push

7. API REST (per aggiornamenti da script)

L'API è ancora disponibile per aggiornamenti automatizzati via curl/script. Base URL: sviluppo.mclmedia.eu/api/update.php

Endpoint disponibili: list, read, update, create, add_log, update_tasks, update_deadlines, update_brief, list_files.

Esempio: aggiornare il brief via API

curl -X POST "https://sviluppo.mclmedia.eu/api/update.php?action=update_brief&project=travel-hub" \
  -H "Content-Type: application/json" \
  -d '{"brief": "Il Travel Hub è la rete di siti turistici italiani..."}'

8. Progetti attivi e relativi slug

9. Formato JSON completo di un progetto (v3)

{
  "name": "Nome Progetto",
  "description": "Descrizione breve",
  "icon": "🎬",
  "icon_bg": "rgba(239,68,68,0.15)",
  "status": "attivo | in_sviluppo | pianificato | in_pausa | completato | critico",
  "priority": "alta | media | bassa",
  "progress": 0-100,
  "owner": "Luca",
  "tags": ["tag1", "tag2"],
  "brief": "Paragrafo narrativo autosufficiente che spiega il progetto, lo stato attuale, cosa è stato fatto, decisioni prese, e prossimo step. 200-500 parole.",
  "github_repo": "https://github.com/... (opzionale, stringa vuota se non presente)",
  "info": {"chiave": "valore"},
  "tech_stack": ["PHP", "Laravel"],
  "links": [{"label": "Nome", "url": "https://...", "icon": "🔗"}],
  "tasks": [
    {"text": "Task completata", "done": true},
    {"text": "Task da fare", "done": false}
  ],
  "deadlines": [
    {"text": "Scadenza con data esplicita", "date": "2026-03-20"}
  ],
  "changelog": [
    {"date": "2026-03-18 12:00", "text": "Cosa è successo (entry aggregata)", "type": "milestone", "agent": "claude"}
  ],
  "notes": "Note operative dettagliate",
  "created_at": "auto",
  "updated_at": "auto"
}

10. Struttura file del portale (v3)

sviluppo.mclmedia.eu/
├── index.php                  ← Dashboard + dettaglio progetto (v3: Claude Bar, Brief, File Manager)
├── config.php                 ← Helper functions PHP (v3.0.0)
├── aggiorna-progetti.php      ← Pagina batch update (legacy, ancora funzionante)
├── nuovo-progetto.php         ← Creazione guidata nuovo progetto (v3: brief + github)
├── istruzioni-claude.php      ← Questa pagina
├── api/
│   ├── update.php             ← API REST (v3: + update_brief, list_files)
│   └── events.php             ← API completamento eventi/deadlines
├── files/                     ← 🆕 Upload file per progetto (files/{slug}/)
├── data/
│   └── completed-events.json
├── daily/
│   └── agenda.php
├── widgets/
│   ├── daily-focus.php
│   ├── fires-panel.php
│   └── server-status-bar.php
└── projects/
    ├── *.json                 ← JSON progetto (v3: + brief, github_repo)
    └── readme-*.md            ← README per progetto