Instrucciones para agentes de programación

Propósito

Use clusterlog para registrar trabajo operativo de forma atribuible, validada y reproducible. No edite directamente archivos derivados ni simule una identidad.

Reglas obligatorias

Lea clusterlog --json schema <tipo> antes de construir una entrada nueva.
No incluya secretos, tokens, contraseñas, llaves privadas ni datos personales innecesarios.
Registre sólo hechos observados. Distinga claramente entre cambio ejecutado, validación ejecutada y recomendación pendiente.
Ejecute primero con --dry-run cuando el contenido provenga de una sesión larga o incluya comandos.
Use siempre --json y compruebe el código de salida.
Para una escritura final, use --commit únicamente cuando el usuario haya autorizado la operación y su mecanismo de firma esté disponible.
Nunca exporte, lea ni copie la llave privada. Pase una ruta autorizada o permita que Git/ssh-agent la maneje.
No edite data/generated/site_state.json; ejecute clusterlog sync.
No agregue manualmente eventos a un arreglo central. Cada evento debe ocupar su archivo independiente y ser creado por la CLI.
Después de escribir, ejecute clusterlog validate y devuelva al usuario ID, ruta, advertencias y SHA del commit.

Flujo para una memoria de sesión

clusterlog --json schema memory > /tmp/memory-schema-envelope.json

cat > /tmp/memory.json <<'JSON'
{
  "title": "...",
  "description": "...",
  "tags": [],
  "systems": [],
  "risk": "low",
  "review_required": true,
  "context": "...",
  "changes": [],
  "commands": [],
  "validation": [],
  "rollback": "...",
  "agent": "<nombre-del-agente>"
}
JSON

clusterlog --root . --json --dry-run --ssh-key "$CLUSTERLOG_SSH_KEY" \
  memory create --from-json /tmp/memory.json

clusterlog --root . --json --commit --ssh-key "$CLUSTERLOG_SSH_KEY" \
  memory create --from-json /tmp/memory.json

clusterlog --root . --json validate
clusterlog --root . --json verify commit HEAD

Calidad de una memoria

Una memoria útil responde:

¿Cuál era el contexto o síntoma?
¿Qué se cambió exactamente?
¿Qué comandos son relevantes, con valores sensibles redactados?
¿Qué resultado se observó?
¿Cómo se validó?
¿Qué riesgo quedó abierto?
¿Cómo se revierte?
¿Qué manual o documento debe actualizarse?

No convierta salidas extensas de terminal en el cuerpo. Resuma y enlace evidencia aprobada.

Comportamiento ante errores

identity_not_found: deténgase; no elija otra identidad por aproximación.
possible_secret: redacte y repita el dry-run; no fuerce la escritura.
validation_failed: presente los códigos y rutas concretas.
git_commit_failed: no afirme que la operación quedó auditada; los archivos pueden existir sin commit y deben revisarse.
task_has_running_timers: identifique a los actores; no cierre o borre eventos.

Cambios al código del proyecto

Antes de entregar:

gofmt -w cmd internal
go test ./...
go vet ./...
make build
./bin/clusterlog --root . sync
./bin/clusterlog --root . sync --check
./bin/clusterlog --root . validate --skip-zola

Cuando Zola esté disponible:

./scripts/bootstrap-theme.sh
./bin/clusterlog --root . validate --require-zola
zola build

Mantenga compatibilidad del JSON. Cualquier cambio de contrato debe actualizar schema.go, CLI.md, ejemplos y pruebas.

3.3 KiB Raw Blame History