fernandoandClaude Sonnet 5
eac5e22ed1
Retira el código del motor (cmd/, internal/, go.mod, templates/, examples/, scripts de desarrollo Go) — vive ahora en https://github.com/fenandosr/clusterlog (release v0.1.0). Este repositorio conserva únicamente content/, data/, config/ y zola.toml: los datos reales de esta instancia (MCPS). Se agrega .clusterlog-version (fija v0.1.0) y scripts/fetch-engine.sh, que descarga el binario y las plantillas del motor por versión fijada verificando su checksum contra el release. Makefile y .gitea/workflows/ci.yml se adaptan para descargar en vez de compilar. RUNBOOK.md y runbooks/ se recortan a las celdas que sí operan sobre datos reales de esta instancia (sync-check, validate-local, site-build, review-mine, verify-head); el ciclo de desarrollo del motor mismo (build/test/vet) vive en su propio repositorio. Se preserva toda la historia existente: éste es un commit nuevo, no una reescritura. Ver docs/adr/0005-motor-instancia.md en el repositorio del motor para el contexto completo de la separación. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
117 lines
4.3 KiB
Markdown
117 lines
4.3 KiB
Markdown
# 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
|
|
|
|
1. Lea `clusterlog --json schema <tipo>` antes de construir una entrada nueva.
|
|
2. No incluya secretos, tokens, contraseñas, llaves privadas ni datos personales innecesarios.
|
|
3. Registre sólo hechos observados. Distinga claramente entre cambio ejecutado, validación ejecutada y recomendación pendiente.
|
|
4. Ejecute primero con `--dry-run` cuando el contenido provenga de una sesión larga o incluya comandos.
|
|
5. Use siempre `--json` y compruebe el código de salida.
|
|
6. Para una escritura final, use `--commit` únicamente cuando el usuario haya autorizado la operación y su mecanismo de firma esté disponible.
|
|
7. Nunca exporte, lea ni copie la llave privada. Pase una ruta autorizada o permita que Git/ssh-agent la maneje.
|
|
8. No edite `data/generated/site_state.json`; ejecute `clusterlog sync`.
|
|
9. No agregue manualmente eventos a un arreglo central. Cada evento debe ocupar su archivo independiente y ser creado por la CLI.
|
|
10. 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
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Runbooks ejecutables (Runme)
|
|
|
|
`RUNBOOK.md` y `runbooks/**/*.md` son documentación ejecutable, no una
|
|
segunda CLI. Reglas para un agente:
|
|
|
|
- Nunca active una celda `risk-mutating` o `risk-destructive` sin que el
|
|
usuario haya autorizado explícitamente esa operación puntual — la
|
|
etiqueta `manual-only`/`interactive`/`excludeFromRunAll` es una defensa
|
|
técnica de Runme, no una autorización.
|
|
- Trate cada celda como el comando que envuelve: si el comando requiere
|
|
`--dry-run` antes de `--commit`, la celda también.
|
|
- No agregue lógica nueva dentro de una celda; si hace falta lógica
|
|
reutilizable, colóquela en `clusterlog`, un script en `scripts/` o un
|
|
target de `Makefile`, y haga que la celda sólo lo invoque.
|
|
- No genere ni edite manualmente un identificador Lifecycle Identity de
|
|
Runme.
|
|
|
|
## Cambios a esta instancia
|
|
|
|
Este repositorio no tiene código de la CLI (vive en
|
|
[fenandosr/clusterlog](https://github.com/fenandosr/clusterlog)). Un cambio
|
|
aquí es Markdown/JSON de contenido o configuración de deployment. Antes de
|
|
entregar:
|
|
|
|
```bash
|
|
make build
|
|
make templates
|
|
./bin/clusterlog --root . sync
|
|
./bin/clusterlog --root . sync --check
|
|
./bin/clusterlog --root . validate --skip-zola
|
|
```
|
|
|
|
Cuando Zola esté disponible:
|
|
|
|
```bash
|
|
./scripts/bootstrap-theme.sh
|
|
./bin/clusterlog --root . validate --require-zola
|
|
zola build
|
|
```
|
|
|
|
Si el cambio necesario es a la CLI, sus esquemas o su comportamiento, hágalo
|
|
en el repositorio del motor, no aquí.
|