# 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.