Guidelines sviluppo tool
Criteri, convenzioni e checklist per creare o estendere tool Yellow.
Creare o estendere?
Nuovo tool
- Dominio ben definito - il problema ha confini chiari e non si sovrappone con tool esistenti
- Utenti specifici - serve un gruppo di utenti con workflow distinto
- Complessita' sufficiente - richiede UI dedicata, non basta un'estensione minimale
- Dati separati - il data model e' sostanzialmente diverso
- Ciclo di vita indipendente - puo' evolvere senza impattare altri tool
Estensione
- Stessi utenti - gli utenti target gia' usano il tool quotidianamente
- Dati condivisi - le nuove feature leggono/scrivono sulle stesse entita'
- Workflow collegato - la nuova funzionalita' e' un passo naturale nel flusso
- Bassa complessita' - una pagina o sezione aggiuntiva basta
- Context switching - separare forzerebbe gli utenti a saltare tra tool
Checklist nuovo tool
- 1Definire utenti target e casi d'uso principali
- 2Verificare che non sia meglio estendere un tool esistente
- 3Scegliere stack (Next.js fullstack o FastAPI + React/Vite)
- 4Scegliere colore logo e generarlo con il Favicon Generator
- 5Impostare design system condiviso (OKLCH, font, radius, shadcn/ui)
- 6Impostare Makefile con target standard
- 7Aggiungere il tool al catalogo Hub
- 8Documentare in docs/ con almeno ARCHITECTURE e DESIGN_SYSTEM
Convenzioni obbligatorie
| Soft delete | Mai hard delete, sempre deleted_at timestamp |
| pnpm | Per frontend, mai npm o yarn |
| uv | Per backend Python, mai pip diretto |
| Tailwind v4 | CSS-first con @theme, niente tailwind.config.ts |
| TypeScript strict | Sempre abilitato |
| shadcn/ui | Per componenti base (Radix) |
| Font | Manrope (heading), Figtree (body), Geist Mono (code) |
| Line length | 100 caratteri |
| Import alias | @/ per import assoluti |
| UI lingua | Italiano per UI, inglese per codice e variabili |
Scelta stack
| Criterio | Next.js | FastAPI + Vite |
|---|---|---|
| Backend semplice (CRUD) | Si | Overkill |
| Backend complesso (workers, ML) | No | Si |
| SSR/SEO | Si | No |
| Background jobs | No | Si |
| Coerenza con Allocation | Si | - |