Guida Rapida

Questo tutorial ti guida attraverso il workflow principale di Contextia: inizializzare un progetto, creare una specifica, annotare il codice e validare che tutto sia collegato correttamente. Alla fine, avrai una directory .contextia/ funzionante con una specifica reale, codice annotato e controlli superati.

Useremo un piccolo progetto Python come esempio, ma Contextia funziona con qualsiasi linguaggio.

Passo 1: Inizializzare il progetto

Naviga nella root del tuo progetto ed esegui:

contextia init

Contextia rileva il linguaggio e la struttura del progetto, poi crea la directory .contextia/:

Detected languages: python
Created .contextia/config.yaml
Created .contextia/system/identity.md
Created .contextia/system/specs/
Created .contextia/system/rationale/
Created .contextia/system/norms/
Created .contextia/work/tasks/
Initialized Contextia project in /home/user/my-project

Il comando init rileva automaticamente i linguaggi del progetto cercando file indicativi (pyproject.toml, package.json, Cargo.toml, go.mod, ecc.) e configura di conseguenza l’analisi delle annotazioni.

Vediamo cosa è stato generato:

.contextia/config.yaml

version: "1.0"
project:
  name: my-project
  languages:
    - python
  paths:
    source:
      - src/
    test:
      - tests/
annotations:
  prefix: "@"
  comment_syntax:
    python: "#"
output:
  color: true
  default_format: human

Il file di identità è un documento Markdown che descrive il progetto sia per gli umani che per gli agenti AI:

.contextia/system/identity.md

---
type: identity
version: 1
---

# my-project

<!-- Describe your project: what it does, who it serves, key constraints -->

Consiglio

Compila identity.md il prima possibile. Questo è il primo file che un agente AI legge quando si connette al tuo progetto tramite MCP. Un buon file di identità evita che l’agente debba indovinare lo scopo e i confini del progetto.

Passo 2: Creare la prima specifica

Le specifiche sono contratti comportamentali — definiscono cosa il sistema deve fare. Creiamone una per un modulo di autenticazione utente:

contextia new spec --title "User Authentication"

Questo crea una nuova specifica dal template integrato:

Created .contextia/system/specs/SPEC-001-user-authentication.md

Apri il file e compila la specifica:

.contextia/system/specs/SPEC-001-user-authentication.md

---
type: spec
id: SPEC-001
title: User Authentication
status: draft
decisions:
  - DEC-001
paths:
  - src/auth/login.py
  - src/auth/tokens.py
tags:
  - auth
  - security
---

# User Authentication

## Panoramica

Il modulo di autenticazione gestisce il login utente, l'emissione dei token e la
validazione delle sessioni. Tutti gli endpoint richiedono HTTPS. Le password non
vengono mai memorizzate in chiaro.

## Comportamento

### Login

