first

2026-09-24 05:19:06 -04:00
commit 2cec225860
27 changed files with 2640 additions and 0 deletions
@@ -0,0 +1,44 @@
+# CLAUDE.md — ApiPilot
+
+Questo file estende [AGENT.md](AGENT.md) con note specifiche per Claude / agenti di coding. Le regole comuni (architettura, sicurezza, testing, documentazione) si trovano in AGENT.md e sono obbligatorie. Consultalo prima di ogni modifica.
+
+## Prompt interno per Claude (non divulgare)
+
+Quando modifichi ApiPilot:
+
+1. **Inizia sempre leggendo AGENT.md e CHANGELOG.md** per capire lo stato attuale.
+2. **Preferisci modifiche minimali e generiche**: la libreria è passthrough. La logica di dominio è nel backend ospite.
+3. **Non introdurre riferimenti a specifiche entità** nel nucleo (es. `invoice`, `workspace`, `tenant`).
+4. **Cap rigorosamente ogni lista/struttura iniettata** nel contesto del modello: dimensioni massime, troncamento chiaro.
+5. **Anti-meta-commento / anti-thinking-leak**:
+   - Le funzioni pubbliche (specie in adapter) restituiscono dati pronti per essere mandati al modello.
+   - Non includere debug, pensieri o meta-commenti nei valori di ritorno.
+   - Nei messaggi di errore evita frasi autoriferite ("io", "questo tool") quando possibile.
+6. **Per modifiche alle strutture `TypedDict`**: aggiorna in parallelo i test corrispondenti; rompere compatibilità qui richiede bump di versione appropriato in CHANGELOG.
+7. **Quando tocchi `openapi_parser`**: verifica che i parametri `in: header` siano sempre esclusi dal catalogo. Non aggiungere parametri tecnologici per errore.
+8. **Quando tocchi `core._run_endpoint`**:
+   - Non permettere all'argomento agente di risolvere arbitrariamente il nome della funzione Python; la mappatura è statica.
+   - Riporta in `ExecuteResponse.error` status_code ed endpoint senza stacktrace internamente.
+9. **Quando tocchi gli endpoints HTTP in `fastapi.py`**:
+   - Assicurati che `require_auth_for_http=True` + `get_current_user != None` dia sempre 401 senza token.
+   - Nessun parametro URL permetta di scegliere nomi di file, rotte, credenziali.
+10. **Ciclo di verifica minimo prima di dichiarare completato**:
+    ```
+    pytest -q
+    ruff check apipilot tests examples
+    ```
+
+## Regole specifiche ApiPilot in aggiunta ad AGENT.md
+
+- I nomi dei tool devono essere identificatori validi e corti: `a-zA-Z0-9_`.
+- Le descrizioni dei tool sono scritte per il modello, non per l'utente finale: devono spiegare **quando** usare il tool, non **come** è implementato.
+- `tools_for(user)` deve sempre ritornare una lista nuova (non condivisa) per evitare side-effect.
+- Ogni adapter deve preservare `tool_call_id` in modo trasparente (cfr. `OpenAIAdapter.make_tool_result`).
+
+## Note su versionamento Qwen / modelli quantizzati
+
+- Le descrizioni dei parametri non devono contenere meta-stringhe tipo "pensa bene prima di...", ma essere istruzioni operative concrete.
+- Evita enum molto lunghe (>20 valori) iniettate nello schema: meglio rimpiazzarle con `type: string` e descrizione che rimandi a un tool di lookup.
+- Dove possibile, rimpicciolisci `max_response_size` prima di affidarti al troncamento generico; esponi come configurazione per-tool.
+
+Per qualsiasi domanda che questi due file non coprano, documenta la decisione nel CHANGELOG e aggiorna questo doc o AGENT.md coerentemente.