Il problema più difficile nella modernizzazione di un'applicazione legacy non è necessariamente convertire il codice.
È capire che cosa l'applicazione faccia realmente.
Il 30 settembre 2026 Esri ha pubblicato Rethinking Application Migrations, mostrando un approccio particolarmente interessante alla modernizzazione di applicazioni basate su ArcGIS Maps SDK for JavaScript.
Il caso utilizzato è il Building Viewer, migrato da uno stack basato su Dojo e Grunt verso:
- Vite;
- TypeScript;
@arcgis/core;- ArcGIS Maps SDK for JavaScript Components;
- tooling moderno basato su
@arcgis/create.
La motivazione immediata è tecnologica: con l'evoluzione del Maps SDK for JavaScript e la progressiva transizione dai tradizionali widget ai componenti nel percorso verso ArcGIS Maps SDK for JavaScript 5.x, alcune applicazioni richiederanno qualcosa di più profondo di un aggiornamento delle dipendenze.
Ma l'aspetto più interessante dell'esperimento Esri non è lo stack di destinazione.
È il processo di migrazione.
Legacy Application
|
v
Static Code Inspection
+
Runtime Exploration
|
v
Behavioral Discovery
|
v
Verified PRD
|
v
Modern Application Generation
|
v
Runtime / Visual Validation
|
v
Architecture & Code ReviewIn altre parole:
non chiedere all'AI di tradurre il vecchio codice. Chiedile prima di ricostruire il contratto comportamentale dell'applicazione.
Ed è una differenza architetturale enorme.
Refactoring e re-platforming non sono la stessa cosa
Esri fa una distinzione importante.
Se dobbiamo semplicemente aggiornare una normale applicazione ArcGIS:
ArcGIS Maps SDK 4.x
|
+-- aggiornare una minor version
+-- sostituire qualche API
+-- modificare alcuni widget
|
v
same application architectureun aggiornamento incrementale può essere perfettamente ragionevole.
Il problema cambia quando contemporaneamente cambiano:
- SDK;
- framework;
- build system;
- architettura UI;
- component model;
- dependency model;
- development patterns.
Nel caso Building Viewer il salto era sostanzialmente:
Dojo
Grunt
legacy ArcGIS widgets
legacy application patterns
|
v
Vite
TypeScript
ArcGIS Components
modern Maps SDK patternsIn un caso di questo tipo, trascinare progressivamente il vecchio software attraverso una lunga sequenza di upgrade può essere meno conveniente che ricostruire l'applicazione partendo dai requisiti verificati.
Questo introduce una distinzione fondamentale:
CODE MIGRATION
legacy implementation
|
v
transformed implementation
BEHAVIORAL MIGRATION
observable behavior
|
v
formal specification
|
v
new implementationNel secondo caso il vecchio codice non è più il progetto della nuova applicazione.
Diventa una delle fonti di evidenza utilizzate per ricostruirne le specifiche.
Il legacy diventa un sistema da osservare
Tradizionalmente, quando dobbiamo migrare un'applicazione, iniziamo dal repository:
repository
|
+-- source
+-- dependencies
+-- configuration
+-- build
+-- documentationMa un'applicazione reale contiene conoscenza che non è necessariamente evidente dal codice.
Per esempio:
source code
configuration
runtime state
external services
ArcGIS Portal items
WebMap / WebScene
user interaction
browser behavior
CSS / layout
historical workaroundsIl comportamento effettivo dell'applicazione è quindi qualcosa di più simile a:
Application Behavior =
Code
+ Configuration
+ Runtime
+ Data
+ External Services
+ UI State
+ User InteractionEd è qui che entra in gioco il coding agent.
Nel workflow Esri l'agente non deve limitarsi a leggere JavaScript e TypeScript.
Deve eseguire realmente l'applicazione.
Browser automation come strumento di reverse engineering
Esri utilizza un browser integrato e Playwright per esplorare l'applicazione legacy.
L'agente deve:
- avviare l'applicazione;
- navigarne le funzionalità;
- attivare controlli e workflow;
- osservare gli stati della UI;
- verificare il comportamento della mappa;
- catturare screenshot;
- correlare quello che osserva con il sorgente;
- individuare risorse ArcGIS e configurazioni esterne.
Gli screenshot diventano quindi qualcosa di molto più importante della semplice documentazione.
Diventano evidence artifacts.
Requirement
|
+-- source evidence
+-- runtime evidence
+-- screenshot evidence
+-- configuration evidenceIl PRD risultante non descrive soltanto ciò che il codice sembra voler fare.
Descrive ciò che l'applicazione effettivamente fa.
Il PRD come Behavioral Contract
Prima di generare qualsiasi nuova applicazione, Esri fa produrre all'agente un vero Product Requirements Document.
Il prompt impone una regola particolarmente importante: documentare il comportamento esistente senza proporre subito nuove tecnologie, redesign, miglioramenti o nuove architetture.
Inoltre l'agente deve distinguere chiaramente ciò che è stato verificato da ciò che è soltanto dedotto oppure non determinabile.
Questo trasforma il PRD in qualcosa che, dal punto di vista architetturale, possiamo definire:
Behavioral Contracttra:
legacy implementation
|
v
PRD
|
v
new implementationIl nuovo sistema non deve necessariamente replicare l'implementazione.
Deve soddisfare il contratto comportamentale.
Verified, Assumption, Unknown
Una delle scelte più intelligenti è evitare che l'LLM presenti ogni deduzione come un fatto.
Nel PRD reale del Building Viewer Esri distingue categorie quali:
Verified
Specified correction
Assumption
UnknownQuesta distinzione è estremamente importante nell'uso professionale degli agenti.
Un modello potrebbe facilmente trasformare:
inferencein:
requiremente successivamente trasformare quel requisito inventato in codice perfettamente funzionante.
Il risultato sarebbe tecnicamente corretto ma funzionalmente sbagliato.
La provenance dell'informazione deve quindi diventare parte della specifica.
Una possibile estensione enterprise potrebbe essere:
Requirement R-042
Behavior:
Selecting floor 2 filters the building.
Evidence:
[x] Source inspection
[x] Runtime verification
[x] Screenshot
[x] ArcGIS service query
Confidence:
VERIFIED
Dependencies:
WebScene: ...
Layer: ...
Field: BldgLevel
Validation:
Playwright test BV-FLOOR-002A questo punto il PRD comincia ad assomigliare più a una specifica eseguibile che a un normale documento di progetto.
Il Data & Configuration Inventory è fondamentale nel GIS
Qui il caso ArcGIS diventa particolarmente interessante.
Un'applicazione GIS raramente è contenuta interamente nel repository.
Una parte importante dell'architettura può vivere dentro:
ArcGIS Online / Enterprise
|
+-- WebMap
+-- WebScene
+-- FeatureLayer
+-- SceneLayer
+-- ElevationLayer
+-- Portal Items
+-- Renderers
+-- Popups
+-- Expressions
+-- Service ConfigurationPer questo Esri chiede esplicitamente all'agente di costruire un Data & Configuration Inventory.
Nel PRD del Building Viewer vengono inventariati elementi quali:
- Portal;
- WebScene ID;
- URL REST;
- spatial reference;
- elevation source;
- SceneServer;
- FeatureServer;
- layer ID;
- visibility;
- definition expression;
- configurazioni applicative;
- risorse esterne.
Il documento arriva quindi a ricostruire relazioni funzionali come:
UI floor
|
v
level_id
|
v
FeatureLayer filteroppure:
UI floor
|
v
BldgLevel
|
v
BuildingSceneLayer filteringQuesta è una lezione importante per qualsiasi migrazione GIS:
il repository Git non coincide con il sistema.
Il sistema reale è piuttosto:
Git repository
+
Portal configuration
+
WebMap / WebScene JSON
+
REST services
+
external data
+
runtime behaviorUn agente che analizzi soltanto il repository vede quindi soltanto una parte dell'architettura.
Dal PRD alla nuova applicazione
Solo dopo questa fase Esri passa alla generazione.
La nuova applicazione viene creata utilizzando @arcgis/create con Vite e uno stack moderno,
mantenendola separata dal progetto originale.
Legacy App
|
| discovery
v
PRD
|
| generation
v
Clean Project
|
v
Modern SDKQuesto riduce un problema tipico delle migrazioni automatiche: la legacy contamination.
Se chiedessimo semplicemente:
convert this Dojo application to modern TypeScriptil modello potrebbe produrre:
legacy architecture
+
TypeScript syntax
+
modern buildottenendo un'applicazione apparentemente moderna, ma concettualmente ancora legacy.
Widget thinking vs Component thinking
Questo problema è particolarmente evidente nel Maps SDK.
Un agente può facilmente ricadere nei pattern che ha già visto più spesso, per esempio:
- vecchi widget;
- classi legacy;
- codice custom che reinventa funzionalità già presenti nei nuovi componenti;
- pattern di inizializzazione appartenenti a versioni precedenti dell'SDK.
Esri non ha risolto il problema continuando ad allungare il prompt della singola conversazione.
Ha modificato le istruzioni persistenti del repository.
Ed è probabilmente una delle parti più interessanti dell'intero esperimento.
.github/copilot-instructions.md come Architecture Policy
Nel repository Building Viewer è presente:
.github/copilot-instructions.mdIn altri ambienti lo stesso concetto può essere rappresentato da:
AGENTS.mdIl file contiene conoscenza persistente relativa al progetto.
Non:
"correggi questo componente"ma:
"questo è il modo corretto di sviluppare in questo repository"Le istruzioni possono stabilire, per esempio:
- quali versioni di
@arcgis/coree@arcgis/map-componentsutilizzare; - quali pattern non devono più essere introdotti;
- quando preferire i Map Components;
- come validare il codice;
- quali requisiti di sicurezza rispettare.
Quindi:
Prompt
= task context
copilot-instructions.md
= architectural contextÈ una distinzione fondamentale.
Architecture as Instructions
Da un punto di vista enterprise, possiamo spingere questo concetto molto più avanti.
Un repository potrebbe contenere:
AGENTS.md
architecture/
principles.md
security.md
arcgis-patterns.md
testing.md
observability.mdcon regole come:
DO use ArcGIS Components
DO NOT use deprecated widgets
DO NOT place secrets in browser code
DO validate browser console
DO execute type checking
DO verify against screenshots
DO inspect ArcGIS service metadata
DO keep changes scopedL'agente non riceve quindi soltanto una richiesta.
Riceve una policy architetturale versionata insieme al codice.
Possiamo quasi considerarla:
Architecture Policy as CodeCorreggere l'agente, non soltanto il codice
Questo cambia anche il modo di lavorare quando l'AI commette ripetutamente lo stesso errore.
Workflow ingenuo:
Agent generates wrong pattern
|
v
developer fixes prompt
|
v
agent generates another wrong pattern
|
v
developer fixes prompt againWorkflow più maturo:
Agent generates wrong pattern
|
v
identify systemic misconception
|
v
update AGENTS.md / copilot-instructions
|
v
future generations inherit correctionIn pratica il feedback non modifica soltanto l'output.
Modifica il sistema che produce gli output successivi.
Questo assomiglia molto più alla gestione di una engineering organization che al normale prompting.
Visual validation non significa semplicemente pixel comparison
Dopo la generazione Esri confronta vecchia e nuova applicazione utilizzando browser e screenshot.
Ma in una GIS application la validazione visuale deve essere interpretata con attenzione.
Una schermata apparentemente identica può nascondere differenze sostanziali:
camera position
zoom
layer visibility
definitionExpression
renderer
popup behavior
hitTest
floor filtering
WebScene state
service errors
console errorsPer questo una pipeline realmente robusta dovrebbe combinare:
Visual Validation
+
Functional Validation
+
GIS State Validation
+
Network Validation
+
Console ValidationPer esempio:
Playwright
|
+-- click Floor 2
+-- capture screenshot
+-- inspect visible controls
+-- verify selected state
+-- inspect browser console
+-- inspect failed requests
+-- verify expected layer filterQui l'AI agent non sostituisce i test.
Può diventare il coordinatore dei diversi strumenti di verifica.
Una possibile pipeline CI/CD
Il pattern mostrato da Esri può essere ulteriormente industrializzato.
LEGACY APPLICATION
|
v
+--------------------+
| Discovery Agent |
+--------------------+
| | |
v v v
Code Browser ArcGIS REST
\ | /
\ | /
v v v
VERIFIED PRD
|
v
Architecture Rules
|
v
Generation Agent
|
v
New Application
|
+------------+------------+
| | |
v v v
Build Playwright Security
Typecheck Tests Checks
| | |
+------------+------------+
|
v
Visual Regression
|
v
Human Review Gate
|
v
DeployA questo punto non stiamo più parlando semplicemente di Copilot.
Stiamo parlando di una agentic application-modernization pipeline.
Il ruolo della sicurezza
Il file di istruzioni utilizzato da Esri contiene anche indicazioni esplicite sulla sicurezza.
Un punto fondamentale per le applicazioni JavaScript è il seguente: una API key utilizzata dal browser è necessariamente disponibile al client.
Inserirla in una build-time environment variable può evitare di commetterla direttamente nel repository, ma non trasforma il bundle JavaScript in un secret store.
OAuth client secret, credenziali applicative e token confidenziali devono invece rimanere fuori da:
- browser;
- bundle;
- log;
- commit;
- prompt e contesto dell'assistente.
Questo diventa ancora più importante con gli agenti.
Un discovery agent potrebbe infatti avere accesso contemporaneamente a:
repository
environment
browser
network
configuration
logs
PortalIl modello di sicurezza dovrebbe quindi ragionare esplicitamente su:
Agent permissions
|
+-- filesystem scope
+-- repository scope
+-- browser scope
+-- network scope
+-- credentials
+-- Portal privileges
+-- command executionIl principio dovrebbe essere sempre:
least privilege
+
isolated environment
+
auditable actions
+
human approval for sensitive operationsAttenzione: il PRD può diventare il nuovo single point of failure
Il workflow è potente, ma introduce anche un rischio interessante.
Legacy
|
v
PRD
|
v
New ApplicationUn errore nel PRD può propagarsi direttamente nella nuova implementazione.
Il problema quindi si sposta:
prima:
"il codice generato è corretto?"
dopo:
"la specifica generata è corretta?"È probabilmente comunque un miglioramento, perché una specifica è più semplice da revisionare rispetto a migliaia di righe di codice.
Ma il PRD deve essere trattato come un artefatto critico:
PRD
|
+-- machine generated
+-- evidence linked
+-- human reviewed
+-- version controlled
+-- test traceableRequirement → Evidence → Test
L'evoluzione naturale del pattern Esri potrebbe essere la completa tracciabilità:
Requirement
|
v
Evidence
|
v
Generated implementation
|
v
Automated testPer esempio:
REQ-GIS-017
"When floor 3 is selected,
only floor 3 content is visible."
|
+-- source evidence
+-- runtime screenshot
+-- service configuration
|
v
Playwright test
|
v
ArcGIS runtime assertionAvremmo quindi una vera catena:
Legacy behavior
|
v
Evidence
|
v
Requirement
|
v
Implementation
|
v
Test
|
v
ValidationEd è probabilmente qui che l'agentic software engineering diventa realmente interessante per applicazioni enterprise.
Non è solo un pattern ArcGIS
Sebbene Esri lo mostri sul Building Viewer, il modello è molto più generale.
Potrebbe funzionare altrettanto bene per:
- ASP.NET WebForms → Blazor;
- AngularJS → Angular;
- jQuery → React;
- ArcGIS JavaScript legacy → ArcGIS Components;
- old Java application → modern services;
- desktop client → web application.
La condizione fondamentale è che il sistema legacy sia ancora sufficientemente eseguibile da poter essere osservato.
In questo caso il runtime stesso diventa una forma di documentazione.
Dal source-driven development all'evidence-driven modernization
È forse questo il cambiamento concettuale più interessante.
Tradizionalmente:
Source Code
|
v
MigrationCon questo modello:
Source Code
|
Runtime ----------+
|
Configuration ----+
|
External Data ----+
|
Screenshots ------+
|
v
Evidence
|
v
Behavioral Model
|
v
New SystemLa migrazione diventa quindi evidence-driven.
E questo può essere particolarmente efficace nei sistemi con dieci o quindici anni di storia, dove il codice racconta soltanto una parte della verità.
Una conseguenza interessante per ArcGIS Enterprise
Nel mondo ArcGIS questo approccio potrebbe diventare ancora più potente.
Un discovery agent specializzato potrebbe interrogare automaticamente:
Portal REST API
ArcGIS Server REST
WebMap JSON
WebScene JSON
FeatureServer
MapServer
SceneServer
ImageServere costruire un dependency graph:
Application
|
+-- WebMap
| |
| +-- FeatureLayer
| +-- MapImageLayer
|
+-- WebScene
| |
| +-- SceneLayer
| +-- ElevationLayer
|
+-- OAuth Application
|
+-- External APIA quel punto il PRD potrebbe essere affiancato da una vera:
GIS Application Dependency Graphutilizzabile non soltanto per la migrazione, ma anche per:
- impact analysis;
- security assessment;
- dependency auditing;
- upgrade planning;
- disaster recovery;
- documentazione automatica;
- individuazione di servizi legacy.
La lezione architetturale
L'aspetto più interessante di Rethinking Application Migrations non è il fatto che Esri abbia usato GitHub Copilot o uno specifico frontier model.
Il workflow è in larga misura indipendente dal modello.
Contano soprattutto:
- contesto;
- istruzioni;
- strumenti;
- evidenze;
- validazione.
La vera innovazione è il cambio di astrazione:
"convert this code"diventa:
"understand this system"
|
v
"prove what you understood"
|
v
"formalize its behavior"
|
v
"rebuild it with modern primitives"
|
v
"prove that the new system behaves correctly"Ed è una differenza enorme.
Il coding agent smette di essere soltanto un generatore di codice.
Diventa contemporaneamente:
reverse engineer
requirements analyst
browser operator
developer
tester
architecture assistantmentre l'architect mantiene la responsabilità delle decisioni, delle policy e dei criteri di accettazione.
Conclusione
Il pattern mostrato da Esri può essere riassunto così:
Legacy App
|
v
Runtime Discovery
|
v
Evidence Collection
|
v
Verified Behavioral PRD
|
v
Architecture Instructions
|
v
Clean Reimplementation
|
v
Visual + Functional Validation
|
v
Human ReviewNon è semplicemente un modo più veloce di riscrivere una vecchia applicazione.
È un possibile modello per la modernizzazione agentica del software.
E per il mondo GIS è particolarmente interessante, perché una ArcGIS application non è quasi mai soltanto il suo codice: è codice, configurazione, Portal items, servizi REST, dati, WebMap, WebScene e comportamento runtime.
La vera domanda per un coding agent, quindi, non dovrebbe più essere:
“Riesci a convertire questa applicazione?”
ma:
“Riesci prima a dimostrare di aver capito esattamente che cosa questa applicazione fa?”
Solo dopo ha senso lasciargli scrivere quella nuova.
Fonte principale:
Esri — Rethinking Application Migrations, 30 settembre 2026
https://www.esri.com/arcgis-blog/products/js-api-arcgis/geoai/rethinking-application-migrations
Building Viewer — PRD:
https://github.com/Esri/building-viewer/blob/main/prd/PRD.md
Repository instructions:
https://github.com/Esri/building-viewer/blob/main/.github/copilot-instructions.md
Nessun commento:
Posta un commento