apipilot/CLAUDE.md

CLAUDE.md — ApiPilot

Questo file estende 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.