davideandClaude Sonnet 5.5
3587f35c2d
Le formule `$…$` e `$$…$$` si disegnano con CSharpMath (ADR-0008), con ripiego sul sorgente se il LaTeX non è valido. I documenti e i nomi dei test non citano più esempi di un solo dominio. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
58 lines
4.7 KiB
Markdown
58 lines
4.7 KiB
Markdown
# Documentazione
|
|
|
|
Indice e regole. Ogni informazione vive in **un solo documento**; gli altri la richiamano con un link.
|
|
|
|
| Documento | Contenuto (sorgente di verità per…) |
|
|
|---|---|
|
|
| [../README.md](../README.md) | Uso, requisiti, build e publish |
|
|
| [PROJECT_STATE.md](PROJECT_STATE.md) | Stato del progetto a colpo d'occhio: stadio (MVP), stato per area, debiti, decisioni, cosa manca per chiudere l'MVP |
|
|
| [MVP.md](MVP.md) | Specifica funzionale, design UI/UX, criteri di accettazione |
|
|
| [INSTALL.md](INSTALL.md) | Come installare e autenticare i motori (Claude Code, Codex), verifica e problemi comuni |
|
|
| [TESTING.md](TESTING.md) | Piano dei test: regola "nuova funzione = nuovi test", soglie di copertura, matrice requisito → test |
|
|
| [ROADMAP.md](ROADMAP.md) | Fasi e stato (spunte); solo passi, mai motivazioni |
|
|
| `adr/NNNN-*.md` | Decisioni architetturali e loro motivazioni (indice sotto) |
|
|
| [../AGENT.md](../AGENT.md) | Istruzioni per gli agenti di codice (Claude Code, Gemini CLI, altri): comandi, architettura del codice, vincoli. Unica sorgente; `CLAUDE.md` e `GEMINI.md` sono solo puntatori |
|
|
|
|
## Nome del progetto
|
|
Il nome è **`agent-wiki-ui`** (prima `LlmRun`). Questa sezione è l'unica sorgente: gli altri doc scrivono "l'app" o `<nome-app>`.
|
|
|
|
Se il nome cambia di nuovo, aggiornare solo questi punti:
|
|
- [ ] `AssemblyName` in [../src/agent-wiki-ui/agent-wiki-ui.csproj](../src/agent-wiki-ui/agent-wiki-ui.csproj) (e il nome del file csproj): da lì il codice legge il nome (`Core/AppInfo.cs`) per titolo finestra, intestazione della barra laterale e cartella dati; l'eseguibile diventa `<nome-app>.exe` / `<nome-app>`
|
|
- [ ] `RootNamespace` e namespace C# (`AgentWikiUi.*`, anche in `x:Class` e `xmlns` dei file `.axaml`): il nome del namespace non può avere trattini
|
|
- [ ] **Cartella dati** `<LocalApplicationData>/<nome-app>/chats`: cambiando nome le chat salvate non si trovano più. `ChatStore` sposta una vecchia cartella (`LlmRun`) in quella nuova al primo avvio; per un nuovo cambio aggiungere il nome precedente all'elenco `LegacyNames`
|
|
- [ ] Titolo di [../README.md](../README.md) e riga iniziale di [../AGENT.md](../AGENT.md) (nome del csproj nei comandi)
|
|
|
|
## Istruzioni per gli agenti di codice
|
|
Le istruzioni per chi lavora sul repository con un assistente (Claude Code, Gemini CLI, altri) stanno **solo in [../AGENT.md](../AGENT.md)**. Gli strumenti cercano file con nomi propri, quindi esistono due file puntatori che contengono una riga di importazione e nient'altro:
|
|
|
|
| File | Letto da | Contenuto |
|
|
|---|---|---|
|
|
| [../CLAUDE.md](../CLAUDE.md) | Claude Code | `@AGENT.md` (importazione) |
|
|
| [../GEMINI.md](../GEMINI.md) | Gemini CLI | `@AGENT.md` (importazione) |
|
|
|
|
Non si scrive nulla nei puntatori: ogni modifica va in AGENT.md. Per un altro strumento si aggiunge un puntatore con il nome che quello strumento cerca (per esempio `AGENTS.md`, usato da Codex), senza copiare il contenuto. Il nome `AGENT.md` è quello scelto per il progetto, non uno standard.
|
|
|
|
## Flusso (doc-first, doc-as-code)
|
|
1. Prima i doc, poi i test, poi il codice: ADR (se c'è una scelta architetturale) → MVP → matrice in [TESTING.md](TESTING.md) → test → codice → ROADMAP → PROJECT_STATE → README → AGENT.md.
|
|
Nessuna funzione è finita senza test che la coprono, nello stesso commit.
|
|
2. I doc stanno nel repo e cambiano con lo stesso commit del codice a cui si riferiscono.
|
|
3. Una modifica non deve lasciare i doc disallineati.
|
|
|
|
## Regole degli ADR
|
|
- Un file per decisione, `adr/NNNN-titolo-breve.md`, numerazione progressiva.
|
|
- Stati: `Proposta` → `Accettata` → eventualmente `Sostituita da ADR-NNNN` o `Rifiutata`.
|
|
- Un ADR accettato non si riscrive: se la decisione cambia se ne scrive uno nuovo che lo sostituisce e si aggiorna lo stato del vecchio.
|
|
- Sezioni: Contesto, Criteri, Opzioni, Decisione, Conseguenze, Da verificare, Riferimenti.
|
|
|
|
## Indice ADR
|
|
| ADR | Titolo | Stato |
|
|
|---|---|---|
|
|
| [0001](adr/0001-gui-multipiattaforma-avalonia.md) | GUI multipiattaforma in solo C# con Avalonia | Accettata |
|
|
| [0002](adr/0002-motori-cli-claude-codex-antigravity.md) | Più motori CLI (Claude Code, Codex, Antigravity) su Windows e Linux | Accettata (Claude Code, Codex) |
|
|
| [0003](adr/0003-strategia-di-test.md) | Strategia di test e regola "nuova funzione = nuovi test" | Proposta |
|
|
| [0004](adr/0004-aggiornamento-dei-cli.md) | Aggiornamento dei CLI dalle Impostazioni | Proposta |
|
|
| [0005](adr/0005-windows-senza-console.md) | Windows: eseguibile senza finestra di console | Proposta |
|
|
| [0006](adr/0006-immagini-nel-markdown.md) | Immagini nel markdown: solo file locali | Proposta |
|
|
| [0007](adr/0007-schema-wiki-per-query-con-immagini.md) | Schema di una wiki interrogabile, con immagini | Proposta |
|
|
| [0008](adr/0008-formule-latex-nel-markdown.md) | Formule LaTeX nel markdown | Proposta |
|