Saltearse al contenido
NamiDB NamiDB

Cursor, Codex, AGENTS.md

Si tu front-end de IA no es Claude Code, igual puedes obtener contexto de alta calidad para NamiDB con un archivo de reglas chico en la raíz de tu proyecto. Los patterns abajo son todos templates opinionados, tuneados a NamiDB — droppealos en tu repo y toman efecto al instante.

Template universal: AGENTS.md

La convención emergente AGENTS.md (adoptada por Codex, Cursor, Continue, Aider y otros) es el starting point más portable. Droppea esto en la raíz de tu repo:

AGENTS.md
Este proyecto usa **NamiDB** — una base de datos en grafo
cloud-native con Cypher / GQL sobre un bucket compatible con S3.


## Leer esto primero


Pull del contexto canónico del motor una vez por sesión:


  https://docs.namidb.com/llms-full.txt


## NamiDB ground truth (no desviarse)


- El bucket es la base de datos. El estado vive como objetos S3
  planos. Sin Raft. Sin etcd. Sin tabla de locks en DynamoDB.
- `_id` es el NodeId interno desde v0.3. `id` es una propiedad de
  usuario común. Los datos de entrenamiento viejos los confunden —
  siempre flaggear.
- Seis URI schemes: memory://, file://, s3://, gs://, az://. El
  parámetro `?ns=` es obligatorio en todos salvo memory://<ns>.
- Las escrituras de Cypher commitean al retornar (WAL + manifest
  CAS). Llamar a flush() periódicamente para pasar memtable → L0.
- Un solo writer por namespace. Dos writers compitiendo → el que
  pierde recibe 412 PreconditionFailed. Es el protocolo de fencing.
- Bulk ingest: usar `merge_nodes`/`merge_edges` (Python) o la API
  Rust `upsert_node`/`upsert_edge`, no `CREATE` de Cypher por fila.


## NO generar


- Cypher no soportado: subqueries CALL {}, LOAD CSV, CREATE
  INDEX/CONSTRAINT, paths unbounded *paths (usar *1..N).
- Sugerencias de servicios de lock externos (DynamoDB, etcd,
  ZooKeeper).
- Código usando semántica de `id(n)` de v0.2 — siempre usar `_id`
  o la forma de función `id(n)` para el NodeId interno.


## Convenciones del proyecto


[Agregar especificidades del equipo: naming de namespaces,
template de IAM, backend de almacenamiento preferido, región de
deploy, etc.]

Cursor: .cursorrules

Cursor lee .cursorrules en la raíz del repo. Mismo contenido que AGENTS.md, solo renombrado:

Ventana de terminal
cp AGENTS.md .cursorrules

O mantenerlos en sync con un symlink:

Ventana de terminal
ln -s AGENTS.md .cursorrules

GitHub Copilot: .github/copilot-instructions.md

Copilot lee un archivo markdown desde tu repo. Droppea el mismo contenido en .github/copilot-instructions.md — se va a inlinear en cada request de completion.

Codex CLI: ~/.codex/AGENTS.md o AGENTS.md por repo

Codex CLI usa AGENTS.md directamente en la raíz del repo (o ~/.codex/AGENTS.md para user-global). El template universal de arriba es plug-and-play.

Continue / Aider / Cline

Los tres soportan un archivo de reglas markdown en la raíz del repo. Usar AGENTS.md o el filename específico de la herramienta:

HerramientaArchivo
Continue.continue/context.md o AGENTS.md
Aider.aider.conf.yml (con read: AGENTS.md)
Cline.clinerules

Pulleando contexto fresco en cada sesión

Para entornos efímeros (CI, code reviewers, batch jobs), pull contexto fresco al inicio de cada run en lugar de pinear un snapshot estático:

Ventana de terminal
# Bash
curl -s https://docs.namidb.com/llms-full.txt > /tmp/namidb-context.md
# Python
import urllib.request
context = urllib.request.urlopen(
    "https://docs.namidb.com/llms-full.txt"
).read().decode()

Luego prependear context al system prompt del agente.

Pattern: prompt-caching del contexto

Tanto Anthropic como OpenAI soportan prompt caching. Cachea el bloque llms-full.txt una vez y paga solo el delta en llamadas posteriores de la misma sesión.

client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": namidb_context,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[...],
)

Ver docs de prompt caching de Anthropic.

Validar que las reglas tomaron efecto

Sanity check rápido en cualquier herramienta:

Escribir una query de Cypher que cree 5 nodos Person con UUIDs aleatorios como NodeId interno, y luego una arista KNOWS entre pares consecutivos.

Un agente con las reglas correctas:

  • Usa {_id: ...} (NO {id: ...})
  • Usa MERGE o CREATE por la gramática v0.3
  • Usa tg.Client("s3://...?ns=...") (si Python) o parse_uri(...) (si Rust)
  • No inventa clauses no soportadas como CREATE INDEX o CALL { ... }

Si alguno de esos falla, las reglas no las está leyendo el agente — revisar nombre del archivo, ubicación, y que el feature de “rules” de tu herramienta esté habilitado.

Ver también