Mon usine logicielle à l'heure de l'IA

Puntos clave

1. ⭐ La rejilla de tres preguntas — la enseñanza más reutilizable. toda la instrumentación responde a "¿Qué sabe el agente?" (contexto, memoria, grafo de código), "¿Qué puede hacer de forma determinista, sin improvisar?" (skills, procedimientos), "¿Qué lo detiene cuando se equivoca?" (hooks, tests de arquitectura, quality gates). Rejilla de auditoría instantánea: aplicada a cualquier configuración agéntica, revela en tres minutos cuál de las tres está vacía. Casi siempre es la tercera.
2. ⭐⭐ El principio rector, que merece memorizarse textualmente. "Lo que importa debe ser ejecutable. Una instrucción se sigue 'la mayor parte del tiempo', pero puede olvidarse. Un hook o un test se sigue siempre." Formulado de forma aún más tajante en otro pasaje sobre los tests de arquitectura: "no se puede eludir, a diferencia de una regla." → Una regla es una intención, un test es una garantía. Es la misma tesis que el anillo de restricciones en [[sfeir-code-review-anneau-contraintes-2026-07-30]] (publicado dos días después) y el harness en [[osmani-agent-harness-engineering-2026-04-19]], pero demostrada en una configuración real, en solitario, no enunciada como doctrina.
3. Explícitamente en contra del vibe coding. "El vibe coding tal como lo define Karpathy era experimentación y soltar el control. Aquí voy a hablar de context engineering." Y la cláusula de responsabilidad resultante: "Aunque no escriba el código, soy responsable de él y debo mantener el control sobre él." Cf. [[karpathy-vibe-coding-agentic-engineering-software-3-0-2026-04-29]].
4. La calidad del software no es la calidad del código. incluye la intención (por qué, para quién) y los cuatro riesgos de Marty Cagan — Value, Usability, Feasibility, Viability— además del rendimiento y la fiabilidad. Esto es lo que justifica la capa 6 (proceso de producto) y explica por qué una fábrica de software puramente técnica pierde el sentido.
5. Capa 1 — contexto, y el movimiento que vale la pena copiar. tres niveles separados por su momento de carga. CLAUDE.md raíz (arquitectura, convenciones transversales, índice de specs) → permanente y corto; .claude/rules/.md → condicional, activado por un frontmatter paths: (la regla de Kotlin se carga solo al tocar api//); .agents/.md → contexto no técnico (posicionamiento de producto, personas, tono). ⭐ La regla, vista en su totalidad, es una tabla de enrutamiento: no contiene los procedimientos, enumera nueve skills con la tarea que dispara cada una, para abrirse solo cuando se necesita. "Si la IA no está haciendo un cambio de esquema, no tiene sentido abrir la skill db-migration." → El contexto permanente lleva el índice, no el contenido.*
6. ⭐ Una restricción a largo plazo codificada como contexto y como test. — el mejor ejemplo del texto: el autor planea liberar parte del código como open source. La regla "el código destinado a ser open source nunca debe depender de código propietario" está escrita en las rules y verificada por un test de arquitectura (ningún archivo del lado "abierto" hace referencia al lado "propietario"; cada archivo de producción pertenece a uno u otro lado). "Escribir una restricción futura en el contexto evita pagar una reescritura más adelante." → Una decisión que aún no existe ya puede garantizarse mecánicamente.
7. La frase que mata el prompt mágico. "No sirve de nada decirle a una IA que 'escriba código de calidad', no significa nada. Hay que hacer explícitas las propias restricciones." Acompañada de una honestidad poco frecuente: "Una restricción es específica de un proyecto y una persona… Usar feature flags no es mejor ni peor, es solo mi preferencia."
8. Capa 2 — skills. "un procedimiento escrito una vez, reproducido de forma idéntica." Criterio de existencia: la tercera repetición. Una treintena, repartidas en seis familias (backend, frontend, datos, ciclo de producto, operaciones/runbooks, redacción). Dos lecciones: las skills de "procedimiento multiarchivo" son las más rentables ("añadir un bloque al editor de contenido toca tres superficies de renderizado; sin una skill, el agente olvida sistemáticamente una"), y las skills de "documentación al día" son críticas en código que evoluciona rápido. ⚠️ Matiz operativo: "Esta carga automática a veces puede fallar. En ese caso, hay que pedir explícitamente usar la skill." Cf. [[shihipar-claude-code-lessons-building-skills-2026-06-03]], [[agent-skills-anthropic-2025-10-16]], [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]].
9. Los sub-agentes, en declive. reservados para tareas "que generan mucha lectura sin mucha toma de decisiones" (auditorías, exploración amplia, redacción de documentación) — "consumen su propio contexto y devuelven una conclusión, no un volcado de archivos." Pero: "los uso cada vez menos, los agentes recientes hacen ellos mismos una delegación bastante focalizada." Señal de evolución: una práctica de instrumentación parcialmente vuelta obsoleta por el modelo.
10. ⭐ Capa 3 — GitNexus, la herramienta más interesante del dispositivo. el repositorio se indexa como un grafo (símbolos, relaciones, flujos de ejecución), lo que permite impact(symbol) antes de modificar (radio de impacto, llamadores, nivel de riesgo), detect_changes() antes de hacer commit ("¿toqué solo lo que quería tocar?"), buscar un flujo de ejecución en lugar de hacer grep de un nombre de función, y renombrar vía el grafo de llamadas en lugar de buscar y reemplazar. Y la justificación, que importa más que la herramienta en sí: "El verdadero problema no es la velocidad, es detectar todos los efectos secundarios de un cambio." → trasladado a la regla n.º 4: "Medir los impactos antes y después de la edición. Queremos evitar el efecto '1 bug corregido, 10 introducidos'." Vale la pena comparar el contexto estructurado en grafo de código frente al RAG vectorial — la misma familia de argumento que el resultado de Compare the Market citado en [[sfeir-code-review-anneau-contraintes-2026-07-30]].
11. MCP, con una advertencia de coste. "intento evitar los MCP que consumen más contexto, pero aun así tengo algunos" — IDE JetBrains (build, inspecciones, refactorizaciones, búsqueda indexada), GitNexus, servicios de negocio (pago, monitorización), base de datos, navegador. El MCP se trata como un gasto de contexto que hay que justificar, no como algo dado por sentado.
12. Capa 4 — hooks: la definición que importa. "scripts disparados por el harness del agente, no por el agente mismo." Dos usos en producción: antes de una llamada de shell, rechazar el build nativo y redirigir al build del IDE (más rápido, errores estructurados) explicando el fallback; después de escribir un archivo, ejecutar el formatter/linter. Otros usos citados: bloquear ediciones a archivos generados, exigir un test junto a cualquier módulo nuevo, prohibir un patrón peligroso.
13. ⭐ Pattern linting — la distinción que vale la pena retener. ESLint para la sintaxis, ast-grep para decisiones de arquitectura (ejemplo: prohibir cualquier llamada fetch que evite el cliente OpenAPI), typecheck para el tipado. → Una decisión de arquitectura puede convertirse en una regla de lint. Es el eslabón que falta entre "lo decidimos" y "se aplica", y cuesta unas pocas líneas.
14. Capa 5 — el gate. push to main → quality gate (lint → pattern lint → typecheck → tests) → build docker image → push to registry → deployment webhook. El punto estructural: el job de despliegue tiene un needs: sobre el job de calidad. "Nada llega a producción sin pasar el gate. Eso es esencial como regla general, más aún para código producido automáticamente." Cinco etapas de pruebas: unitarias (intensivamente), de integración con contenedores desechables ("base de datos y broker reales, sin mocks"), de arquitectura, de componentes front-end, end-to-end solo en los caminos críticos. Cf. [[williams-adlc-3-tests-are-the-spec-2026-06-12]] y [[williams-adlc-2-two-human-gates-2026-06-12]].
15. Capa 6 — el proceso de producto, y el paso que todo el mundo olvida. specs numeradas (una por dominio funcional, indexadas en el contexto permanente) enmarcadas por dos skills — una para redactar la spec y su plan, otra para cerrarla actualizándola con lo que realmente se construyó. "Sin ella, las specs quedan obsoletas en seis meses," y como regla final: "La documentación de la spec muere si su cierre no forma parte del proceso." ⭐ El cierre es la parte del ciclo de documentación que casi nunca existe en otros lugares.
16. Regla anti-alucinación para las specs. "Si una spec no es clara o es incoherente con el sistema existente, el agente debe preguntar, no adivinar." Una sola línea de contexto que aborda el modo de fallo más costoso del desarrollo agéntico.
17. Entrega escalonada, y su razón de ser. la spec está diseñada para entregarse en etapas protegidas por un feature flag, "me permite hacer varias sesiones de implementación pequeñas en lugar de una sesión grande, que tiende a degradarse en calidad cuando se llena demasiado." → Aquí, la descomposición del producto está dictada por la degradación del contexto largo, no por la gestión de proyecto. Distinción útil: feature flipping (Unleash — activar/desactivar sin redesplegar: rollout, kill switch, mantenimiento) frente a gating (tabla de configuración + servicio — restringir según el contrato o plan del cliente). Dos mecanismos, dos necesidades, y una skill para que los agentes no los confundan.
18. Por dónde empezar (orden dado, y es bueno). (1) primero el quality gate, si aún no existe; (2) un CLAUDE.md ligero que describa lo esencial y el porqué; (3) rules añadidas de forma incremental para los patrones de arquitectura importantes; (4) skills en cuanto un procedimiento se repite; (5) CLI y MCP para las herramientas principales. ⚠️ Advertencia de seguridad: "cualquier skill, MCP o código importado del exterior debe examinarse con lupa. Son dependencias que pueden ser vectores de ataque." Vale la pena compararlo con la superficie de ataque agéntica descrita en [[clinton-anthropic-secure-ai-native-sdlc-2026-07-21]].
19. ⚠️ Limitaciones vividas — la sección que da credibilidad a la página. 1. La obsolescencia de una regla no es medible. "A mediados de 2025, 'escribe un test para cada nuevo servicio' tenía sentido. Hoy es ruido y Claude lo hace de forma natural… no tengo forma de medir o saber si una regla antigua se ha vuelto obsoleta." → El contexto acumulado se degrada al ritmo de los modelos, y nada rastrea esa degradación. Es la verdadera brecha metodológica del campo, y aquí se nombra sin solución. 2. El rabbit hole. Una regla boyscout.md ("deja siempre el código un poco mejor… márcame las mejoras") produce "sesiones interminables" y sobrecarga cognitiva. Solución prevista: encauzar estos hallazgos hacia una lista de TODO y trasladar el mantenimiento a un flujo de trabajo separado, parcialmente automatizado. → Una buena instrucción de mejora continua se convierte en un generador de deriva cuando el agente no se detiene por sí solo. 3. Sin empaquetado. Las skills y las rules se copian y pegan de proyecto en proyecto, a veces dependientes de la máquina. Falta: una forma de empaquetar para el despliegue y centralizar el mantenimiento. 4. Dependencia de Claude, calificada de "riesgo moderado" ("todo el ecosistema está subiendo de nivel"), con interés en probar modelos de pesos abiertos — bloqueado por el hardware. Y el IDE ha dejado de encajar bien: "sigo usando IntelliJ pero ya no lo encuentro adecuado para nuestra época. Aún no he visto una alternativa interesante."
20. ⭐⭐ La admisión de fondo, que merece citarse textualmente. "Las últimas versiones de Opus son cada vez más autónomas… Es rozando lo inquietante, y más riguroso que el 99% de los humanos. Seamos honestos, cada vez soy menos útil en las fases de implementación, pero no quiero perder el control del código producido. Estoy dividido entre la satisfacción de tener una fábrica de software cada vez más eficiente y el riesgo de perder el conocimiento." → Es exactamente la deuda de comprensión de [[osmani-cognitive-surrender-comprehension-debt-2026-05-05]], expresada desde dentro por alguien que construyó el harness más completo posible y constata que el harness no resuelve ese problema en particular. El dispositivo garantiza que el código es correcto; no garantiza que el humano todavía lo entienda. La pregunta abierta del texto: "necesito encontrar una forma de revisar los diseños a posteriori, para hacer mío el resultado."
21. ⚠️ Alcance que no hay que sobrestimar. un dispositivo en solitario, sobre productos personales, con un único responsable de decisión. Sin coordinación multideveloper, sin peer review, sin restricciones de cumplimiento o auditoría — la capa de "quién valida" la ocupa una sola persona, que además es la autora de las rules. Lo que se traslada a un entorno empresarial: la rejilla de tres preguntas, el principio de lo ejecutable, el cierre de specs, el pattern linting. Lo que no se traslada tal cual: la ausencia total de cualquier gate humano que no sea uno mismo.
22. Meta / relacionados. una demostración práctica de [[osmani-agent-harness-engineering-2026-04-19]] y un primo directo de [[sfeir-code-review-anneau-contraintes-2026-07-30]] (publicado 2 días después, misma tesis: la calidad reside en el anillo de restricciones, no en el código); el mismo vocabulario de "fábrica de software" que [[wescale-usine-logicielle-augmentee-juge-strategique-2026-05-03]], pero a la escala de un solo individuo; se opone al vibe coding de [[karpathy-vibe-coding-agentic-engineering-software-3-0-2026-04-29]]; converge con [[klaassen-teach-ai-think-senior-engineer-every-2025-11-07]] en hacer explícitas las restricciones; para leer junto con [[shihipar-claude-code-lessons-building-skills-2026-06-03]] sobre skills y [[williams-adlc-3-tests-are-the-spec-2026-06-12]] sobre tests.