- Accetta email e password tramite POST `/api/auth/login`
- Valida le credenziali contro l'archivio utenti
- In caso di successo, restituisce un token di accesso JWT (scadenza 15 min) e un refresh token (scadenza 7 giorni)
- In caso di fallimento, restituisce 401 con un messaggio di errore generico (non rivelare se l'email esiste)

### Rinnovo del token

- Accetta un refresh token valido tramite POST `/api/auth/refresh`
- Restituisce un nuovo token di accesso
- Se il refresh token è scaduto o revocato, restituisce 401

### Logout

- Accetta un token di accesso tramite POST `/api/auth/logout`
- Aggiunge il token alla lista di revoca
- Restituisce 204

## Vincoli

- Password hashate con bcrypt, fattore di costo minimo 12
- JWT firmato con RS256, chiavi ruotate trimestralmente
- Limite di frequenza: 5 tentativi di login falliti per email ogni 15 minuti

Nota i campi del frontmatter:

• id: SPEC-001 — identificatore unico, referenziato dai task e dalle annotazioni nel codice
• status: draft — stato del ciclo di vita (draft, active, deprecated, superseded)
• decisions — link alle decisioni architetturali che vincolano questa specifica
• paths — file sorgente che implementano questa specifica (tracciabilità top-down)
• tags — per la ricerca e il filtraggio

Passo 3: Annotare il codice

Ora colleghiamo la specifica al codice sorgente. Apri un file sorgente e aggiungi le annotazioni usando i commenti:

src/auth/login.py

from datetime import datetime, timedelta

from auth.tokens import create_access_token, create_refresh_token
from auth.users import verify_credentials
from auth.rate_limit import check_rate_limit, record_failure


# @spec SPEC-001
# @spec SPEC-001.login
async def login(email: str, password: str) -> dict:
    """Authenticate a user and return token pair."""
    if not check_rate_limit(email):
        raise RateLimitError("Too many login attempts")

    user = await verify_credentials(email, password)
    if user is None:
        record_failure(email)
        # @decision DEC-001 -- generic error, do not reveal email existence
        raise AuthenticationError("Invalid credentials")

    access_token = create_access_token(user.id, expires=timedelta(minutes=15))
    refresh_token = create_refresh_token(user.id, expires=timedelta(days=7))

    return {
        "access_token": access_token,
        "refresh_token": refresh_token,
    }


# @spec SPEC-001.logout
async def logout(token: str) -> None:
    """Revoke an access token."""
    await revoke_token(token)

Le annotazioni creano link dal basso verso l’alto dal codice alle specifiche:

• @spec SPEC-001 — questa funzione implementa la specifica User Authentication
• @spec SPEC-001.login — specificamente il sotto-comportamento di login
• @decision DEC-001 — questa riga è vincolata da una specifica decisione architetturale

Queste annotazioni completano i link dall’alto verso il basso nel frontmatter della specifica (paths: [src/auth/login.py]). Insieme, formano una tracciabilità bidirezionale tra specifiche e codice.

Nota

Il prefisso delle annotazioni (@) è configurabile in .contextia/config.yaml sotto annotations.prefix. Alcuni team preferiscono @ctx: per evitare conflitti con sistemi di annotazione esistenti (ad esempio, @Override di Java). Scegli un prefisso che non entri in conflitto con la sintassi del tuo linguaggio.

Passo 4: Eseguire check

Il comando check valida l’integrità della tua architettura del contesto. Verifica che i link tra gli artefatti siano coerenti, che i campi obbligatori siano presenti e che le annotazioni nel codice corrispondano alle rispettive specifiche:

contextia check

Se tutto è collegato correttamente, vedrai:

Checking .contextia/ integrity...

Specs:          1 found, 1 active
Decisions:      0 found (1 referenced but missing: DEC-001)
Norms:          0 found
Tasks:          0 found
Annotations:    3 found in 1 file

Warnings:
  SPEC-001 references DEC-001 but no decision file exists
    → Create it with: contextia new decision --id DEC-001

Annotations validated:
  ✓ src/auth/login.py:9    @spec SPEC-001        (spec exists)
  ✓ src/auth/login.py:10   @spec SPEC-001.login  (spec exists)
  ✓ src/auth/login.py:19   @decision DEC-001     (decision missing)

Result: 1 warning, 0 errors

Il controllo ha trovato che la nostra specifica fa riferimento a DEC-001, ma non abbiamo ancora creato quel file di decisione. Risolviamo:

contextia new decision --id DEC-001 --title "Generic authentication errors"

.contextia/system/rationale/DEC-001-generic-authentication-errors.md

---
type: decision
id: DEC-001
title: Generic authentication errors
status: accepted
date: 2026-03-02
specs:
  - SPEC-001
---

# Generic authentication errors

## Contesto

L'endpoint di login deve comunicare i fallimenti di autenticazione al client.

## Decisione

Restituire un messaggio generico "Invalid credentials" per tutti i fallimenti di
autenticazione, indipendentemente dal fatto che l'email esista nel sistema.

## Motivazione

Rivelare se un'email è registrata permette attacchi di enumerazione degli account.
Un messaggio di errore generico impedisce agli attaccanti di distinguere tra
gli scenari "email non trovata" e "password errata".

## Alternative considerate

- **Messaggi di errore specifici**: UX migliore ma permette l'enumerazione.
  Rifiutata per ragioni di sicurezza.
- **Risposte con temporizzazione uniforme**: Aggiungere un ritardo artificiale per mascherare il timing della ricerca.
  Considerata complementare, non sostitutiva dei messaggi generici.

Esegui di nuovo check:

contextia check

Checking .contextia/ integrity...

Specs:          1 found, 1 active
Decisions:      1 found, 1 accepted
Norms:          0 found
Tasks:          0 found
Annotations:    3 found in 1 file

All annotations validated ✓
All links resolved ✓

Result: 0 warnings, 0 errors

Attenzione

contextia check è progettato per essere eseguito nelle pipeline CI/CD. Usa --format json per un output parsabile dalla macchina, e configuralo come controllo obbligatorio sulle pull request per impedire che link rotti vengano mergiati.

Passo 5: Esplorare con trace

Il comando trace mostra la tracciabilità completa per un file o una directory — quali specifiche lo governano, quali decisioni lo vincolano e quali task lo hanno toccato:

contextia trace src/auth/

Tracing: src/auth/

src/auth/login.py
  ├── @spec SPEC-001          User Authentication
  │   ├── @spec SPEC-001.login    (sub-behavior: login)
  │   └── @decision DEC-001   Generic authentication errors
  └── @spec SPEC-001.logout       (sub-behavior: logout)

src/auth/tokens.py
  └── @spec SPEC-001          User Authentication (via paths in spec)

Coverage:
  Files with annotations:   1 / 2  (50%)
  Spec path coverage:       2 / 2  (100%)

Trace ti dà un quadro completo di come codice, specifiche e decisioni sono correlati. Funziona a livello di file, directory o singola specifica:

# Traccia una singola specifica per vedere tutti i suoi artefatti collegati
contextia trace SPEC-001

# Traccia con profondità completa per includere norme e storico dei task
contextia trace src/auth/ --depth full

Cosa succede quando un agente AI si connette

Con il server MCP configurato (vedi Installazione), ecco cosa sperimenta un agente AI quando si connette al tuo progetto:

1. Il server MCP si avvia e scopre la tua directory .contextia/
2. L’agente riceve automaticamente la risorsa contextia://identity — il file di identità del tuo progetto
3. L’agente riceve la risorsa contextia://index — una mappa di navigazione di tutte le specifiche, decisioni, norme e task

Quando all’agente viene assegnato un task, invoca load_context per ottenere tutto ciò di cui ha bisogno:

Agent calls: load_context(task_id="TASK-042")

Response includes:
  - Task TASK-042 full content
  - SPEC-001 (referenced by task)
  - DEC-001 (referenced by SPEC-001)
  - Applicable norms (matched by tag)
  - Previous session logs (if any)

L’agente lavora con piena conoscenza delle specifiche e dei vincoli pertinenti. Non ha bisogno di cercare, indovinare o chiederti di incollare il contesto nella chat.

Prossimi passi

Ora hai un progetto Contextia funzionante con:

• Una directory .contextia/ configurata
• Una specifica comportamentale con link nel frontmatter
• Annotazioni nel codice che creano tracciabilità bidirezionale
• Controlli di integrità superati

Da qui, puoi:

• Creare un task con contextia new task per assegnare lavoro che fa riferimento alle tue specifiche
• Aggiungere norme con contextia new norm per codificare le convenzioni di coding del team
• Configurare il server MCP per consentire agli agenti AI di accedere direttamente alla tua architettura del contesto
• Aggiungere contextia check alla tua pipeline CI per impedire che link rotti vengano mergiati

Per una comprensione più approfondita di ogni tipo di artefatto e del suo schema, consulta la documentazione di riferimento.