Un desarrollador sabio no «empieza a programar y espera». Lleva un proyecto nuevo por brainstorming, discusión con el equipo, prototipado, diagramas, propuestas, ADR, MR/PR y GitOps — con Review Bots que generan automáticamente comentarios en PR para que los humanos inviertan tiempo en lo que importa. Este es el playbook de nivel producción. Un FDE puede levantar el sistema; la Claude Architect Certification vale la pena si quieres diseñarlo y defenderlo.
1. Qué significa «sabio» en un proyecto nuevo
La sabiduría no son más reuniones. Es aprendizaje barato temprano y errores caros tardíos hechos raros. La secuencia siguiente está ordenada para que cada paso reduzca el radio de explosión del siguiente:
Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
→ Implement in small slices → MR/PR + Review Bot → Merge
→ GitOps promote (dev → staging → prod) → Observe → Iterate
Omita pasos solo con intención (p. ej. un arreglo de config de una línea). Nunca omita Review Bot + CI en nada que pueda llegar a producción.
2. Brainstorming (solo primero, luego estructurado)
Antes de pedir tiempo a nadie, dedique 30–90 minutos solo:
- Resultado: ¿qué cambio de usuario/negocio debe ser cierto cuando terminemos?
- Restricciones: tiempo, presupuesto, cumplimiento, plataformas existentes, habilidades del equipo.
- No-objetivos: lo que no construiremos en v1 (protege el alcance).
- Riesgos: datos, seguridad, rendimiento, vendor lock-in, carga operativa.
- Métricas de éxito: latencia, tasa de error, adopción, coste — elija dos que importen.
Capture esto en una nota breve (Notion/Confluence/markdown en el repo bajo docs/ideas/). Brainstorming sin artefacto escrito es solo conversación que se evapora.
3. Discusiones con compañeros
Invite al círculo útil más pequeño: un par que implementará con usted, alguien que posee el sistema adyacente y (si hace falta) seguridad o SRE. Reglas para mantenerlo sabio:
- Time-box (25–45 minutos). Termine con decisiones o preguntas abiertas — no vibes.
- Disienta sobre opciones, no personas. Fuerce «opción A vs B vs diferir.»
- Asigne un scribe. La nota se convierte en la semilla de la propuesta.
- Sin vetos silenciosos. Si alguien está incómodo, escriba la preocupación como riesgo en el ADR después.
Lo asíncrono también funciona: un hilo corto de comentarios RFC a menudo supera una reunión — pero alguien debe cerrar el bucle.
4. Prototipado (spikes con fecha de caducidad)
Prototipe cuando la incertidumbre es alta: una API nueva, un servicio cloud poco familiar, una pregunta de rendimiento o comportamiento de IA/agente. Reglas sabias:
- Nómbrelo spike en el ticket; fije una parada en el calendario (1–3 días típicos).
- Mantenga el código en una rama desechable o carpeta
spikes/; no pule. - Anote lo aprendido en 10 viñetas — especialmente lo que falló.
- Decida: promover (refactorizar al producto), reescribir o abandonar.
Los prototipos que se convierten silenciosamente en producción sin ADR son cómo los equipos heredan arquitectura accidental.
5. Diagramas (suficientes para discutir)
No necesita una novela UML. Prefiera tres bocetos que quepan en una pantalla cada uno:
| Diagrama | Responde |
|---|---|
| Contexto (C4 L1) | ¿Quién habla con qué? ¿Límites de confianza? |
| Secuencia | Camino feliz + un camino de fallo |
| Despliegue | Dónde corre; cómo fluyen config y secretos |
Guarde Mermaid o imágenes junto a la propuesta (docs/architecture/). Actualice diagramas cuando cambien los ADR — imágenes obsoletas son peores que ninguna.
6. Propuestas (RFC ligero)
Una buena propuesta tiene de una a tres páginas:
- Problema y por qué ahora
- Opciones consideradas (al menos dos)
- Recomendación y por qué
- Impacto: seguridad, coste, ops, migración
- Rollout y rollback
- Preguntas abiertas
Pida revisión con un plazo claro. Cuando se apruebe (o con enmiendas), convierta la decisión en ADR — no deje la «fuente de verdad» en el chat.
7. ADR — Architecture Decision Records
Un ADR es un registro corto, inmutable por convención, de una decisión. Plantilla:
# ADR-00XX: Title Status: Proposed | Accepted | Superseded by ADR-00YY Date: YYYY-MM-DD Deciders: @alice @bob ## Context What forces are in play? ## Decision What we will do. ## Consequences Positive, negative, and follow-ups. ## Alternatives considered Option A — why not Option B — why not
Mantenga los ADR en git (docs/adr/). Enlácelos desde las PR. Sustituya en lugar de reescribir la historia — su yo futuro necesita el rastro.
8. MR y PR — la unidad de entrega
MR (Merge Request, GitLab) y PR (Pull Request, GitHub/Bitbucket) son la misma idea: un conjunto de cambios revisable. Hábitos sabios:
- Pequeño: idealmente <400 líneas de diff significativo; divida en slices verticales.
- Una intención: una feature, fix o chore — no «misc.»
- Descripción: por qué, cómo probar, capturas/logs, riesgo, rollback.
- Enlaces: ticket + ADR + diagrama de diseño.
- Draft primero cuando quiera feedback temprano sin implicar «listo para merge.»
- Nunca force-merge alrededor de CI rojo o findings de bot de alta severidad sin excepción escrita.
Ejemplo de checklist del cuerpo de PR
## Summary - … ## Test plan - [ ] Unit tests - [ ] Manual path … - [ ] Feature flag / config … ## Risk & rollback - Risk: … - Rollback: revert this PR / GitOps revert commit … ## References - ADR-00XX - Ticket ABC-123
9. Uso del Review Bot — comentarios PR auto-generados
Un Review Bot es un revisor automatizado que publica comentarios inline y resúmenes en cada MR/PR. No reemplaza a los humanos; anticipa lo aburrido y lo peligroso.
9.1 En qué debe comentar el bot
- Seguridad: injection, huecos de authz, fuga de secretos, defaults inseguros
- Correctness: caminos null, race conditions, migraciones rotas
- Tests: cobertura faltante en ramas nuevas, abuso de snapshots
- API/contrato: cambios breaking sin bump de versión
- Ops: timeouts faltantes, sin idempotencia, retries ilimitados
- Estilo solo cuando escapó del formatter/linter (evitar ruido)
9.2 Cómo agiliza la vida del desarrollador
- El autor abre la PR → el bot corre en segundos a minutos.
- El autor corrige o responde a hilos del bot antes de pedir humanos.
- El revisor humano lee el resumen del bot + se centra en diseño y riesgo de producto.
- Menos rondas de «nits»; merge más rápido; menos incidentes del viernes por footguns perdidos.
9.3 Opciones típicas de setup
| Enfoque | Notas |
|---|---|
| SaaS Review Bot (p. ej. CodeRabbit, bots de vendor) | Rápido de activar; ajuste severidad y filtros de path |
| Cursor Bugbot / revisión ligada al IDE | Fuerte en diffs de PR en equipos centrados en Cursor |
| GitHub Action custom + Claude / LLM | Control total; necesita prompt + política + topes de coste |
| Pipeline en capas (lint → SAST → LLM) | Mejor postura de producción — ver guía de pipeline de revisión de código IA |
9.4 Política que mantiene útil al bot
- Etiquetas de severidad: blocker / should-fix / nit — los nits no deben bloquear el merge.
- Ignorar paths generados (
vendor/, ruido de lockfiles, dumps protobuf). - Requerir aprobación humana para paths sensibles de seguridad (
auth/,infra/, IAM). - Registrar falsos positivos; reinyectarlos en reglas de ignore mensualmente.
- Nunca deje que el bot sea el único revisor en servicios críticos de producción.
9.5 Esbozo mínimo de GitHub Action
# .github/workflows/review-bot.yml
name: review-bot
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Review Bot
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
run: |
# Fetch diff, call your review CLI, post review comments via gh api
./scripts/review-bot.sh
Implemente review-bot.sh para: calcular el diff de la PR, llamar a su modelo con un system prompt estricto (seguridad + correctness primero) y publicar comentarios con la API de GitHub/GitLab. Tope tokens y omita drafts si el coste preocupa.
10. Mejores prácticas GitOps para calidad production-grade
GitOps significa: el estado deseado vive en git; un reconciliador (Argo CD, Flux, etc.) hace que el cluster coincida; la promoción es un merge; el rollback es un revert.
- Separar código de app y config de env (o carpetas claras:
apps/vsenvs/dev|staging|prod). - No kubectl apply a prod como camino feliz — solo break-glass, auditado.
- Entrega progresiva: auto-sync en dev; sync manual o gated para prod.
- Digests de imagen sobre tags mutables en manifests de prod.
- Policy as code: OPA/Kyverno para privilegios, registries, límites de recursos.
- Commits firmados / provenance donde su threat model lo requiera.
- Observar tras sync: health checks, error budgets, hooks de rollback automático cuando estén listos.
La calidad del código no es solo «funciones limpias.» También es cómo el cambio entra en producción. GitOps hace ese camino revisable, reversible y repetible.
11. Gates de calidad de extremo a extremo (optimizados para producción)
Local: pre-commit (fmt, lint, secrets) + unit tests PR open: CI (build, test, SAST) + Review Bot comments PR merge: human approve + branch protection + required checks Main: build immutable artifact (image digest) GitOps: update env repo / overlay → sync → verify Prod: SLOs + alerts + runbook linked from ADR/PR
12. Rol FDE — quién monta este sistema
Un Forward Deployed Engineer es ideal para instalar el sistema del desarrollador sabio dentro de un equipo real:
- Plantillas de repo:
docs/adr/, plantilla PR, CODEOWNERS, branch protection - Review Bot + secrets + controles de coste
- Checks CI requeridos y protecciones de entorno
- Apps GitOps (dev/staging/prod) y docs de promoción
- Coaching de dos semanas: primer ADR, primera PR afinada por el bot, primer drill de rollback GitOps
Calendario indicativo para enablement liderado por FDE en un repo de producto: 1–2 semanas para scaffolding y política del bot; +1–2 semanas para la ruta de promoción GitOps y un rollback en seco. El cambio cultural tarda más — mida tiempo de merge y defectos escapados, no installs de herramientas.
13. Claude Architect Certification — vale la pena
Si diseña sistemas donde humanos y agentes de IA coescriben código, la Claude Architect Certification vale la pena. Señala que puede:
- Arquitectar entrega asistida por IA sin tratar el modelo como infalible
- Especificar políticas de revisión, guardrails y evaluación para workflows agenticos
- Comunicar trade-offs (latencia, coste, privacidad, precisión) a stakeholders
- Entrenar equipos en ADR, disciplina PR y gates de producción junto a herramientas IA
Empareje la credencial con entrega real: levante un Review Bot, escriba tres ADR y ejecute un drill de rollback GitOps. El papel sin práctica no le hace sabio; la práctica más un lenguaje compartido sí.
14. Anti-patrones (cómo se ve lo imprudente)
- PR gigante con «WIP please approve ASAP»
- Arquitectura decidida solo en Slack, nunca en ADR
- Prototipo mergeado a prod sin tests
- Desactivar Review Bot porque «molesta»
- Hotfix a prod fuera de GitOps sin plan de revert
- Humanos repitiendo nits de formatter que el bot ya capturó
15. Checklist starter copy-paste para un proyecto nuevo
- Crear
docs/ideas/,docs/architecture/,docs/adr/ - Añadir plantilla PR/MR + CODEOWNERS
- Habilitar pre-commit + checks CI requeridos
- Instalar Review Bot; ajustar filtros de path y severidades
- Escribir ADR-0001: «We use GitOps for deploy»
- Definir entornos y reglas de promoción
- Programar un game day de rollback de 30 minutos
- Reservar tiempo FDE para coaching del primer mes; considerar Claude Architect Certification para leads
16. Cierre
Un desarrollador sabio trata un proyecto nuevo como una secuencia de artefactos de aprendizaje — notas, diagramas, propuestas, ADR — y luego entrega mediante MR/PR pequeños vigilados por un Review Bot y promovidos por GitOps. Así se optimiza la calidad del código para production grade sin quemar al equipo en nits interminables. Deje que un FDE instale los raíles; deje que arquitectos certificados mantengan el sistema honesto mientras la IA acelera cuán rápido puede escribir código.
Publicado por Workstation.
