Argui

Disciplina operativa

Cómo se opera un proyecto Argui a lo largo del tiempo: git, sesiones y auditorías. El workflow define qué se hace en cada fase; este documento define cómo se sostiene la calidad y la eficiencia mientras el proyecto avanza.

La unidad de trabajo

Toda la disciplina gira alrededor de la unidad de trabajo:

  • Fases 0–4 (preparación): la unidad es un paso del workflow.
  • Fase 5 (ciclo iterativo): la unidad es un change/item del backlog.

Una unidad define a la vez una rama, una sesión y un punto donde se sugiere commit/PR. Cerrar una unidad es el momento de confirmar, integrar y limpiar.

Aislamiento del entorno de IA

El asistente corre con los permisos de quien lo lanza. Por defecto su escritura está acotada a la carpeta del proyecto, pero su lectura es amplia: puede leer casi todo el equipo, incluidas credenciales como ~/.ssh/ y ~/.aws/credentials. Sin aislamiento explícito, un prompt malicioso, una dependencia comprometida o el propio agente en modo autónomo pueden leer secretos fuera del proyecto o exfiltrarlos por red. Coherente con el territorio de Argui (privacidad y soberanía), el entorno se confina antes de empezar (fase 0).

El principio es portable; la implementación depende de la herramienta. Dos niveles, según el riesgo:

  • Nivel 1 — confinamiento nativo (baseline, siempre). El asistente solo lee/escribe la carpeta del proyecto y solo sale a los dominios imprescindibles (red default-deny). Bajo costo: archivo(s) de configuración. Necesita dos capas que se complementan —el sandbox de SO (sistema operativo) (cubre los comandos de shell) y reglas de permisos que deniegan lectura/escritura fuera del proyecto (cubren las herramientas internas de archivo, que no pasan por el sandbox)—; por separado cada una deja huecos. Implementación de referencia para Claude Code en templates/aislamiento/.
  • Nivel 2 — contenedor (proporcional: autonomía total o código no confiable). El asistente corre dentro de un contenedor que solo monta la carpeta del proyecto, como usuario no-root, con firewall de egress default-deny. Aunque algo burle las reglas, no hay nada más montado que tocar. Es el único entorno donde el modo autónomo sin confirmaciones tiene sentido (el peor caso es romper el contenedor). Referencia: el devcontainer oficial de Anthropic (https://code.claude.com/docs/en/devcontainer.md), en vez de mantener una imagen propia que envejece.

Honestidad de límites: el filtrado de red no inspecciona TLS (Transport Layer Security) (dominios amplios dejan margen de exfiltración) y el aislamiento es respecto al host, no respecto al propio proyecto (un .env o credenciales dentro de la carpeta montada siguen siendo visibles). No dejes secretos dentro de la carpeta de trabajo.

En una herramienta sin sandbox ni reglas de permisos equivalentes, el Nivel 2 (contenedor) es el camino para el mismo principio (ver portability.md).

Git: ramas, commits y PRs

Los agentes no ejecutan git. Proponen ramas, commits y PRs (Pull Requests); el humano revisa, confirma y ejecuta. El control de lo que entra al historial es humano — principio “el humano aprueba, no supervisa”.

Ramas

Una rama por unidad de trabajo:

  • Fases 0–4: cada paso del workflow se trabaja en su propia rama antes de entrar al ciclo iterativo.
  • Fase 5: cada change/item tiene su rama; los commits del ciclo se acumulan ahí.

Nombre de la rama: <tipo>/<ID>-<slug>, donde <tipo> es el de Conventional Commits (feat, fix, chore…) e <ID> es la unidad: el F-ID del paso en fases 0–4 (chore/F4.6-estandares) o el ID del item del backlog en fase 5 (feat/CHQ-014-login). Codificar el ID en el nombre hace que la lista de ramas activas (git branch -r) diga por sí sola qué se está construyendo — base del claim en equipo, donde el formato se valida en CI (Continuous Integration) (ver teams.md).

Commits

Siguen Conventional Commits v1.0.0:

tipo(alcance): descripción breve en imperativo

[cuerpo opcional: el porqué del cambio]

[footer opcional: BREAKING CHANGE: …, refs, etc.]

Tipos: feat, fix, docs, refactor, test, chore, build, ci, perf. El footer BREAKING CHANGE: marca cambios incompatibles.

Cuándo se sugiere un commit:

  • Al cerrar cada paso del workflow (fases 0–4).
  • Al cerrar cada fase del ciclo iterativo (apply / verify / qa / sync+archive).
  • Al terminar una sesión de trabajo, aunque la unidad no haya cerrado: un commit WIP (Work In Progress) deja el avance persistido y el día de trabajo registrado. Un día sin commit es invisible para las métricas de tiempo (ver metrics.md); persistir va primero, la métrica se alimenta de paso.

Pull requests

Al cerrar la unidad se sugiere abrir el PR: un paso aprobado (fases 0–4) o un change archivado (fase 5). La rama va a PR → revisión → merge. El PR es la pieza que integra; los commits granulares quedan dentro de él.

Disciplina de sesión (limpieza de contexto)

Un contexto que crece sin control degrada la calidad de las respuestas y malgasta tokens. La regla:

  • Una sesión = una unidad de trabajo. No mezclar varios pasos o varios changes en la misma sesión.
  • Limpiar el contexto solo al cerrar la unidad, nunca a mitad de un tema.
  • Antes de limpiar, persistir todo lo valioso en archivos: decisiones, estado, progreso, hallazgos de auditoría. Nada que importe vive solo en la conversación.
  • Secuencia de cierre de unidad: sugerir commit/PR → confirmar que todo está persistido → sugerir limpiar el contexto.
  • Delegar a subagentes la lectura/análisis pesado para no llenar el contexto principal.

En Claude Code la limpieza es /clear; en otra herramienta, su equivalente (ver portability.md).

Varios desarrolladores (equipos)

Cuando varios desarrolladores comparten un proyecto Argui el proceso no cambia: cambia quién posee cada unidad de trabajo. El modelo completo —un responsable por unidad, el grafo como coordinador, el claim por rama publicada, worktrees, roles singulares y CODEOWNERS, la guarda de gobernanza en CI, el setup de equipo y el onboarding de un dev, y por qué el paralelismo vive en la iteración— está en teams.md. Lo de aquí arriba —unidad de trabajo, ramas, aislamiento, sesiones, decisiones y auditorías— es la base sobre la que ese documento construye.

Registro de decisiones

Las decisiones que el proyecto va tomando —de arquitectura, de proceso, de producto— se anotan en un decisiones.md en la raíz: una línea por decisión, con fecha, qué se decidió y por qué. Es un log histórico append-only: las entradas pasadas no se reescriben; una decisión que cambia se anota como una fila nueva que reemplaza a la anterior. Es el registro liviano que Argui prefiere sobre procesos pesados de tipo ADR (Architecture Decision Record). Plantilla: decisiones.md.template.

Ahí terminan las decisiones que salen de las auditorías, los cambios de estándar y las políticas del proyecto (p. ej. la versión de Argui y la estrategia de specs en brownfield).

Auditorías periódicas

El proyecto se revisa a sí mismo con cadencia: cada sprint o cada 5 items archivados, lo que ocurra primero. Tres focos de revisión —y, en la misma pasada, la agregación de las métricas de entrega (metrics.md)—. Se opera con el comando auditoria.

Recordatorio (capturado en el origen): la etapa archive cuenta los items archivados desde la última auditoría y, al llegar al umbral, sugiere correrla; el índice del log muestra la fecha de la última, para el disparador por sprint. No hace falta recordarlo a mano.

Specs ↔ código

A medida que se avanza, las specs pueden divergir del código o quedar atrasadas: cada ciclo sincroniza las delta specs con las principales (/opsx:sync), pero el código sigue cambiando en correcciones de QA (Quality Assurance), refactors y archives posteriores.

Qué se verifica:

  • Las specs reflejan el comportamiento realmente implementado.
  • No hay specs huérfanas (describen algo que ya no existe).
  • No hay comportamiento implementado sin spec que lo respalde.

La conduce el arquitecto (es trabajo de juicio); el listado mecánico de specs vs. módulos puede prepararlo un agente económico.

Consumo de tokens

Con el avance se acumulan artefactos que degradan la eficiencia del proceso: un CLAUDE.md inflado, agentes con un modelo más caro del necesario, skills/MCPs (Model Context Protocol) que agregan overhead sin aportar, contexto que debió podarse, fanout innecesario.

Qué se verifica:

  • Consumo real por fase y por agente; dónde se concentra el gasto.
  • Artefactos que pesan más de lo que aportan.
  • Oportunidades de bajar de tier sin perder calidad.

Medición mecánica en un agente económico (haiku); interpretación y ajuste, trabajo de juicio. Es la versión periódica del “Medición y ajuste” de efficiency.md, que arranca tras los primeros 3–5 items y de ahí en adelante se repite.

Salud de la suite de tests

La suite se degrada con el avance: tests frágiles que rompen con cambios de UI (interfaz de usuario) no relacionados, flaky que entrenan a ignorar los rojos, un tope E2E (end-to-end) que se infla. Una suite en mal estado deja de dar confianza y de correrse.

Qué se verifica:

  • Flaky tests: identificarlos y ponerlos en cuarentena o arreglarlos — nunca ignorarlos (un test que falla a veces entrena al equipo a ignorar los rojos).
  • Forma de la pirámide: ¿se está inflando el tope E2E? ¿hay lógica cubierta arriba que debería bajar a integración/unit? (ver standards.md §4).
  • Mantenibilidad: selectores frágiles, tests duplicados, cobertura de lo crítico aún vigente.
  • Velocidad: una suite lenta deja de correrse — vigilar el tiempo total.

La conduce un revisor/tester (juicio); el listado mecánico (lista de flaky, conteo por capa, tiempos) lo prepara un agente económico (haiku).

Métricas de entrega

Además de los tres focos, la auditoría agrega las métricas de resultado de la entrega definidas en metrics.md: el conteo mecánico sale de git, el artifact de QA y el backlog (agente económico); una entrevista corta cubre lo que es juicio o no quedó en ningún artefacto (ocio que infle el calendario, intervención correctiva sin registrar). No es un foco que “caza” problemas como los otros tres: es una lectura periódica que detecta si la velocidad sigue siendo confiable. Se persiste como una fila más en la tabla fechada del log — una tabla, no un dashboard.

Registro

Cada auditoría es un archivo propio del proyecto, en auditorias/ (auditorias/[fecha-sprint].md, desde auditoria.md.template): los tres focos, las acciones derivadas y la tabla de métricas de esa pasada. Un archivo por auditoría —en vez de uno que crece sin fin— es más manejable y queda inmutable una vez cerrado (log histórico append-only).

La serie de tiempo vive en un índice delgado auditorias/README.md: una fila por auditoría (fecha + métricas titulares), que el comando auditoria actualiza solo. El detalle está en los archivos; la tendencia se lee en el índice.

Si una auditoría cambia una decisión de operación o arquitectura, esa decisión va además a decisiones.md. Y como cada foco termina en candidatos priorizados, esos candidatos alimentan el grooming del backlog (más abajo).

Grooming del backlog (intake de trabajo nuevo)

En evolución continua (fase 6) el trabajo nuevo entra por cuatro fuentes y se procesa en un grooming periódico, en la misma cadencia que las auditorías (cada sprint o cada 5 items archivados). El grooming:

  • Revisa los candidatos acumulados —capturados en su origen (ver workflow.md fase 6)— y los prioriza.
  • Enruta cada uno por su carril (change directo / feature con validación / área nueva) y aplica el gate de definición-validada a los significativos.
  • Es human-in-the-loop y barato: el listado mecánico de candidatos lo prepara un agente económico (haiku); la priorización y el enrutamiento son juicio.

Captura automática, decisión humana. Que la señal llegue sola no reemplaza la decisión de que es trabajo: la captura puede automatizarse, la promoción al intake es juicio (de este grooming). Por señal (herramientas en standards.md §9):

  • Errores: el error tracker agrupa y alerta solo (puede auto-abrir un issue con release/SHA) → se decide si uno recurrente es candidato.
  • Disponibilidad: el monitor de uptime avisa solo cuando cae → se decide si revela trabajo o fue un pico aislado.
  • Uso: la analítica se acumula sola → se lee en el grooming; un patrón se vuelve idea de backlog.
  • Regresión de eval: el CI falla el build solo (gate automático, §10) → se decide si abrir un item para arreglarla.
  • Feedback de usuarios: el formulario o canal de soporte deja el mensaje solo → una persona lo tría.

Lo único que promueve trabajo sin intervención es el gate de eval en CI (bloquea el merge); el resto es captura barata + decisión en el grooming. Montar un orquestador que convierta toda señal en ticket es el tooling sobredimensionado que §9 descarta para un PMV.

Las auditorías de arriba alimentan este grooming: una auditoría no termina en un hallazgo, termina en un candidato priorizado.