Saltar al contenido principal

​
¿Qué es un topic?

Un topic es la unidad atómica de contexto en Driftless. Conecta una porción de tu sistema con el conocimiento compartido del equipo sobre ella. La porción puede ser TypeScript, Python, Rust, Go, docs, config, infraestructura, o un flujo de trabajo que abarca varios repos. Un topic tiene:
FieldDescription
slugid único en kebab-case dentro del workspace (ej.: auth-flow, billing-webhook)
titleNombre corto para mostrar a humanos: un sustantivo como el nodo de un diagrama (Auth, Billing). Manténlo en una o dos palabras; la explicación va en what/content, nunca en el title
whatResumen corto de lo que hace este código
howNota corta (1-3 oraciones) sobre el mecanismo o el enfoque. La explicación extensa va en content, no aquí
decisionsPor qué se tomaron las decisiones (decisiones de arquitectura)
gotchasTrampas, casos límite, cosas que se van a romper
invariantsReglas que siempre deben cumplirse
required_checksChecks a correr antes de cambiar este código
ownershipEquipo o individuo responsable
contentCuerpo libre completo (Markdown). Puede incluir diagramas, snippets de código, referencias
anchorsPatrones, archivos y repos que ligan este topic al código
tagsCategorías del workspace para descubrimiento y filtrado (ej.: auth, billing): filtra con context list/search --tag <name>, el parámetro tags de MCP, o los chips del dashboard. Precréalas y cúralas en el registro (driftless tags)
relationsLinks tipados a otros topics
classificationEstado (reviewed, draft)
Los topics son content-first: el cuerpo markdown content ES el topic. Los campos estructurados (gotcha / decision / invariant / check) son highlights opcionales que se ponen encima. Agrega uno solo cuando quieras que esa cosa específica se le muestre a la máquina (el bot de PR, el brief de un futuro agente). Usa tags para etiquetar y agrupar topics.

​
Crea tu primer topic

Empieza con el topic útil más pequeño: una nota durable que explique un área lo suficientemente bien para que un humano o agente futuro pueda trabajar ahí. 
# The first topic should be something REAL: the gotcha that bit you, the
# invariant nothing may break, anchored to the module it governs:
driftless context add billing-webhooks --title "Webhooks" \
  --what "Stripe webhook ingestion and its idempotency rules." \
  --gotcha "Stripe delivers at-least-once: handlers must short-circuit on a seen event.id" \
  --pattern "src/billing/webhooks/**"
Luego enriquécelo a medida que la realidad se aclara: 
driftless context update billing-webhooks \
  --gotcha "..." \
  --decision "..." \
  --check "..."

​
Anclar topics al código

Los topics se conectan al código mediante patrones glob y rutas de archivo. Esto es agnóstico del lenguaje: Driftless matchea rutas, no ASTs. Cuando el código anclado cambia, el topic entra en drift. 
# Anchor by glob pattern
driftless context add api-guards --pattern "src/auth/**"

# Multiple patterns for cross-cutting topics
driftless context update api-guards --add-pattern "src/common/guards/**"

# Anchor by exact file path
driftless context add auth-flow --where src/auth/guard.ts

# Anchor a document
driftless context add architecture-decisions --file docs/decisions/auth.md
La CLI valida cada patrón contra tu checkout local al momento de escribir:
  • ✓ pattern "src/auth/**" matches 12 files: anchor sano
  • ⚠ over-broad anchor: el patrón matchea más de 100 archivos; considera dividirlo
  • ✗ pattern "src/nonexistent/**" matches 0 files: bloqueado; arregla el glob
Disciplina: 5-40 archivos matcheados por topic es sano. Menos de 5 significa que estás fragmentando. Más de 100 es una trampa cajón de sastre que nadie va a mantener. Si un topic cubre demasiado, divídelo; si cubre muy poco, fusiónalo. Quita anchors cuando ya no tengan sentido: 
driftless context update auth-flow --remove-pattern "src/old-auth/**"

​
Clasificación de topics

Un topic es content-first: el cuerpo markdown content ES el topic. Usa tags para etiquetar y agrupar topics. El único eje de confianza es status.

​
Status: ciclo de vida de gobernanza

Una nota se vuelve Knowledge una vez que se fusiona: draft → proposed → reviewed → archived. reviewed es Knowledge; la respuesta de lectura lleva governance.authoritative. Los agentes proponen; fusionar es un acto de owner/admin (un agente lo corre solo cuando se le pide explícitamente). Ver Gobernanza.
StatusMeaning
draftCapturado, todavía sin fusionar: una pista (una Nota), no verdad
proposedEn revisión
reviewedKnowledge: un owner/admin lo fusionó (o un agente lo hizo a pedido suyo); el agente lo trata como verdad
archivedRetirado
orphanedImpulsado por código (repo borrado), ortogonal a la gobernanza

​
Visibilidad

Un topic vive en el workspace y es visible para todos sus miembros. La excepción es una Nota privada (un draft con is_private puesto), visible solo para su creador hasta que se ponga en revisión o se le quite la marca. ¿Necesitas aislamiento entre grupos? Usa un workspace aparte.

​
Relaciones tipadas

Los topics se conectan entre sí mediante relaciones tipadas, construyendo un grafo semántico:
RelationMeaning
depends_onEl topic A depende de B
relates_toAsociación general
supersedesEl topic B reemplaza a A
blocksA no puede avanzar hasta que B esté hecho
implementsA es la implementación del patrón descrito en B
documentsA documenta o explica B
risk_forA introduce un riesgo para B
driftless context update auth-guard \
  --rel depends_on:jwt-service \
  --rel relates_to:role-decorator
Usa la sintaxis [[slug]] dentro de cualquier campo de texto libre (what, how, decisions, gotchas, invariants, content). La API las parsea automáticamente en referencias hacia adelante y hacia atrás. 
driftless context update billing-webhook \
  --gotcha "Same idempotency race as [[stripe-webhook-ingest]]; deduplicate by event ID"
Tanto billing-webhook como stripe-webhook-ingest se mostrarán mutuamente en sus referencias cuando se consulten.

​
Contexto entre repos

Un topic puede abarcar varios repositorios. Cuando corres driftless context update <slug> desde cualquier repo, ese repo se agrega a la lista where_repos del topic. Los topics acumulan repos de forma orgánica sin cableado manual. Usa un solo topic entre repos cuando el mismo concepto realmente abarca varios repos, por ejemplo billing-contracts a través de un repo de API, un repo de worker y un repo de frontend. Usa topics separados más relaciones cuando cada repo tiene sus propios detalles de implementación, por ejemplo billing-api depends_on:billing-worker. Para ligar explícitamente el repo actual a un topic: 
driftless context link auth-flow

​
El grafo de topics

El grafo de topics se puede explorar desde la CLI y el dashboard: 
driftless context graph auth-flow    # BFS graph from a topic, terminal output
El dashboard renderiza el grafo interactivo completo. Los nodos son topics, las aristas son relaciones tipadas. Haz clic en cualquier nodo para ver su contexto completo y sus anchors.