Creare Contesti

Questa guida ti accompagna nella creazione di un Documento di contesto da zero - dalla navigazione verso la pagina dei Contesti, alla scrittura di contenuto markdown ben strutturato, alla pubblicazione della tua prima versione, fino al collegamento del Contesto ai session type o alle persona che devono riceverlo.

Navigare verso la pagina dei Contesti

I Contesti si trovano nella sidebar del progetto. Cerca la voce Contesti nel pannello di navigazione a sinistra. Se non la vedi, assicurati di avere almeno accesso Membro al progetto. La pagina dei Contesti si trova in /p/{projectId}/context.

La pagina elenca tutti i Contesti esistenti nel progetto, mostrando per ciascuno il nome, la descrizione, il numero di versioni pubblicate e la data di pubblicazione della versione attiva. Se non è ancora stato creato alcun Contesto, vedrai uno stato vuoto con un pulsante Crea Contesto in evidenza.

Creare un nuovo Contesto

Scrivere il contenuto del Contesto

La pagina di dettaglio del Contesto contiene un editor markdown completo. Il contenuto che scrivi qui è esattamente ciò che viene iniettato nelle sessioni sandbox. Scrivilo allo stesso modo in cui scriveresti un file CLAUDE.md - chiaramente strutturato, con intestazioni per la navigazione e punti elenco per regole facilmente scorribili.

Cosa includere

Un contenuto di Contesto efficace è specifico e azionabile. Gli agenti performano meglio quando hanno regole concrete e non ambigue piuttosto che linee guida vaghe. Struttura il tuo contenuto con:

• Una sezione panoramica che descrive lo stack tecnologico ad alto livello
• Sezioni sulle convenzioni dei file che elencano dove risiedono i diversi tipi di file
• Standard di coding che coprono naming, pattern e anti-pattern da evitare
• Vincoli chiave usando un linguaggio esplicito “mai” e “sempre”
• Dipendenze importanti o configurazioni di cui gli agenti devono essere a conoscenza

Esempio di contenuto di Contesto

Di seguito un esempio di Contesto Architettura del progetto ben scritto per un’applicazione TypeScript full-stack:

# Project Architecture

This is a Next.js 16 application with:
- **Frontend**: React 19, TypeScript, Tailwind CSS, shadcn/ui
- **Backend**: Convex (reactive database + server functions)
- **Auth**: Clerk

## Coding Standards
- Always use TypeScript strict mode
- Prefer server components over client components
- Use Convex mutations for all data writes
- Never use `dangerouslySetInnerHTML` without sanitization

## File Conventions
- Components: PascalCase in `/components/`
- Hooks: camelCase with `use` prefix in `/hooks/`
- Utils: camelCase in `/lib/`

## Convex Rules
- Never use `.collect()` on large tables - use `.take(N)` or paginate
- Batch work goes to `ctx.scheduler.runAfter` to avoid timeout
- Mutations validate input with Convex validators, not Zod

## Next.js Specifics
- The middleware file is `proxy.ts`, NOT `middleware.ts`
- All API routes live in `/app/api/`
- Use `generateStaticParams` for static paths, not `getStaticPaths`

## Testing
- Unit tests: Vitest with `@testing-library/react`
- E2E tests: Playwright in `/e2e/`
- Run `bun test` before every commit

Pubblicare la tua prima versione

Visualizzare la cronologia delle versioni

Il pannello Cronologia delle versioni nella pagina di dettaglio del Contesto elenca ogni versione pubblicata in ordine cronologico inverso. Ogni voce mostra:

• Il numero di versione (v1, v2, v3, …)
• Il timestamp di pubblicazione
• Chi l’ha pubblicata (nome visualizzato dell’utente)
• Il badge di stato attivo o inattivo

Clicca su una versione qualsiasi per vederne il contenuto in modalità di sola lettura. Questo ti permette di confrontare la versione attiva corrente con le versioni storiche per capire cosa è cambiato.

Collegare un Contesto a una persona

Per collegare un Contesto a una persona specifica, naviga alla pagina di dettaglio della persona in /p/{projectId}/personas/{personaId} e apri il tab Contesto. Da lì, usa il menu a tendina per selezionare il Contesto che vuoi che questa persona usi. Una volta salvato, ogni sessione eseguita da questa persona inietterà il Contesto collegato della persona invece del default del session type.

Collegare un Contesto a un session type

I binding a livello di session type vengono gestiti dalle Impostazioni del progetto. Ogni session type ha il proprio tab di setup:

• Setup Answering - /p/{id}/answering-setup
• Setup Issues - /p/{id}/issues-setup
• Setup Learning - /p/{id}/learning-setup
• Setup Merging - /p/{id}/merging-setup
• Setup Evaluator - /p/{id}/evaluator-setup
• Setup Judge - /p/{id}/judge-setup

In ciascun tab di setup, trova il campo Contesto e seleziona il Contesto che vuoi che tutte le sessioni di quel tipo ricevano per default. Il binding viene salvato immediatamente alla selezione.

Prossimi passi