anvil · cliente HTTP
Charla técnica · IA + Diseño de software

Decisiones
conscientes

Diseñar con IA antes
de escribir código

Cris Llanos· Engineering Lead· cristianllanos.com
Quién habla

Cris Llanos

Rol

Engineering Lead

11+ años construyendo software que escala a millones, en 18+ países.

Open source

Herramientas para devs

reliese/laravel (3M+ descargas) · kotlin-container · kotlin-events.

Hoy construyo anvil — un cliente HTTP de escritorio. Será nuestro ejemplo de principio a fin.

Abres tu propio código de hace 3 meses…

“¿Por qué lo
hice así?”

La decisión existió.

Nadie la escribió.

El problema

Las decisiones implícitas
se evaporan.

Tú en 3 meses, el siguiente dev, o un agente de IA: todos re-derivan, rediscuten y adivinan mal.

Y con IA, se agudiza

El agente, literalmente,
no tiene memoria entre sesiones.

Si no externalizas la decisión, la vuelve a tomar — y distinto.

“

Un spec es un contrato con un agente que no tiene memoria.

— mi forma de pensar un spec

El giro

Diseñar con IA no es lo que crees

✗ No es

Que la IA escriba tu código

El cliché. Autocompletado con esteroides.

✓ Sí es

Que la IA te haga pensar

Articular la tensión, sacar tradeoffs y producir un contrato ejecutable.

  PARTE 01

Cómo funciona
/spec

La filosofía

Es una conversación,
no un documento.

→Presenta opciones con tradeoffs — tú decides
→Corta sin piedad “¿de verdad lo necesitamos?”
→No escribe código: solo diseña

El ROADMAP es la única fuente de verdad.

Paso 1 · Restricciones

Antes de la visión,
lo que la condiciona.

→Geografía, dinero, legal
→Infra y servicios que ya tienes
→Quién opera y cómo se despliega
→Prior art qué funcionó · qué dolió

No avanza hasta tenerlas claras.

Paso 2 · Visión

Empieza por la fricción —
y el pitch de una frase.

Para quién · cuál es el dolor

Si no lo dices en una frase…

…la visión todavía no está clara.

Pasos 3–4 · Decidir

Opciones con tradeoffs.
Una recomendación. Tú decides.

→3–4 opciones con pros y contras
→Corta lo que no se gana su lugar
→Organiza en fases MVP · alto valor · nice-to-have
→Gut check ¿sigue siendo lo que quieres construir?
Documenta · el qué

El ROADMAP
captura el qué.

Visión, comportamiento y fases — y lo que no se hace, explícito.

ROADMAP.md
# Roadmap · Environment Editor

Gestión in-app de variables:
máscaras de secretos, edición
tabla/raw e import/export.

## Non-goals
- Sync de entornos en equipo
- Almacenamiento cifrado
- Herencia de entornos
Documenta · el cómo

Decidido el qué,
el cómo es mecánico.

Tipos, data flow, edge cases. La IA lo ejecuta sin adivinar.

src-tauri/environment.rs
// environment.rs · auto-migración
fn migrate_variable(v: &Value)
  -> EnvVariable {
  match v {
    Value::String(s) =>
      EnvVariable {
        value: s.clone(),
        secret: false,
      },
    Value::Object(_) =>
      from_value(v.clone())
        .unwrap_or_default(),
    _ => EnvVariable::default(),
  }
}
El artefacto más importante

Decidido ·
Por qué ·
Rechazado

El oro está en lo Rechazado: evita rediscutir lo ya decidido.

docs/DECISIONS.md
## 002 · Enmascarado de secretos

Decidido:
  convención + flag explícito.

Por qué:
  la convención cubre el 90%;
  el flag maneja las excepciones.

Rechazado:
  ✗ sin máscara (maneja API keys)
  ✗ solo convención
  ✗ solo explícito (se olvida)
Antes de cerrar · Self-audit

El skill se auto-audita.

01Redundancia ¿esta capa protege algo que otra ya cubre?
02Conflicto ¿alguna decisión contradice a otra?
03Migración orden de despliegue · ventana rota
04Async / timing ¿race conditions o estado viejo?
05Datos existentes ¿rechaza datos ya guardados en prod?

Atrapa ~80% de los problemas en diseño, no en código.

Antes de cerrar · Quality check

¿Una sesión nueva implementa
el paso 1 sin preguntar?

✓Implementa el paso 1 sin preguntas
✓Sin búsquedas web ni exploración de API
✓Cada decisión tiene su rationale
Documentar & handoff

Docs para que otra sesión —
o un agente — ejecute sin ti.

ROADMAP.md
el plan + fases
CLAUDE.md
reglas + arranque
PROGRESS.md
dónde retomar
DECISIONS · ARCH
porqués + diseño

El CLAUDE.md trae la regla para IA: el proceso principal orquesta y delega en subagentes — el contexto es el recurso escaso.

  PARTE 02 · EN VIVO

Speceamos
una feature nueva

En vivo · /spec

Encadenar la respuesta
en el siguiente request.

→Referencia inline (@request) vs captura explícita
→Resolución ¿se cachea la respuesta o se re-ejecuta?
→Masking reusar la convención isSecret (decisión 002)
→Persistencia ¿sobrevive al reinicio? → ¿Non-goal?
login.http
### Login
POST {{base_url}}/auth/login
Content-Type: application/json

{ "email": "{{email}}" }

### Perfil
GET {{base_url}}/me
# ← lo único nuevo
Authorization: Bearer {{@login.data.token}}
Para llevar

Técnicas que te puedes
robar hoy.

01Diseña antes de codear una conversación, no un documento
02Opciones con tradeoffs una recomendación, decides tú
03Auto-audítate redundancia · conflicto · migración · timing
04Decisiones con Rechazado evita rediscutir lo ya cerrado
05Codifica tu proceso en un skill tu taste, reutilizable
El payoff

El ciclo completo

Conversación→ ROADMAP→ DECISIONS→ ARCHITECTURE→ Código

Tú-del-futuro no rediscute. Un dev nuevo — o un agente — ejecuta sin alucinar.

El reto

Tu próxima feature:
no abras el editor.

01La fricción y el pitch, en una frase.
02Opciones con tradeoffs — y elige.
03Escribe qué rechazaste, y por qué.
04Pásale el self-audit (5 chequeos).
05¿Lo implementarían sin preguntarte? Recién ahí, codea.

La decisión que hoy
no escribes

es el bug que mañana
vas a depurar.

Gracias· Cris Llanos· cristianllanos.com
01 / 25
← → navegar · Ctrl E buscar · F pantalla completa