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/ítem 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. La configuración se parte en dos: la línea base de seguridad se versiona (quien clona hereda el aislamiento) y lo específico de cada máquina —rutas absolutas de toolchains, carpetas externas— queda fuera del repositorio. Implementación de referencia para Claude Code en Aislamiento del entorno. El aislamiento acota lo que el asistente lee; el .gitignore acota lo que el repositorio publica. Por eso la fase 0 también pone el .gitignore de partida —con initial-references/, los .env y los volcados de base de datos— antes de que llegue el primer archivo confidencial (F0.3).

• 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.

Las dos capas del Nivel 1 no cubren lo mismo, y eso cambia cómo se trabaja: lo que vive fuera del repositorio —la metodología clonada aparte, un repo hermano, una carpeta de referencia— queda al alcance de las herramientas de archivo del asistente, no de los comandos de shell. Se consulta leyéndolo; un cat o un grep falla como si la ruta no existiera, aunque el archivo esté ahí. Abrir esa carpeta también a los comandos es una excepción que se declara, no el punto de partida. Cuando la ruta es propia de la máquina, va como nota operativa en el CLAUDE.md (ver CLAUDE.md vivo).

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 Portabilidad).

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/ítem 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 ítem del backlog en fase 5 (feat/PRJ-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 Equipos).

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 Métricas); 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 — ni en la memoria del asistente, que no es un archivo: no se versiona ni la ve el resto del equipo (ver CLAUDE.md vivo → Directivas operativas).
• 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 Portabilidad).

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 Equipos. 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: Registro de decisiones.

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 ítems archivados, lo que ocurra primero. Cuatro focos de revisión —y, en la misma pasada, la agregación de las métricas de entrega (Métricas)—. Se opera con el comando auditoria.

Recordatorio (capturado en el origen): la etapa archive cuenta los ítems 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, que arranca del índice de changes archivados (qué se construyó, sobre qué capabilities y con qué RF-*) en vez de leer las carpetas archivadas completas — ver Las 7 fases F5.1.

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 Eficiencia, que arranca tras los primeros 3–5 ítems 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 Estándares §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).

Seguridad del producto

El pase de seguridad de verify mira un change a la vez, y solo cuando el gate lo marca. Un producto puede tener todos sus changes limpios y aun así ser inseguro: lo que se acumula —superficie expuesta, permisos que se fueron ensanchando, dependencias que envejecieron, secretos que se colaron en el historial— no lo ve ningún change individual.

Este foco revisa lo que ningún gate automático cubre: buscar a mano lo que el CI ya busca en continuo (vulnerabilidades conocidas, Estándares §11) sería duplicar trabajo.

Qué se verifica:

• Superficie expuesta: endpoints, puertos y buckets públicos que nadie decidió abrir.
• Autorización: los permisos por rol siguen siendo los que dicen las specs, sin ensanches acumulados.
• Secretos: nada en el repositorio ni en el historial; la rotación pendiente, anotada.
• Dependencias: el estado del mecanismo, no los CVE (Common Vulnerabilities and Exposures) —de esos se ocupa el audit de CI (§11)—: excepciones vencidas, PRs del bot acumulados sin merge (el síntoma de que el gate se está ignorando), dependencias sin mantenimiento (que no generan ninguna alerta) y deriva de majors: cuántas versiones atrás va el proyecto.
• Datos sensibles: qué se registra en logs y qué se retiene, contra lo que el PRD declaró y contra el enmascarado que el logger debería estar aplicando (Estándares §9).

La conduce un revisor con perspectiva de seguridad (juicio); el listado mecánico —dependencias, rastreo de secretos, inventario de endpoints— lo prepara un agente económico.

Métricas de entrega

Además de los cuatro focos, la auditoría agrega las métricas de resultado de la entrega definidas en Métricas: el conteo mecánico sale de git, el artefacto 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 cuatro: 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 Auditoría): los cuatro 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 refinamiento del backlog (más abajo).

Refinamiento del backlog (recepción de trabajo nuevo)

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

• Revisa los candidatos acumulados —capturados en su origen (ver Las 7 fases 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 a la recepción es juicio (de este refinamiento). Por señal (herramientas en Estándares §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 refinamiento; 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 ítem 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 refinamiento. 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 refinamiento: una auditoría no termina en un hallazgo, termina en un candidato priorizado.