<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ariel Alejandro Wagner on Medium]]></title>
        <description><![CDATA[Stories by Ariel Alejandro Wagner on Medium]]></description>
        <link>https://medium.com/@arielwagnermovil?source=rss-10ff0a47ac49------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*3p80TcT5YWzVGJgQaqyW4w.png</url>
            <title>Stories by Ariel Alejandro Wagner on Medium</title>
            <link>https://medium.com/@arielwagnermovil?source=rss-10ff0a47ac49------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 11:24:07 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@arielwagnermovil/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Reverse Engineering for Migrating from a Legacy Project to an SDD (Spec-Driven Development) Model…]]></title>
            <link>https://medium.com/@arielwagnermovil/reverse-engineering-for-migrating-from-a-legacy-project-to-an-sdd-spec-driven-development-model-72dbf0c2b97f?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/72dbf0c2b97f</guid>
            <category><![CDATA[reverse-engineering]]></category>
            <category><![CDATA[sdd]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Thu, 22 Oct 2026 22:21:49 GMT</pubDate>
            <atom:updated>2026-10-22T22:21:49.088Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0-s8NLe9eq8_zvMnFrJj_w.jpeg" /></figure><h3>Reverse Engineering for Migrating from a Legacy Project to an SDD (Spec-Driven Development) Model Using AI</h3><h4>Introduction</h4><p>There is a clear “<em>before and after</em>” in the evolution of modern software development. Today, software development leverages the full range of advantages offered by AI (<em>Artificial Intelligence</em>). Modern, AI-driven development goes well beyond approaches like “<em>vibe coding</em>.” Instead, professional development employs efficient architectural patterns — such as SDD (<em>Spec-Driven Development</em>) — where the software is built based on a specific set of defined specifications.</p><p>In the past, software development — which I will refer to as “<em>legacy development</em>” — relied on a fully manual, highly artisanal process, requiring constant human intervention. This raises a critical question for the future: how can we migrate, maintain, or scale software built using these legacy methods into a modern, AI-driven framework? This is a significant and challenging question — one that every software engineer or architect will eventually have to face.</p><p>In this article, we will analyze and outline several ideas that could prove highly useful when migrating from legacy software development to an AI-driven approach.</p><h4>Initial Strategic Analysis</h4><p>Many of us might be tempted to let AI handle the entire migration process — documentation, implementation, and so on — on its own. As you might expect, this is not advisable. Several factors can influence the process. Essentially, the key is not to simply ask AI to generate `spec.md`, `plan.md`, and `tasks.md` files in isolation based solely on the source code. Instead, the recommended approach is to design a reverse-engineering process that reconstructs functional specifications, architectural decisions, business rules, and system evolution tasks — all while maintaining traceability between the existing code and the generated documentation. While AI can, through reverse engineering, uncover what software does, it is not advisable to let it do so entirely on its own. For one thing, AI cannot always explain why software was designed a certain way, nor can it determine the original requirements that justified those design choices. Therefore, documentation should distinguish between observed facts, inferences, and decisions that still require confirmation. This highlights the importance of human oversight of AI throughout the entire migration process.</p><h4>A Secure Path for the Migration Process</h4><p>The migration process requires a series of strategic steps. Below, I outline the recommended phases for a typical migration process.</p><pre>Phase 0 - Original Software<br>* The existing system lacks AI and consists of source code, a database, an API, tests, and configuration.<br><br>Phase 1 — Discovery and Reverse Engineering<br>* Static analysis, dependencies, endpoints, entities, queries, commands, and business rules.<br><br>Phase 2 — SDD Documentation<br>* Key Markdown (.md) files for the AI: constitution, specs, plan, tasks, and agents.<br><br>Phase 3 — Validation against Actual Code<br>* Cross-referencing documentation, observed behavior, tests, and decisions confirmed by the person responsible for the system.<br><br>Phase 4 — Future Development via SDD + AI<br>* New functionality → specification → plan → tasks → implementation → testing → documentation update.</pre><p>Keep in mind that the complexity of the software being developed may cause this sequence of phases to vary. Each scenario requires a more thorough analysis. I have provided a generic example here to help you understand some key steps that should be considered during a migration process.</p><h4>Structure via AI</h4><p>An important recommendation before getting started is to use the GitHub Spec Kit to create the essential files for the development and migration context. This tool can assist with the documentation process; the full, formal workflow covers setup, specification, planning, task management, and implementation. Furthermore, it also supports integration into existing projects.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TdrEa_YUXz6SOSu8oNiv5Q.png" /><figcaption>Figure 1 — Recommended Structure for Integration with SDD + AI.</figcaption></figure><p>In Figure 1, I outline the recommended structure for integrating SDD + AI into your migration project. Each of the files is created using the Markdown (<em>.md</em>) format.</p><p>Personally, I would not adopt an approach that requires a separate SDD (<em>Software Design Document</em>) folder for every class or technical entity. Instead, I would create a specification based on functionality or business capability. Within that, I would document the relevant entities, commands, queries, handlers, validations, and endpoints. The underlying idea — wherever possible — is to avoid duplicating documentation, thereby ensuring consistent traceability. For instance, a customer management module might be organized as follows.</p><pre>* AddClienteCommand and your Handler.<br>* UpdateClienteCommand and your Handler.<br>* GetByIdClienteQuery and your Handler.<br>* Customer, your innvariants and relationships.<br>* REST endpoints and the contracts.<br>* Unit Tests and integration.<br>* The corresponding tables and migrations.</pre><h4>Key Content of Each File</h4><p>It is essential to have a clear understanding of the specific responsibilities associated with the key files used in the project’s construction process. I have outlined each of them below as a reminder:</p><pre>* constitution.md - Rules that all features must adhere to.<br>* spec.md - Existing functional behavior, requirements, scenarios, and acceptance criteria.<br>* plan.md - Architecture, affected components, contracts, persistence, and implementation strategy.<br>* tasks.md - Specific work, execution order, dependencies, and verification criteria.<br>* agents.md - Milestones, reviews, open questions, pending decisions, and next steps.</pre><p>Monitoring processes requires our supervision. Therefore, it is necessary to establish a convention for each step taken. For example, each requirement should have an associated evidence status. These requirements can be described using at least three key statuses, which are as follows:</p><pre>* Confirmed – Supported by code, tests, or verifiable documentation.<br>* Inferred – Deduced from behavior but not yet validated.<br>* Pending – Requires confirmation from the person responsible for the system.</pre><p>These states can help you maintain the manifest based on a process known in AI as the “source of truth.” While this phrase might sound a bit unusual, it is actually quite straightforward. It is a direct way of signaling to the AI ​​that the decisions made at each step must be strictly aligned with — and evaluated against — the context you have defined for each process, and that you are the one who ultimately decides what actions to take at every stage.</p><ol><li><strong>How to Get Started with the AI</strong>-Driven Reverse Engineering Process?<br>To begin, we will break the migration process down into at least six fundamental parts — or a series of sequential steps. <strong>Note</strong>: In this example, we will use an API model as our baseline.</li><li><strong>System Inventory</strong> — Identify the solution and its constituent projects, frameworks, NuGet packages, controllers, services, repositories, entities, DbContext, migrations, existing configurations, and tests.</li><li><strong>API Reconstruction</strong> — Analyze controllers, routes, HTTP verbs, parameters, DTOs, validations, response codes, authentication, and authorization. Cross-reference these with Swagger/OpenAPI documentation, if available.</li><li><strong>Domain Reconstruction</strong> — Identify entities, relationships, invariants, business rules, states, calculations, transactions, and dependencies. Distinguish between core business rules and mere implementation conventions.</li><li><strong>CQRS (<em>Command Query Responsibility Segregation</em>) Reconstruction </strong>— Assuming the use of the CQRS pattern, identify operations that modify state (“<em>Commands</em>”) and read-only operations (“<em>Queries</em>”), including their respective handlers, validations, side effects, and data access mechanisms. If the system does not use CQRS, document its current behavior as-is, without assuming the presence of a pattern that isn’t actually there.</li><li><strong>Generation of SDD (<em>Software Design Description</em>) Artifacts</strong> — Group the findings by functionality and generate four files for each feature, alongside the project charter, architectural documentation, and a traceability matrix.</li><li><strong>Validation and Approval</strong> — Execute existing tests, compare contracts and behaviors, identify contradictions, and obtain human approval for inferred decisions before establishing the specifications as the definitive source of truth.</li></ol><h4>Architecture Suitable for the Model</h4><p>Before beginning the architectural organization of the project, it is best to start with a read-only phase. In other words, it is not advisable to refactor the existing context directly into a specific architecture — such as Clean Architecture or the implementation of the CQRS pattern — as part of the AI-driven reverse engineering process. Instead, such architectural changes should come later, accompanied by the inclusion of specific requirements within dedicated `spec.md`, `plan.md`, and `tasks.md` files.</p><p>This read-only phase helps in gaining a better understanding of each project element and determining how to translate it into an AI-based model. It requires meticulous review and a thorough grasp of every phase that contributes to the software’s overall functionality.</p><p>Once this initial process has been established and developed, the next step is to begin with the `constitution.md` file. This file should articulate verifiable rules, rather than merely stating that the project will follow “<em>best practices</em>.”</p><pre># Project Charter<br><br>## 1. Purpose<br><br>Maintain and evolve the backend in a secure, traceable, and sustainable manner through AI-assisted Spec-Driven Development.<br><br>## 2. Architectural Principles<br><br>- Apply Clean Architecture and the Dependency Inversion principle.<br>- The domain layer must not depend on ASP.NET Core, Entity Framework Core, or other infrastructure details.<br>- The Application layer shall coordinate use cases and define the necessary contracts.<br>- The Infrastructure layer shall implement persistence adapters and external integrations.<br>- The API layer shall expose HTTP contracts and delegate execution to the use cases.<br>- Avoid circular dependencies and adhere to the dependency direction defined in the approved design.<br><br>## 3. CQRS<br><br>- Represent write operations as Commands and read operations as Queries, where appropriate for the given use case.<br>- Keep input models, domain entities, and response models separate when their responsibilities differ.<br>- Do not introduce CQRS complexity, mediators, or event sourcing without documented justification.<br><br>## 4. Quality and Testing<br><br>- All new functionality must have verifiable acceptance criteria.<br>- Cover business rules with unit tests.<br>- Use integration tests to validate persistence, transactions, and relevant contracts.<br>- Do not consider a task complete without executing and recording the applicable verifications.<br>- Do not claim that a test has been executed unless there is evidence of its execution.<br><br>## 5. Security<br><br>- Validate input data at the appropriate boundaries.<br>- Apply explicit authorization to protected operations.<br>- Do not store secrets in the repository.<br>- Log errors without exposing credentials, tokens, or sensitive data.<br><br>## 6. Reverse Engineering<br><br>- Do not modify system behavior during the discovery phase.<br>- Distinguish between observed facts, inferences, and pending requirements. - Link relevant findings to evidence from the code, tests, contracts, or database schema.<br>- Do not invent functional requirements that are not supported by evidence.<br><br>## 7. Specification Governance<br><br>- Each piece of functionality must include `spec.md`, `plan.md`, `tasks.md`, and `agenda.md`.<br>- Functional changes must be reflected in the corresponding SDD (Software Design Description) artifacts.<br>- Significant architectural decisions must be documented via ADRs (Architecture Decision Records).<br>- The implementation must satisfy the approved specification and its acceptance criteria.<br>- The CI (Continuous Integration) process will automatically verify architectural rules that can be reliably checked.</pre><p>This example serves as a foundational or starting-point framework. It is highly likely that you will need to make adjustments as your project progresses. This framework is not strictly rigid; in fact, it is more flexible than one might assume. However, it is important to note that this flexibility should not be applied arbitrarily. On the Microsoft website, you can find a well-documented guide on architectures and the recommended approach for various scenarios. See <a href="https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures?utm_source=chatgpt.com">here</a>.</p><h4>Working with the GitHub Spec Kit</h4><p>The GitHub Spec Kit provides a highly flexible workflow that saves time. Furthermore, it allows you to directly specify the characteristics of your reverse engineering process via the `agents.md` file. This tool enables the adoption of an SDD (<em>Software Design Description</em>) process within an existing repository, while allowing for the customization of workflows and templates. You can learn more about the Spec Kit here. <strong>Note</strong>: This process is necessary if you do not yet have a repository for your project.</p><p>Conversely, if your project already has a repository, it is advisable to create a separate branch to house the new project and all future changes.</p><p>The subsequent planning phase should outline the step-by-step organization of specific SDD commands — executed via a compatible programming agent — followed by the implementation of a dedicated reverse analysis workflow. The planning could be structured as follows.</p><pre>/reverse-engineer-inventory<br>/reverse-engineer-api<br>/reverse-engineer-domain<br>/reverse-engineer-cqrs<br>/reverse-engineer-specs<br>/reverse-engineer-validate</pre><h4>Conclusion</h4><p>In this article, we have explored several key points regarding the migration process from legacy software to a model that utilizes SDD (<em>Software Design Description</em>) and AI. It is important to note that every scenario may involve different variables and variations during the analysis and implementation phases. Nevertheless, this article provides a standard framework that can serve as a useful basic reference model. Please keep in mind that more complex projects will naturally entail greater complexity in the analysis and implementation process.</p><p>As a final recommendation, it is best to start with a representative module, automate the analysis, and validate its four corresponding files against the system’s actual behavior. Once this procedure is working correctly, you can extend it to the rest of the backend. This will provide a reliable SDD foundation for enhancing the system with AI, all while maintaining full traceability and avoiding any unintended functional changes.</p><p>See you soon!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=72dbf0c2b97f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Ingeniería Inversa para una Migración desde un Proyecto Legacy hacia un Modelo SDD (Spec-Driven…]]></title>
            <link>https://medium.com/@arielwagnermovil/ingenier%C3%ADa-inversa-para-una-migraci%C3%B3n-desde-un-proyecto-legacy-hacia-un-modelo-sdd-spec-driven-42fce1036ab1?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/42fce1036ab1</guid>
            <category><![CDATA[reverse-engineer]]></category>
            <category><![CDATA[sdd]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Thu, 22 Oct 2026 03:13:47 GMT</pubDate>
            <atom:updated>2026-10-22T03:13:47.385Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0-s8NLe9eq8_zvMnFrJj_w.jpeg" /></figure><h3>Ingeniería Inversa para una Migración desde un Proyecto Legacy hacia un Modelo SDD (Spec-Driven Development) Utilizando IA</h3><h4>Introducción</h4><p>Existe un antes y un después con respecto al desarrollo de software moderno. Actualmente, el desarrollo de software hace uso de todas las ventajas que puede proporcionar la IA (<em>Inteligencia Artificial</em>). El desarrollo moderno basado en IA va más allá del desarrollo mediante el Vibe Coding. En su lugar, el desarrollo profesional hace uso de al menos un patrón arquitectónico eficiente como lo es SDD (<em>Spec-Driven Development</em>) o en español (<em>Desarrollo Dirigido por Especificaciones</em>), y como sugieren sus siglas, el desarrollo del software se crea desde un conjunto particular de especificaciones.</p><p>En el pasado, el desarrollo del software, al que llamaré como <em>Legacy Development</em>, o en español como (<em>Desarrollo Heredado</em>), este enfoque recurría a un proceso totalmente manual, se podría decir altamente artesanal, donde la intervención humana era total. El problema que suscita de cara al futuro es; ¿cómo migrar y luego, mantener o escalar un software que ha sido desarrollado de forma <em>Legacy Development</em> hacia un proceso moderno basado en IA? Esta gran pregunta resulta importante y desafiante a la vez, y por la que todo ingeniero o arquitecto de software deberá enfrentarse.</p><p>En este artículo vamos analizar y esbozar algunas ideas que podrían ser muy útiles a la hora de llevar a cabo un proceso de migración desde un desarrollo de software heredado hacia uno basado en IA.</p><h4>Análisis Estratégico Inicial</h4><p>Quizá muchos de nosotros nos sintamos tentados en dejar que la IA haga sola todo el proceso de migración, documentación, implementación, etc., y como ya suponemos, hacer esto no es aconsejable. Existen varios factores que podrían condicionar el proceso. En esencia, la clave aquí es no pedirle a la IA que genere todos los archivos <a href="http://spec.md/">spec.md</a>, <a href="http://plan.md/">plan.md</a> y <a href="http://tasks.md/">tasks.md</a> de forma aislada a partir del código fuente. Lo recomendable es diseñar un proceso de ingeniería inversa que permita reconstruir la especificación funcional, las decisiones arquitectónicas, las reglas de negocio, las tareas de evolución del sistema, manteniendo trazabilidad entre el código existente y la documentación generada.</p><p>Si bien, la propia IA a través de la ingeniería inversa puede descubrir lo que hace el software, no es aconsejable dejar que la IA lo haga por si sola. Por empezar, esta no siempre puede demostrar por qué el software fue diseñado así, tampoco puede determinar qué requisitos originales utilizados lo han justificado. Por eso, la documentación debería distinguir entre hechos observados, inferencias y decisiones pendientes de confirmación. He aquí la importancia de la supervisión de la IA desde la óptica humana durante todo el proceso de migración.</p><h4>Camino Seguro para el Proceso Migratorio</h4><p>El proceso de migración requiere de un conjunto de pasos estratégicos. A continuación, comparto las siguientes fases más recomendadas para el proceso general migratorio.</p><pre>Fase 0 - Software original <br>* El Sistema existente carece de IA y se compone de Código Fuente, base de datos, API, pruebas y configuración.<br><br>Fase 1 — Descubrimiento e ingeniería inversa<br>* Análisis estático, dependencias, endpoints, entidades, consultas, comandos y reglas de negocio.<br><br>Fase 2 — Documentación SDD<br>* Archivos md claves de la IA. Estos son constitution, specs, plan, tasks y agents.<br><br>Fase 3 — Validación con el código real<br>* Contrastar documentación, comportamiento observado, pruebas y decisiones confirmadas por el responsable del sistema.<br><br>Fase 4 — Desarrollo futuro mediante SDD + IA<br>* Nueva funcionalidad → especificación → plan → tareas → implementación → pruebas → actualización documental.</pre><p>Ten en cuenta que la complejidad del software desarrollado podría variar esta secuencia de fases. Cada caso asume un análisis más exahustivo. En este caso he dado un ejemplo genérico para comprender algunos pasos importantes que debiéramos considerar para un proceso migratorio.</p><h4>Estructura desde la IA</h4><p>Una recomendación importante antes de empezar es el uso de GitHub Spec Kit para la construcción de los archivos más importantes del contexto del desarrollo y migración. Esta herramienta te puede ayudar con el proceso de documentación, más todo ese flujo oficial contempla la constitución, la especificación, la planificación, las tareas y la implementación. Además, también contempla la adopción en proyectos existentes.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/693/0*pjuVsjTyVijIuRKC" /><figcaption>Figura 1 — Estructura Recomendada para la Integración con SDD + IA.</figcaption></figure><p>En la figura 1 describo la estructura recomendada para la integración SDD + IA en tu proyecto de migración. Cada uno de los archivos están construidos bajo el formato <a href="https://www.markdownguide.org/">Markdown</a> (<em>.md</em>).</p><p>Personalmente, no adoptaría una inclusión necesaria partiendo de una carpeta SDD por cada clase o entidad técnica. En su lugar, crearía una especificación por funcionalidad o capacidad de negocio. Luego, documentaría dentro de ella las entidades, comandos, consultas, handlers, validaciones y endpoints involucrados. La idea de fondo es evitar, por supuesto si es en lo posible, la duplicación en la documentación a los efectos de mantener una trazabilidad coherente. Por ejemplo, una gestión para los clientes podría tener el siguiente aspecto organizativo.</p><pre>* AddClienteCommand y su handler.<br>* UpdateClienteCommand y su handler.<br>* GetByIdClienteQuery y su handler.<br>* Cliente, sus invariantes y sus relaciones.<br>* Los endpoints REST y sus contratos.<br>* Las pruebas unitarias y de integración.<br>* Las tablas y migraciones correspondientes.</pre><h4>Contenido Clave de Cada Archivo</h4><p>Resulta primordial comprender bien cada una de las responsabilidades que poseen los archivos clave para el proceso constructivo del proyecto. Detallo en modo de recordatorio cada uno de ellos a continuación:</p><pre>* constitution.md - Reglas que todas las funcionalidades deben respetar.<br>* spec.md - Comportamiento funcional existente, requisitos, escenarios y criterios de aceptación.<br>* plan.md - Arquitectura, componentes afectados, contratos, persistencia y estrategia de implementación.<br>* tasks.md - Trabajo concreto, orden de ejecución, dependencias y criterios de verificación.<br>* agents.md - Hitos, revisiones, preguntas abiertas, decisiones pendientes y próximo paso.</pre><p>El seguimiento de los procesos requiere de nuestra supervisión. Por ende, es necesario establecer una convención para cada paso dado. Por ejemplo, cada requisito debería llevar un estado de evidencia. Estos requisitos podrían describirse bajo al menos tres estados claves y estos son los siguientes.</p><pre>* Confirmado - Respaldado por código, pruebas o documentación verificable.<br>* Inferido - Deducido del comportamiento pero todavía no validado.<br>* Pendiente - Requiere confirmación del responsable del sistema. </pre><p>Estos estados te pueden ayudar a mantener el manifiesto basado en el proceso conocido en IA como “<em>la fuente de la verdad</em>”. Esta frase podría sonar algo extraña pero en verdad no lo es. Es una forma directa de indicarle a la IA que las decisiones que se deben tomar en cada paso son estrictamente consensuadas y evaluadas por el contexto que le hayas especificado a cada proceso y que eres tú el que decides qué hacer en cada paso y proceso.</p><h4>¿Cómo Empezar con el Proceso de Ingeniería Inversa con IA?</h4><p>Para comenzar, iremos a dividir al menos en seis partes fundamentales, o bien, un conjunto de pasos para el proceso migratorio. Nota: En este caso vamos a tratar con un modelo API como ejemplo base.</p><ol><li><strong>Inventario del Sistema</strong> — Identificar solución y proyectos, frameworks, paquetes NuGet, controladores, servicios, repositorios, entidades, DbContext, migraciones, configuración y pruebas existentes.</li><li><strong>Reconstrucción de la API</strong> — Analizar controladores, rutas, verbos HTTP, parámetros, DTO, validaciones, códigos de respuesta, autenticación y autorización. Contrastar con Swagger/OpenAPI cuando exista.</li><li><strong>Reconstrucción del Dominio</strong> — Detectar entidades, relaciones, invariantes, reglas de negocio, estados, cálculos, transacciones y dependencias. Separar las reglas reales de las meras convenciones de implementación.</li><li><strong>Reconstrucción de CQRS (<em>Command Query Responsibility Segregation</em>)</strong> — Considerando que hacemos uso del patrón CQRS, pasamos a identificar las operaciones que modifican estado (<em>Commands</em>) y operaciones de lectura (<em>Queries</em>), incluidos sus handlers, validaciones, efectos secundarios y acceso a datos. Si el sistema no utiliza CQRS, documentar el comportamiento actual sin fingir que ya existe.</li><li><strong>Generación de Artefactos SDD</strong> — Agrupar los hallazgos en funcionalidades y generar los cuatro archivos por funcionalidad, junto con la constitución, la documentación arquitectónica y la matriz de trazabilidad.</li><li><strong>Validación y Aprobación</strong> — Ejecutar las pruebas existentes, comparar contratos y comportamientos, identificar contradicciones y obtener aprobación humana para las decisiones inferidas antes de considerar las especificaciones como fuente de verdad.</li></ol><h4>Arquitectura Adecuada para el Modelo</h4><p>Antes de comenzar con el proceso de organización arquitectónica del proyecto, es empezarlo desde un proceso de solo lectura. Es decir, no es conveniente refactorizar el contexto directamente para una arquitectura determinada, como por ejemplo podría ser Clean Architecture e incluso, la inclusión del patrón CQRS como proceso migratorio desde la ingeniería inversa de la IA. En su lugar, este proceso debiera ser posterior más la inclusión de sus propios specs en cada archivo <a href="http://spec.md/">spec.md</a>, <a href="http://plan.md/">plan.md</a> y <a href="http://tasks.md/">tasks.md</a>.</p><p>El proceso de solo lectura nos ayuda a comprender mejor cada elemento del proyecto y luego, cómo traducirlo al modelo basado en IA. Es un trabajo que requiere una revisión minuciosa y un perfecto endendimiento de cada una de las fases que forman parte de la funcionalidad del software en general.</p><p>Asumiendo entonces que este proceso inicial lo hemos ido creando y desarrollando, resulta necesario empezar desde el archivo <a href="http://constitution.md/">constitution.md</a>. Este debería expresar reglas verificables, no simplemente decir que el proyecto utilizará buenas prácticas.</p><pre># Constitución del proyecto<br><br>## 1. Propósito<br><br>Mantener y evolucionar el backend de forma segura, trazable y sostenible mediante Spec-Driven Development asistido por IA.<br><br>## 2. Principios de arquitectura<br><br>- Aplicar Clean Architecture y el principio de inversión de dependencias.<br>- El dominio no dependerá de ASP.NET Core, Entity Framework Core ni otros detalles de infraestructura.<br>- La capa Application coordinará los casos de uso y definirá los contratos necesarios.<br>- La capa Infrastructure implementará los adaptadores de persistencia e integraciones externas.<br>- La capa API expondrá los contratos HTTP y delegará la ejecución en los casos de uso.<br>- Evitar dependencias circulares y respetar la dirección de dependencias definida en el diseño aprobado.<br><br>## 3. CQRS<br><br>- Representar las operaciones de escritura mediante Commands y las de lectura mediante Queries cuando corresponda al caso de uso.<br>- Mantener separados los modelos de entrada, las entidades de dominio y los modelos de respuesta cuando sus responsabilidades difieran.<br>- No introducir complejidad de CQRS, mediadores o event sourcing sin una justificación documentada.<br><br>## 4. Calidad y pruebas<br><br>- Toda funcionalidad nueva tendrá criterios de aceptación verificables.<br>- Cubrir las reglas de negocio con pruebas unitarias.<br>- Utilizar pruebas de integración para validar persistencia, transacciones y contratos relevantes.<br>- No considerar una tarea terminada sin ejecutar y registrar las verificaciones aplicables.<br>- No afirmar que una prueba fue ejecutada si no existe evidencia de su ejecución.<br><br>## 5. Seguridad<br><br>- Validar los datos de entrada en los límites correspondientes.<br>- Aplicar autorización explícita a las operaciones protegidas.<br>- No almacenar secretos en el repositorio.<br>- Registrar errores sin exponer credenciales, tokens ni datos sensibles.<br><br>## 6. Ingeniería inversa<br><br>- No modificar el comportamiento del sistema durante la fase de descubrimiento.<br>- Diferenciar hechos observados, inferencias y requisitos pendientes.<br>- Asociar los hallazgos relevantes con evidencias del código, pruebas, contratos o esquema de base de datos.<br>- No inventar requisitos funcionales ausentes de la evidencia.<br><br>## 7. Gobierno de especificaciones<br><br>- Cada funcionalidad tendrá spec.md, plan.md, tasks.md y agenda.md.<br>- Los cambios funcionales deberán actualizar sus artefactos SDD.<br>- Las decisiones arquitectónicas relevantes se registrarán mediante ADR.<br>- La implementación deberá satisfacer la especificación aprobada y sus criterios de aceptación.<br>- La CI verificará automáticamente las reglas arquitectónicas que puedan comprobarse de forma fiable.</pre><p>Este ejemplo es un modelo de constitución base o de arranque. Es muy probable que a medida que vayas avanzando en tu proyecto debas realizar algunas modificaciones. La constitución no se sujeta a un modelo totalmente rígido. Por el contrario, resulta más flexible de lo que se puede pensar. Sin embargo, es necesario que sepas que esa flexibilidad no debe aplicarse de forma deliberada. En la página Web de Microsoft podremos incluso encontrar una guía muy bien documentada sobre las arquitecturas y de cómo debieramos proceder para cada caso. Ver <a href="https://learn.microsoft.com/es-es/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures?utm_source=chatgpt.com">aquí</a>.</p><h4>Trabajando con GitHub Spec Kit</h4><p>La herramienta GitHub Spec Kit nos proporciona un flujo de trabajo muy flexible que nos ahorra tiempo, y por otro lado, sumado a este proceso, podríamos pasar directamente a especificarle las características de nuestra ingeniería inversa desde el archivo <a href="http://agents.md/">agents.md</a>. Esta herramienta nos permite adoptar un proceso SDD en un repositorio existente y personalizar sus flujos y plantillas. Puedes obtener información de Spec Kit <a href="https://github.com/github/spec-kit?utm_source=chatgpt.com">aquí</a>. Nota: Este proceso es necesario en caso de que no contemos con un repositorio para el proyecto.</p><p>Por el contrario, si ya contamos con un repositorio en nuestro proyecto, es recomendable crear una rama aparte para alojar allí nuestro nuevo proyecto y todos los cambios que se darán a futuro.</p><p>La planificación posterior a esto debería dar el paso a paso para organizar a los comandos concretos de SDD que se ejecutan desde el agente de programación compatible y luego implementaría un flujo específico de análisis inverso. La panificación podría ser la siguiente.</p><pre>/reverse-engineer-inventory<br>/reverse-engineer-api<br>/reverse-engineer-domain<br>/reverse-engineer-cqrs<br>/reverse-engineer-specs<br>/reverse-engineer-validate</pre><h4>Conclusión</h4><p>En este artículo hemos visto una serie de puntos claves que conciernen a un proceso de migración desde un software desarrollado <em>Legacy</em> hacia un modelo que hace uso de SDD + IA. Resulta importante señalar que cada caso puede incluir diversos tipos de variables y variantes en el análisis e implementación en cada caso. No obstante, este artículo encierra al menos una traza estándar que puede resultar muy útil como modelo de referencia básica. Por lo tanto, ten en cuenta que proyectos más complejos implicarían también una mayor complejidad al proceso de análisis e implementación.</p><p>Como una recomendación final, resulta necesario empezar por un módulo representativo, automatizar el análisis y validar sus cuatro archivos contra el comportamiento real. Cuando ese procedimiento funcione, proceder a extenderlo al resto del backend. Así tendrás una base SDD fiable para ampliar el sistema con IA, sin que con todo ello pierdas la trazabilidad y ni que tengas que introducir cambios funcionales involuntarios.</p><p>¡Hasta pronto!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=42fce1036ab1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SDD (Spec-Driven Development) — Evolution of the Specification]]></title>
            <link>https://medium.com/@arielwagnermovil/sdd-spec-driven-development-evolution-of-the-specification-55ca0609ad64?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/55ca0609ad64</guid>
            <category><![CDATA[spec-fir]]></category>
            <category><![CDATA[spec-as-source]]></category>
            <category><![CDATA[sdd]]></category>
            <category><![CDATA[spec-anchroe]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Tue, 06 Oct 2026 12:50:01 GMT</pubDate>
            <atom:updated>2026-10-06T12:50:01.368Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jIt7Ig8mI1ArRKWKBVnp3g.jpeg" /></figure><h4>Introudction</h4><p>Not all SDD approaches are the same. Each team adopts varying levels of rigor depending on specific needs, tools, and domain constraints. Therefore, it is necessary to understand the three types of specifications that can be used for the development and construction of our software.</p><h4>What is the source of truth?</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*orJBMClBBfwRlsfseDbMng.png" /><figcaption>Figure 1 — Evolution Specification.</figcaption></figure><p>Figure 1 illustrates the evolution from a code-first approach to a full spec-as-source approach. In Figure 1, we can see where each team falls along this evolutionary path and where the first step toward effectively adopting SDD should be taken.</p><h4>Spec-First Definition</h4><p>In spec-first development, a specification is written prior to coding to guide the initial implementation. Once the code exists, the specification may or may not be maintained; its primary value lies in the initial clarity it provides.</p><p>The spec-first approach serves as the starting point for development. Before writing code, the developer or team defines what the code must do; this is typically achieved through a user story with acceptance criteria, a BDD scenario, or a detailed requirements document. The specification guides implementation, but once the code is written and tests are passed, the specification can be discarded or allowed to become outdated.</p><p>The defining characteristic of spec-first development is that the specification is written before implementation begins, ensuring developers have a clear objective before they start programming. However, post-implementation, the code becomes the primary artifact, and the specification may become obsolete as the code evolves through subsequent iterations. This approach entails a lower maintenance burden than more rigorous specification disciplines, making it practical for teams unable to commit to the ongoing maintenance of specifications.</p><p>The spec-first approach is particularly effective for initial feature development when working with AI-powered coding assistants. Having a prior specification prevents the AI ​​from having to guess requirements, drastically improving the quality of the generated code. It is also a valuable method for prototypes and one-off features — scenarios where the cost of maintaining an up-to-date specification alongside the code indefinitely is not justified. However, this approach does not guard against divergence over time. If the code is intended for long-term maintenance, teams should consider “<em>spec-anchored</em>” approaches, where the specification serves as the central reference point.</p><h4>Spec-Anchored Definition</h4><p>In spec-anchored development, the specification is maintained alongside the code throughout the system’s entire lifecycle. Changes in behavior require updating both the specification and the code, keeping them synchronized.</p><p>Spec-anchored development treats the specification as a living document that evolves alongside the source code. When functionality changes, the specification is updated either before or simultaneously with the code. Automated checks — typically via tests derived from the specification — ensure that the specification and the code remain aligned. If a divergence occurs, the tests fail, providing immediate feedback that the system documentation no longer reflects its actual behavior.</p><p>In this approach, the specification and the code evolve together on equal footing. Tests ensure consistency between the two; typically, BDD (<em>Behavior-Driven Development</em>) scenarios serve as automated tests that run with every commit. The specification acts as up-to-date documentation that both developers and stakeholders can rely on. However, maintaining this consistency requires discipline and tool support. Teams must commit to updating specifications whenever behavior changes.</p><p>The spec-anchored approach represents the sweet spot for most production systems. It offers the benefits of clear documentation and verifiable requirements without requiring the code to be generated entirely from the specifications. BDD frameworks like Cucumber exemplify this approach by allowing teams to write human-readable scenarios that execute as automated tests. In API development, OpenAPI specifications combined with contract testing tools — such as Specmatic — achieve that same consistency between specification and implementation.</p><h4>Spec-as-Source Definition</h4><p>In spec-as-source development, the specification is the only artifact that humans edit directly. The code is generated entirely from the specification and must never be modified manually. Any change in behavior entails modifying the specification and regenerating the code.</p><p>The spec-as-source approach represents the most radical form of SDD. In practice, the specification becomes the source code, albeit expressed at a higher level of abstraction. Developers think in terms of requirements and behavior; machines translate this into executable code. If functionality needs to be modified, the specification is changed and the code is regenerated; the generated code is never edited directly.</p><p>This approach, based on Design by Contract principles, fundamentally reverses the traditional relationship between specifications and code. The specification is the primary artifact, and the code is derived entirely from it. Manual code editing is either prohibited or restricted to clearly defined extension points. This requires mature, reliable generation tools; developers must be confident that the generated code correctly implements the specification.</p><p>In return, divergence by design is eliminated. This means that, since code is regenerated rather than manually edited, the specification and the code remain aligned by construction.</p><p>Spec-as-source is already standard practice in domains with well-defined code generation — such as generating API servers, creating stubs from OpenAPI specifications, or producing certified embedded code from Simulink models. In the automotive industry, engineers routinely create control algorithms in Simulink to verify behavior at the model level via simulation and to generate certified C code that is never manually edited. Tools like Tessl are now emerging from the AI ​​sector itself, aiming to extend this approach to general software development and pointing toward a future where specifications truly become “<em>the new source code</em>.” However, there is a critical point we must highlight. Adopting “<em>spec-as-source</em>” requires a high degree of confidence in the quality of the generation process, and currently, it is only practical in areas where such confidence has already been firmly established.</p><p>See you soon!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=55ca0609ad64" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SDD (Spec-Driven Development) — Evolución de la Especificación]]></title>
            <link>https://medium.com/@arielwagnermovil/sdd-spec-driven-development-evoluci%C3%B3n-de-la-especificaci%C3%B3n-a41c6016d1c1?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/a41c6016d1c1</guid>
            <category><![CDATA[spec-first]]></category>
            <category><![CDATA[spec-as-source]]></category>
            <category><![CDATA[spec-anchored]]></category>
            <category><![CDATA[sdd]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Mon, 05 Oct 2026 20:45:24 GMT</pubDate>
            <atom:updated>2026-10-05T20:45:24.898Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jIt7Ig8mI1ArRKWKBVnp3g.jpeg" /></figure><h4>Introducción</h4><p>No todos los enfoques SDD son iguales. Cada equipo adopta diferentes niveles de rigor dependiendo de cada necesidad, herramientas y restricciones de dominio. Por tanto, resulta necesario comprender las tres clases de especificaciones que podemos utilizar para el desarrollo y construcción de nuestro software.</p><h3>¿Cuál es la Fuente de la Verdad?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/836/1*4Un4EGQFOKo931IJbneHyg.png" /><figcaption>Figura 1 — Evolución de la Especificación.</figcaption></figure><p>En la figura 1 se puede apreciar una evolución que va desde el enfoque <em>code-first</em> hacia el enfoque total de <em>spec-as-source</em>. En la figura 1 podemos observar donde cae cada equipo sobre esta evolución y donde debería ubicarse el primer paso adoptando efectivamente SDD.</p><h4>Definición de Spec-First</h4><p>En el desarrollo basado en especificaciones <em>spec-first</em>, se redacta una especificación antes de la codificación para guiar la implementación inicial. Una vez que existe el código, la especificación puede mantenerse o no; su valor principal reside en la claridad inicial que aporta.</p><p>El enfoque <em>spec-first</em> (<em>primero especificar</em>) constituye el punto de partida del SDD. Antes de escribir código, el desarrollador o el equipo definen qué debe hacer dicho código; esto suele hacerse mediante una historia de usuario con criterios de aceptación, un escenario BDD o un documento detallado de requisitos. La especificación guía la implementación, pero una vez escrito el código y superadas las pruebas, es posible descartarla o permitir que quede desactualizada.</p><p>La característica distintiva del desarrollo <em>spec-first</em>, es que la especificación se redacta antes de iniciar la implementación, lo que garantiza que los desarrolladores cuenten con un objetivo claro antes de comenzar a programar. No obstante, tras la implementación, el código se convierte en el elemento principal y la especificación puede quedar obsoleta, a medida que el código evoluciona en iteraciones posteriores. Este enfoque conlleva una menor carga de mantenimiento que otras disciplinas de especificación más rigurosas, lo que lo hace práctico para equipos que no pueden comprometerse a un mantenimiento continuo de las especificaciones.</p><p>El enfoque <em>spec-first</em> resulta especialmente eficaz para el desarrollo inicial de funcionalidades al trabajar con asistentes de programación basados en IA. La especificación previa evita que la IA tenga que adivinar los requisitos, lo que mejora drásticamente la calidad del código generado. También es un método valioso para prototipos y funcionalidades puntuales, casos en los que no se justifica el coste de mantener una especificación actualizada junto con el código de forma indefinida. Sin embargo, este enfoque no protege contra la divergencia a lo largo del tiempo. Si el código se va a mantener a largo plazo, los equipos deberían considerar enfoques basados en especificaciones como referencia central <em>spec-anchored</em>.</p><h4>Definición de Spec-Anchored</h4><p>En el desarrollo <em>spec-anchored</em>, la especificación se mantiene junto con el código a lo largo de todo el ciclo de vida del sistema. Los cambios en el comportamiento requieren actualizar tanto la especificación como el código, manteniéndolos sincronizados.</p><p>El desarrollo basado en <em>spec-anchored</em> trata la especificación como un documento vivo que evoluciona junto con el código fuente. Cuando una funcionalidad cambia, la especificación se actualiza antes o simultáneamente al código. Las comprobaciones automatizadas, generalmente mediante pruebas derivadas de la especificación, garantizan que esta y el código permanezcan alineados. Si se produce una divergencia, las pruebas fallan, lo que proporciona un feedback inmediato que la documentación del sistema ya no refleja su comportamiento.</p><p>En este enfoque, la especificación y el código evolucionan conjuntamente, en igualdad de condiciones. Las pruebas garantizan la coherencia entre ambos; habitualmente, los escenarios de BDD (<em>Behavior-Driven Development</em>) actúan como pruebas automatizadas que se ejecutan con cada <em>commit</em>. La especificación sirve como documentación siempre actualizada en la que tanto desarrolladores como partes interesadas pueden confiar. No obstante, mantener esta coherencia exige disciplina y apoyo de herramientas. Los equipos deben comprometerse a actualizar las especificaciones siempre que cambie el comportamiento.</p><p>El enfoque basado en especificaciones <em>spec-anchored</em> representa el punto óptimo para la mayoría de los sistemas en producción. Ofrece las ventajas de una documentación clara y requisitos verificables, sin exigir que el código se genere íntegramente a partir de las especificaciones. Los frameworks de BDD, como Cucumber, ejemplifican este enfoque al permitir a los equipos redactar escenarios legibles para humanos que se ejecutan como pruebas automatizadas. En el desarrollo de API, las especificaciones OpenAPI combinadas con herramientas de pruebas de contrato, como Specmatic, logran esa misma coherencia entre la especificación y la implementación.</p><h4>Definición de Spec-as-Source</h4><p>En el desarrollo basado en <em>spec-as-source</em>, la especificación es el único artefacto que los humanos editan directamente. El código se genera en su totalidad a partir de la especificación y nunca debe modificarse manualmente. Cualquier cambio en el comportamiento implica modificar la especificación y volver a generar el código.</p><p>El enfoque <em>spec-as-source</em> representa la forma más radical de SDD. La especificación se convierte, en la práctica, en el código fuente, aunque expresado a un nivel de abstracción superior. Los desarrolladores piensan en términos de requisitos y comportamiento; las máquinas traducen esto a código ejecutable. Si se desea modificar la funcionalidad, se cambia la especificación y se regenera el código; nunca se edita directamente el código generado.</p><p>Este enfoque, basado en los principios del <em>Diseño por Contrato</em>, invierte fundamentalmente la relación tradicional entre especificaciones y código. La especificación es el artefacto principal y el código se deriva íntegramente de ella. La edición manual del código está prohibida o limitada a puntos de extensión claramente definidos. Esto exige herramientas de generación maduras y fiables; los desarrolladores deben tener la certeza de que el código generado implementa correctamente la especificación.</p><p>A cambio, se elimina la divergencia por diseño. Ello quiere decir que dado que el código se regenera en lugar de editarse manualmente, la especificación y el código permanecen siempre alineados por construcción.</p><p><em>Spec-as-source</em> ya es una práctica estándar en dominios con generación de código bien definido, como generar un servidor API, resguardos de especificaciones OpenAPI o producir código integrado certificado a partir de modelos de Simulink. En la industria automotriz, los ingenieros crean rutinariamente algoritmos de control en Simulink, a los efectos de poder verificar el comportamiento a nivel del modelo mediante simulación, y generar código C certificado que nadie editará manualmente. Desde la propia IA surgen las herramientas como Tessl que tienen como objetivo extender este enfoque al software general de desarrollo, representando un futuro donde las especificaciones realmente se convierten en “<em>el nuevo código fuente</em>”.</p><p>Sin embargo, existe un punto crítico que no podemos dejar de señalar. Adoptar <em>spec-as-source</em> requiere un alto grado de confianza en la calidad de la generación y, actualmente, solo resulta práctico en ámbitos donde dicha confianza ya se ha consolidado muy eficientemente.</p><p>¡Hasta pronto!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a41c6016d1c1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SPDD — New Paradigm in Design and Software Develop with AI]]></title>
            <link>https://medium.com/@arielwagnermovil/spdd-new-paradigm-in-design-and-software-develop-with-ai-32eabb676446?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/32eabb676446</guid>
            <category><![CDATA[sdd]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[spdd]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Wed, 30 Sep 2026 18:44:24 GMT</pubDate>
            <atom:updated>2026-09-30T18:44:24.415Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Rcud724bQJgAUrJr_AELNg.png" /></figure><h4>Introduction</h4><p>Following the emergence of AI (<em>Artificial Intelligence</em>) in both our professional and daily lives, the use of prompts — enabled by LLM (<em>Large Language Model</em>) technology — has become a fundamental pillar of general development. However, as we know, using simple prompts without a proper structure fails to deliver an optimal experience during the process.</p><p><a href="https://www.thoughtworks.com/engineering">Thoughtworks </a>— a resource featured on architect <a href="https://martinfowler.com/">Martin Fowler’s</a> website — has developed an interesting strategy that proposes a different paradigm for the software construction process using AI. The Thoughtworks team has created a workflow known as SPDD (<em>Structured Prompt-Driven Development</em>). This approach enables developers to place greater emphasis on crafting effective prompts through a structured process.</p><h4>Thoughtworks Team Proposal</h4><p>The team has identified three key characteristics among developers that drive effective development: alignment, prioritized abstraction, and iterative review.</p><p>One initial characteristic observed at the individual developer level is the problem-solving capability applied to writing, modifying, and refactoring code. This enables tasks to be executed more quickly than before. The team also highlights aspects related to delivery speed that go beyond the mere volume of code written. However, it is worth noting the friction that arises during the development process within the context of the development lifecycle.</p><p>The team highlights these points as areas requiring attention and further analysis.</p><ul><li><em>Ambiguous Requirements and Misunderstandings.</em></li><li><em>Frequent Reviews and the Indirect Introduction of Inconsistencies.</em></li><li><em>Integration and Testing Issues. Generation Is Not Alignment.</em></li><li><em>Increased Production Risk Linked to an Increase in Changes.</em></li></ul><p>The Thoughtworks team is very clear regarding velocity, noting that it does not improve throughput capacity. For this reason — as the Thoughtworks team rightly points out — the key question is: how do we ensure that AI-generated changes are controllable, reviewable, and reusable, enabling teams to work faster and more securely? This very question led the Thoughtworks team to develop SPDD.</p><h4>SPDD Principles</h4><p>The most important rule of SPDD is to establish a structured design process rather than relying on the ad-hoc use of prompts. This process emphasizes versioning, revisions, reuse, and, of course, all possible improvements. In other words, the entire approach is structured around a set of well-defined instructions.</p><p>The LLM generates code within a clearly defined scope or boundary, making it easier to validate and predict. The Thoughtworks team has structured this process around two possible control scenarios, as follows:</p><ul><li><strong><em>Reasons Canvas</em></strong> — Fosters clarity regarding requirements, the domain model, the solution approach, system structure, task decomposition, reusable standards, and security measures. Consequently, the LLM is guided by intent rather than guesswork.</li><li><strong><em>SPDD Workflow</em></strong> — Integrates prompting into the same discipline as coding, relying specifically on commit history, reviews, and quality checks. It also enforces a simple yet powerful rule: when reality diverges, correct the prompt first, then update the code.</li></ul><p>The Thoughtworks team describes both as prompt control models for achieving software design best practices using AI.</p><h4>Reasons Canvas</h4><p>The control process in this scenario employs a seven-phase approach, as follows:</p><ul><li><strong><em>Requirements</em></strong></li><li><strong><em>Entities<br>Approach</em></strong></li><li><strong><em>Structure</em></strong></li><li><strong><em>Operations</em></strong></li><li><strong><em>Norms</em></strong></li><li><strong><em>Safeguards</em></strong></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5vdWI6n_jxtSutagzD3Psg.jpeg" /><figcaption>Figure 1 — Process Reasones Canvas Phases.</figcaption></figure><p>The phases of the <em>Reasons Canvas</em> can be further divided into three key sections, which the Thoughtworks team has termed abstract parts, specific parts, and common parts. Let us now describe them.</p><p><strong><em>Abstract Components</em></strong></p><ul><li><strong>Requirements</strong>: What problem are we solving, and what is the DoD (<em>Department of Defense</em>)?</li><li><strong>Entities</strong>: Domain entities and relationships.</li><li><strong>Approach</strong>: The strategy for meeting the requirements.</li><li><strong>Structure</strong>: Where the change fits into the system; components and dependencies.</li></ul><p><strong>Note</strong>: Please do not confuse this use of the acronym DoD (in IT) with the acronym DOD. It does not refer to the US government agency known as the <em>Department of Defense</em> (which has actually changed its name to the <em>Department of War</em>).</p><p><strong><em>Specific Components</em></strong></p><ul><li><strong>Operations</strong>: Break down the abstract strategy into concrete, verifiable implementation steps.</li></ul><p><strong><em>Common Components</em></strong></p><ul><li><strong>Standards</strong>: Cross-cutting engineering standards (naming conventions, observability, defensive coding, etc.)</li><li><strong>Safeguards</strong>: Non-negotiable limits (invariants, performance limits, security rules, etc.)</li></ul><p>The proposal establishes a clear process framework that prevents the fragmentation of chat interactions and other inconsistencies in references. These processes operate on the same artifact, enabling adherence to a consistent approach when handling requests. Furthermore, as the number of requests aimed at improving, modeling, and refining the design increases, the collective capability — derived from these interactions — surpasses that of any single individual, thereby reducing variability within the development team.</p><h4>SPDD Workflow</h4><p>The SPDD workflow facilitates the implementation of specific approaches that allow tasks to be better focused, preventing them from veering off track or becoming fragmented. For instance, reviews shift from traditional “bug-hunting” exercises to “intent verification” checks. This simple shift in focus significantly improves overall processes. It is important to note that this practice aligns closely with the standards outlined by <a href="https://github.com/tembo/aifsd">AIFSD (<em>Artificial Intelligence First Software Development</em>)</a>.</p><p>The SPDD approach begins in the same way as SDD (Specification-Driven Development): the process starts with detailing the specifications. These specifications must be clear and concise to ensure the model can subsequently implement them. However, SPDD handles this slightly differently than SDD. SPDD treats processes in a structured manner, using guidelines that organize team resources — ensuring they are controlled and reusable — and incorporating reviews based on the “Reasons Canvas” alongside the SPDD workflow itself. This process evolves in tandem with the code, as it operates as a specification-anchored approach — a concept championed by expert developer <a href="https://www.thoughtworks.com/profiles/b/birgitta-bockeler">Birgitta Böckeler</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1Pbfx4mLd5-vGcq-LaZSjw.jpeg" /><figcaption>Figure 2 — SPDD Workflow.</figcaption></figure><p>The goal of this workflow is to focus on the prompts themselves, allowing developers and product owners to avoid repetitive alignment cycles. Furthermore, the prompt establishes a precise boundary for code generation, reducing the randomness associated with LLM non-determinism and simplifying management. By treating prompts as first-class artifacts in version control, we transform successful practices into reusable assets, thereby improving consistency and reducing redundant work.</p><p>There is a set of commands documented in <a href="https://github.com/gszhangwei/open-spdd">openspdd</a>. These commands are used to develop design processes using SPDD.</p><h4>Conclusions</h4><p>SPDD represents a fundamental shift in how developers create software. Through the work of the Thoughtworks team, we have identified three essential skills required to perform effectively. These skills reflect the evolving value of developers in an AI-driven world.</p><p>Source: <a href="https://martinfowler.com/articles/structured-prompt-driven/">https://martinfowler.com/articles/structured-prompt-driven/</a></p><p>See you soon!</p><p>Ariel.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=32eabb676446" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SPDD — Un Nuevo Paradigma en el Diseño y Desarrollo de Software con IA]]></title>
            <link>https://medium.com/@arielwagnermovil/spdd-un-nuevo-paradigma-en-el-dise%C3%B1o-y-desarrollo-de-software-con-ia-32a69fa5cc2a?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/32a69fa5cc2a</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[spdd]]></category>
            <category><![CDATA[sdd]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Wed, 30 Sep 2026 15:47:45 GMT</pubDate>
            <atom:updated>2026-09-30T15:47:45.640Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TsvHuaAwNqkDFlNlw4WXng.png" /></figure><h4>Introducción</h4><p>Tras la irrupción de la IA (<em>Inteligencia Artificial</em>) en nuestras vidas, ya sea profesionales como cotidianas, el uso de los prompt que propone la tecnología LLM (<em>Large Language Model</em>), ha sido el pilar básico para el desarrollo general. Sin embargo, y como ya sabemos, el uso de simples prompts sin una estructura adecuada no nos permite lograr una mejor experiencia en el proceso.</p><p>El departamento <a href="https://www.thoughtworks.com/engineering">Thoughtworks</a>, un recurso que puedes encontrar en el sitio Web del arquitecto <a href="https://martinfowler.com/">Martin Fowler</a>, ha desarrollado una estrategia interesante que propone un paradigma distinto para el proceso de diseño constructivo del software mediante el uso de IA. El equipo de Thoughtworks ha desarrollado un flujo de procesos al que han llamado como SPDD (<em>Structured Prompt-Driven Development</em>) o en español como (<em>Desarrollo Estructurado Guiado por Indicaciones</em>). Este enfoque permite a los desarrolladores hacer un mayor énfasis en la construcción de prompts eficaces mediante el uso de un proceso estructurado.</p><h4>Propuesta del Equipo Thoughtworks</h4><p>El equipo ha detectado entre los desarrolladores tres características claves para un desarrollo eficaz y estas son las siguientes: <em>alineación, abstracción prioritaria </em>y<em> revisión iterativa</em>.</p><p>Una primera característica que se aprecia entre los desarrolladores, a nivel individual, es el aspecto resolutivo que surge para los procesos de redacción, modificación y refactorización. Gracias a ello los trabajos se pueden instrumentar de forma más rápida que antes. Además, existen otros aspectos que el equipo señala, respecto a la velocidad de entrega y que no estaría limitada a la cantidad de texto escrito. Sin embargo, resulta interesante resaltar la fricción que se produce a lo largo del proceso del desarrollo dentro del contexto del ciclo de vida del desarrollo.</p><p>El equipo señala estos puntos interesantes a los que debemos prestar atención para su posterior análisis.</p><ul><li><em>Requisitos Ambiguos y Malos Entendidos.</em></li><li><em>Revisiones más Recurrentes y las Generación Indirectas de Inconsistencias Ingresadas.</em></li><li><em>Problemas de Integración y Pruebas. Generación no es Alineación.</em></li><li><em>Aumento del Riesgo en Producción en función al Aumento de Cambios.</em></li></ul><p>El trabajo del equipo de Thoughtworks es muy claro con respecto a la velocidad dado que no mejora la capacidad de rendimiento. Por este motivo, como bien señala el equipo Thoughtworks, la pregunta clave aquí es; ¿cómo logramos que los cambios generados por IA sean controlables, revisables y reutilizables, para que los equipos trabajen con mayor rapidez y seguridad? Esta misma cuestión llevó al equipo Thoughtworks a desarrollar SPDD.</p><h4>Los Principios de SPDD</h4><p>La regla más importante de SPDD es la de establecer un proceso estructurado para el diseño en lugar de depender del uso improvisado de los prompts. Este proceso hace énfasis en las versiones, revisiones, las reutilizaciones y por supuesto, todas las mejoras posibles. Dicho de otra forma, todo esto es estructurado bajo un conjunto de indicaciones bien instrumentadas.</p><p>El LLM genera el código dentro de un espacio o límite bien definido de modo tal de lograr que sea más fácil de validar y predecir. El equipo Thoughtworks ha estructurado este proceso bajo dos escenarios posibles de control y estos son los siguientes:</p><ul><li><strong><em>Reasons Canvas — (Lienzo de Razones)</em></strong> — Fomenta la claridad en torno a los requisitos, el modelo de dominio, el enfoque de la solución, la estructura del sistema, la descomposición de tareas, las normas reutilizables y las medidas de seguridad. Por lo tanto, el LLM se guía por la intención, no por conjeturas.</li><li><strong><em>SPDD Workflow — (Flujo de Trabajo de SPDD)</em></strong> — El flujo de trabajo integra las indicaciones en la misma disciplina que el código basándose precisamente en el historial de confirmaciones, revisión y controles de calidad. Además, impone una regla simple pero poderosa y es para cuando la realidad difiere, primero corrige el mensaje y luego actualiza el código.</li></ul><p>El equipo Thoughtworks describe ambos como dos modelos de control de indicaciones para la obtención de las mejores prácticas para el diseño del software mediante el uso de IA.</p><h4>Reasons Canvas</h4><p>El proceso de control bajo este escenario hace uso de un proceso de control basado en siete fases y estas son las siguientes:</p><ul><li><em>Requirements — (Requerimientos)</em></li><li><em>Entities — (Entidades)</em></li><li><em>Approach — (Enfoque)</em></li><li><em>Structure — (Estructura)</em></li><li><em>Operations — (Operaciones)</em></li><li><em>Norms — (Normas)</em></li><li><em>Safeguards — (Salvaguardas)</em></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vak6SvDWpmvV6lvXI_G32g.jpeg" /><figcaption>Figura 1 — Fases de los Procesos de Reasons Canvas.</figcaption></figure><p>Las fases de Reasons Canvas se pueden a su vez separar en tres secciones importantes las que el equipo Thoughtworks ha denominado como <em>partes abstractas</em>, <em>partes específicas</em> y <em>partes comunes</em>. A continuación, pasemos a describirlas.</p><p><strong><em>Partes Abstractas</em></strong></p><ul><li><strong>Requisitos</strong>: ¿Qué problema estamos resolviendo y qué es el DoD (<em>Department of Defense</em>) o en español (<em>Departamento de Defensa</em>)?</li><li><strong>Entidades</strong>: Entidades y relaciones del dominio.</li><li><strong>Enfoque</strong>: La estrategia de cómo cumpliremos con los requisitos.</li><li><strong>Estructura</strong>: Dónde encaja el cambio en el sistema; componentes y dependencias.</li></ul><p><strong>Nota</strong>: <em>Por favor, no confundas el uso de estas siglas DoD en informática con las siglas DOD. Estas no hacen referencia a la agencia del gobierno de los EEUU, conocido como Deparment of Defense y que actualmente ha cambiado su nombre por Department of War.</em></p><p><strong><em>Partes Específicas</em></strong></p><ul><li><strong>Operaciones</strong>: Descomponga la estrategia abstracta en pasos de implementación concretos y comprobables.</li></ul><p><strong><em>Partes Comunes</em></strong></p><ul><li><strong>Normas</strong>: Normas de ingeniería transversales (nomenclatura, observabilidad, codificación defensiva, etc.)</li><li><strong>Salvaguardias</strong>: Límites no negociables (invariantes, límites de rendimiento, reglas de seguridad, etc.)</li></ul><p>La propuesta establece un claro marco de proceso que evita la dispersión de las interacciones en los chats entre otras diferencias referenciales. Los procesos razonan sobre el mismo artefacto dado que les permiten seguir un lineamiento manteniendo la misma solicitud de la misma manera. Al incrementar las solicitudes con el objeto de mejorar, modelar y perfeccionar el diseño, por otro lado, también incrementa la potencia por sobre la experiencia individual, a través de las interacciones, lo cual permite una reducción de la variabilidad dentro de un equipo de desarrollo.</p><h4>SPDD Workflow</h4><p>El flujo de trabajo de SPDD permite instrumentar mejor algunos enfoques particulares que permiten concentrar mejor las tareas y evitar que estas se desvíen o dispersen. Por ejemplo, las revisiones dejan de ser las clásicas prácticas de “<em>búsqueda de errores</em>” enfocándose en las “<em>verificaciones de las intenciones</em>”. Este simple ejemplo de cambio de enfoque mejora significativamente todos los procesos. Resulta muy importante señalar que esta práctica sigue muy bien los lineamientos trazados como estándares según lo indica <a href="https://github.com/tembo/aifsd">AIFSD (<em>Artificial Intelligence First Software Development</em>)</a>.</p><p>La propuesta de SPDD se inicializa de igual forma como lo hacemos cuando utilizamos SDD (<em>Spec Driven-Development</em>). Es decir, el proceso comienza con el detallado de las especificaciones. Estas mismas deben ser muy claras y concisas para que luego el modelo las implemente. Sin embargo, la propuesta SPDD las hace de forma ligeramente distinta con respecto a SDD. SPDD trata los procesos de forma estructurada, a través de indicaciones que permiten estructurar los recursos de los equipos controlados, reutilizables y de las revisiones basadas en Reasons Canvas más el flujo de trabajo de SPDD Workflow. Este proceso irá evolucionando junto al código, dado que se comporta como un enfoque anclado a la especificación, tal cual lo afirma la experta desarrolladora <a href="https://www.thoughtworks.com/profiles/b/birgitta-bockeler">Birgitta Böckeler</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0d64T9YT0LB_PXoAG7X2Wg.jpeg" /><figcaption>Figura 2 — Flujo de Trabajo SPDD.</figcaption></figure><p>El objetivo de este flujo de trabajo es la de enfocarse por sobre las indicaciones, a los efectos de que los desarrolladores y responsables deL producto eviten ciclos repetitivos de alineación. Por otro lado, la indicación establece un límite exacto para la generación de código, reduciendo la aleatoriedad del no determinismo del LLM y facilitando su gestión. Cuando consideramos a las indicaciones como artefactos de primera clase en el control de versionados, pasamos a convertir las prácticas en exitosas en recursos reutilizables, mejorando la coherencia y reduciendo tareas sin tener que volver a recrearlas nuevamente.</p><p>Existe un conjunto de comandos que pueden encontrarse documentados en <a href="https://github.com/gszhangwei/open-spdd">openspdd</a>. Los comandos son utilizados para poder desarrollar los procesos para el diseño mediante SPDD.</p><h4>Conclusiones</h4><p>SPDD supone un cambio fundamental en la forma en que los desarrolladores crean software. En el trabajo del equipo de Thoughtworks hemos identificado tres habilidades esenciales que son necesarias para desempeñar una labor con eficacia. Estas habilidades reflejan la evolución del valor de los desarrolladores en un mundo impulsado por la IA.</p><p>Fuente: <a href="https://martinfowler.com/articles/structured-prompt-driven/">https://martinfowler.com/articles/structured-prompt-driven/</a></p><p>¡Hasta pronto!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=32a69fa5cc2a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SSD (Spec Driven-Development) for AI — Strategying Design]]></title>
            <link>https://medium.com/@arielwagnermovil/ssd-spec-driven-development-for-ai-strategying-design-00fdede4b6b8?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/00fdede4b6b8</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[tdd]]></category>
            <category><![CDATA[mdd]]></category>
            <category><![CDATA[ddd]]></category>
            <category><![CDATA[sdd]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Sun, 27 Sep 2026 21:45:08 GMT</pubDate>
            <atom:updated>2026-09-27T21:45:08.725Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*t99RVL5a3mF6J_JsU_w1Tg.jpeg" /></figure><h4>Introduction</h4><p>What is SDD (<em>Spect Driven-Development</em>)? <a href="https://www.ibm.com/think/topics/spec-driven-development">IBM Corporation’s</a> website — specifically the “<em>Think</em>” section — offers an interesting description of SDD. It reads as follows: “<em>Is a software methodology in which a detailed specification of implementation details is authored and agreed upon before development begins. In other words, it serves as a single source of truth for what to build and how to build it.</em>”</p><p>That said, I would venture to say that there are many ways to define this design approach. One definition — and my personal favorite — is: “<em>An approach to avoid losing control or compromising quality during software development.</em>” This description is detailed within the <a href="https://scrummanager.com/community/spec-driven-development-qu-es-de-dnde-viene-y-por-qu-importa">Scrum Manager</a> community (In Spanish).</p><p>Beyond these descriptions, the core idea behind SDD is to design software in a specific, detailed manner. This involves several fundamental elements that contribute to an orderly, methodical design process focused on requirements, functionalities, dependencies, technologies, constraints, and so on — while eliminating, as much as possible, any ambiguities or elements irrelevant to the project context.</p><p>In this article, we will break down everything related to SDD so that we can effectively apply this strategy to our future projects. For further details, please visit the <a href="https://en.wikipedia.org/wiki/Specification-driven_development">SDD</a> Wikipedia page.</p><h4>A Brief Evolution of SDD and Its Predecessors</h4><p>SDD is not a new concept today. Before SDD, other similar approaches were developed — though without the use of specifications — aimed at facilitating the software design and construction process. Let us describe a few of them below.</p><p>Let us begin with <a href="https://en.wikipedia.org/wiki/Domain-driven_design">DDD (<em>Domain-Driven Design</em>)</a>. DDD essentially involves designing software based on domain strategies, utilizing a common language often referred to as “ubiquitous language.” This ubiquitous language relies on a strict vocabulary to minimize ambiguities — whether arising in human communication, within the design itself, or even in the software’s initial requirements.</p><p>However, DDD is not the only approach; others exist as well. For instance, there is <a href="https://en.wikipedia.org/wiki/Behavior-driven_development">BDD (<em>Behavior-Driven Design</em>)</a>. This design strategy relies heavily on various types of scenarios to define every component and interaction within the overall model.</p><p>Another well-known method is <a href="https://en.wikipedia.org/wiki/Test-driven_development">TDD (<em>Test-Driven Development</em>)</a>. This strategy allows the software design process to originate from the concept of evaluative testing.</p><p>Finally, there is <a href="https://en.wikipedia.org/wiki/Model-driven_engineering">MDD (<em>Model-Driven Development</em>)</a>, an approach that has not seen much success. Instead of traditional step-by-step coding, this method focuses on modeling the software directly, aiming to automatically generate executable software. Currently, this is the least utilized paradigm.</p><h3>Drafting Specifications for SDD</h3><p>Below, we analyze some key aspects of crafting an effective narrative for writing specifications within the SDD approach.</p><h4>The Challenge of Writing Correctly</h4><p>The first point to grasp is the necessity of writing specifications correctly. Specifications must be precise, readable, and understandable.</p><p>Therefore, to perform this task efficiently, it is essential to clearly detail the desired outcome. The writing process should be approached with the mindset that the specifications are intended for another person — someone completely unfamiliar with our implicit knowledge and even our own personal assumptions. If we want the person to understand what they should and should not do, it is always best to explain and detail everything properly. If these details are not clearly specified, the agent might make a discretionary decision, resulting in something unexpected or undesirable from our perspective. This is the point where the design effectively breaks down.</p><h4>The Game of Implicit Knowledge and Guesswork</h4><p>Another relevant point is the gap between the agent and the developer regarding their respective implicit knowledge — and, in particular, the developer’s assumptions.</p><p>Think of it this way: If I tell you to paint my house green but fail to specify that the window frames should *not* be painted — because I want them a different color — you might paint the walls and the window frames alike. Alternatively, you might paint the window frames a different color — very likely one I dislike. By the time you finish and I see the work, I will realize the result isn’t what I expected. So, what happened? The obvious answer: I didn’t clearly instruct you on what needed to be done. I implicitly assumed you would notice these details and do the work correctly — but that didn’t happen. On the other hand, relying on your own implicit knowledge, you simply did what seemed best to you at the time.</p><p>The same applies to specifications. They must be detailed correctly, leaving no room for assumptions. Remember, the agent is not a mind reader.</p><h4>Word Specificity</h4><p>Keywords — precise and concise — are more powerful than a lengthy narrative explanation. Therefore, use key terms that align with the appropriate professional vocabulary for your field. For instance, adjectives like “<em>fast</em>,” “<em>clean</em>,” “<em>secure</em>,” or “<em>robust</em>” are not actual requirements; each one invites the agent to invent their own definition.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aDyytn6P5ixBS_7nRmEVkQ.png" /><figcaption>Table 1 — Questions and Results.</figcaption></figure><p>Therefore, when you need to formulate a question for the specification, you should do so correctly. Consider this: if you handed that line to someone without any context, could they implement it without asking further questions? If the answer is no, you need to specify it. On the other hand, be careful not to fall into the trap of answering your own questions; in other words, every question you answer within the specification represents a flawed assumption you failed to address in the code.</p><h4>Defining the Negative Scope</h4><p>The premise here might seem obvious, but what you build is just as important as what you choose not to build. Even with the most astute and well-intentioned agent, the results produced may well differ from what was actually expected or desired.</p><pre>## Features not included (v1)<br><br>- No recurring tasks<br>- No calendar integration (planned for v2)<br>- No time tracking: the product does not compete in the analytics space<br>- No task dependencies; only subtasks (max. 50 per task)<br>- No bulk operations (multi-select, bulk deletion)<br>- No offline mode</pre><p>Preventing certain types of errors at the outset is, in a sense, a way to avoid processes becoming more costly than anticipated. A potential issue is that the agent might extend the data model to support functionality you didn’t intend. This indirectly forces you to waste time — most likely refactoring that function to fix it — even though you never included it in your requirements.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/722/1*RcJcr5aBeZsVCnJ-JKA2zA.png" /><figcaption>Table 2 — Concrete examples beat adjectives.</figcaption></figure><p>Thus, those five rows eliminate at least five potential error reports. Indeed, it is that last row that consistently causes problems. Consequently, no agent will account for the case of blank spaces unless you explicitly include it, because nothing in the “validate title” step (see Table 1) implies trimming the input before validation. In effect, concrete examples transform interpretation into verification: the agent either produces the exact output for a given input or it does not.</p><p>This pattern works for any validation, state machine, or conditional flow. Think in terms of input/output pairs and then document them.</p><h4>Drafting Requirements</h4><p>Drafting requirements often seems like a straightforward task until implementation begins. A quick example of a specification premise might be: “Access permissions must be validated in the processing area.” Ambiguities arise immediately following this specification. Questions emerge: Under which operations? If an error occurs, should the system silently reject the request, throw an exception, or something else? Furthermore, another question arises: Should this happen before or after the validation process?</p><h4>EARS: A Good Solution</h4><p>Alistair Mavin created a mechanism to apply “soft” constraints to textual requirements, known as EARS (Easy Approach to Requirements Syntax). His work, published in 2009, is widely used by companies and institutions around the world, including NASA, Airbus, Intel Corporation, and Bosch.</p><p>EARS patterns provide a structured guide that enables authors to draft high-quality textual requirements. These patterns align particularly well with the operation of AI agents, as EARS facilitates an approach where precise wording and definitions function efficiently within AI systems.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HMk0ml2O1bGXIBQfRvCcWQ.png" /><figcaption>Table 3 — Writing Requirements in EARS.</figcaption></figure><p>Words such as WHEN, IF, WHILE, and SHALL function as contractual terms. These words are key to ensuring correct phrasing.</p><p>Each element should be used based on the specific requirements context. They can be used all together or selectively, depending on the need. The core idea is to adapt the pattern to the requirement type, bearing in mind that an invariant is ubiquitous, a user action is event-driven, and a guard condition is state-based.</p><p>Last but not least, there are established usage practices for EARS vocabulary — specifically English terms like SHALL (mandatory) or SHALL NOT (prohibited). These align directly with the MoSCoW prioritization framework (e.g., SHALL = Must have, SHOULD = Should have, MAY = Could have, WON’T = Won’t have).</p><h4>Frequently Asked Questions</h4><p>Before launching into a flood of default questions, it is necessary to filter for the right — and most relevant — ones, refining them as we analyze the project details and advance the conceptual model. Therefore, all ambiguities must be listed and addressed within the specification as a dedicated Q&amp;A section. Any gaps or ambiguities that arise or are detected must be resolved through intentional decisions rather than becoming erroneous assumptions silently embedded in the code.</p><pre>## Implementation FAQs<br><br>**Q: What happens when a user deletes a task that has subtasks?**<br>A: A cascading deletion occurs. Explicit confirmation is requested first:<br>&quot;This will also delete 3 subtasks. Continue?&quot;<br><br>**Q: Who can see unassigned tasks?**<br>A: All workspace members, regardless of their role. Only owners<br>can assign tasks to others.<br><br>**Q: What happens if an assignee is removed from a workspace<br>while they have pending tasks?**<br>A: The tasks remain open with no assigned owner. The workspace owner<br>receives a notification listing the affected tasks.<br><br>**Q: Can a task belong to more than one project?**<br>A: No. A task belongs to exactly one project. This is a limitation of version 1,<br>not a decision that will be reconsidered.<br><br>**Q: Which time zone is used for due dates?**<br>A: They are stored in UTC and displayed according to the user&#39;s profile time zone;<br>&quot;today&quot; and &quot;overdue&quot; are calculated based on the user&#39;s time zone.</pre><p>The entries you need most are those that deviate from the standard path. Examples include cascading deletions, conflicting states, deleted users, time zones, and simultaneous edits. These are precisely the scenarios agents handle worst when left to guess. Training data is saturated with implementations of the standard path but virtually devoid of edge cases.</p><p>Therefore, you should draft your FAQs by imagining the agent in the middle of the implementation process, reaching a decision point where the specification offers no clarity. What would you do in that situation? That question — along with the correct answer — should be included in the FAQs.</p><p>However, a problem might arise: what if you don’t know the answer while writing? In that case, you should mark the question as open (e.g., Q-003: open). Doing this is far better than silence. Without it, the agent might act on its own, trying to guess the required implementation — and as we know, that is a terrible idea. Consequently, resolving this issue promptly is imperative. Remember, an open question is essentially a pending specification — or, put another way, a deferred error.</p><h4>Avoid Multiple Billing</h4><p>One of the most serious issues is the excessive consumption of tokens — which is indirectly equivalent to burning money — during the internal processing of AI agents. The recurrence of tasks and actions supposedly already completed implies that the current design is flawed and requires urgent revision.</p><pre># Specification: Create a payment charge (POST /v1/charges)<br># Status: requirements:approved<br><br>## Overview<br>A merchant creates a charge for a customer. This operation involves the movement of money,<br>so it must be safe to retry while ensuring that double billing does not occur.<br><br>## Scope<br>- Create a charge based on an authenticated request from the merchant.<br>- Return the charge ID and status.<br>- Ensure unique billing (*exactly-once*) in the event of client retries.<br><br>## Out of scope (v1)<br>- Refunds (separate specification: 005-refunds).<br>- Partial captures.<br>- Multi-currency. All amounts are in BRL and stored as integers (cents).<br>Never as floating-point numbers (*float*).<br><br>## Functional requirements (EARS)<br>- FR-1  WHEN a merchant submits a charge via POST with a valid *Idempotency-Key*,<br>THE SYSTEM MUST create at most one charge for that key.<br>- FR-2  WHEN the same idempotency key is reused within a 24-hour period,<br>THE SYSTEM MUST return the original charge and not create<br>a new one.<br>- FR-3  IF the amount is &lt;= 0,<br>THE SYSTEM MUST reject the request with a 422 code and the message &quot;amount must be positive&quot;.<br>- FR-4  IF the merchant exceeds their rate limit,<br>THE SYSTEM MUST reject the request with a 429 code and a *Retry-After* header.<br>- FR-5  WHILE a charge is pending,<br>THE SYSTEM MUST NOT allow a second capture. ## Acceptance criteria (examples the agent must meet)<br>- amount=1000, key=abc            -&gt; 201, status=pending<br>- same key=abc, retry             -&gt; 200, same charge ID, no new row<br>- amount=0                        -&gt; 422 &quot;amount must be positive&quot;<br>- amount=-50                      -&gt; 422 &quot;amount must be positive&quot;<br>- 6th request in 1s, same merchant -&gt; 429, Retry-After: 1<br><br>## Non-functional requirements<br>- p95 latency under 300 ms at 200 requests/second per merchant.<br>- All monetary values ​​are integers. No floating-point numbers are used anywhere.<br><br>## Data<br>- charges(id, merchant_id, amount_cents, currency, status,<br>idempotency_key, created_at)<br>- UNIQUE(merchant_id, idempotency_key)   # this ensures compliance with FR-1<br><br>## Verification<br>- Integration test: concurrent retry of the same key 50 times;<br>verify that only one row and one accounting entry exist.<br>- Load test: maintain p95 &lt; 300 ms at 200 rps.<br><br>## Confirm before developing<br>Do not write code until you have restated requirements FR-1 through FR-5<br>and the uniqueness constraint in your own words. If any<br>acceptance criterion is ambiguous, consult before implementing.</pre><p>The “out-of-scope” clause indicates what is not covered by the specification. Without it, the agent might expand the charges table to include a `refund_amount` column — since refunds seem related — thereby tying the data model to a function that was never specified.</p><p>Rules FR-1 and FR-2 jointly specify idempotency in both directions: upon the first receipt, a charge is created; upon the second, the original is returned. If repeated, both directions are accounted for, as the two scenarios yield different HTTP responses.</p><p>FR-3 and FR-4 define patterns of undesired behavior. They specify how the system should act when something goes wrong. Without them, the agent chooses its own error codes — sometimes 400, sometimes 500, sometimes none at all.</p><p>Acceptance criteria are not a test suite. They are a table of input/output pairs included in the specification, allowing the agent to verify their own work before you review anything.</p><p>“Every monetary value is an integer.” This simple phrase prevents the floating-point rounding errors that plague payment systems by their second day in production. It belongs in the specification, not in a code comment, as comments do not persist after the session ends.</p><p>The UNIQUE constraint is the mechanism that enforces FR-1. If omitted, the agent might attempt to enforce idempotency via application logic — logic that fails during concurrent retries, whereas a database constraint does not.</p><p>“Confirm before coding” is the final line, and it is not merely for show. The agent restates requirements FR-1 through FR-5 in their own words before writing a single character of code. If they misunderstood FR-2, you find out right then — at no cost — rather than after three implementation sessions. It is the most cost-effective error prevention measure you will ever write.</p><h4>Checklist: Before handing the specification to the agent</h4><ul><li>The “smart kid” test is passed: someone with no prior context builds the right thing based solely on the document.</li><li>All functional requirements are written using EARS. If any requirement like “should be fast” or “handle errors appropriately” remains, find and replace it.</li><li>Explicit out-of-scope items: at least 3 elements that are *not* being developed. The absence of this section implies a scope risk, not a clean specification.</li><li>Validation rules include input/output tables. Text validation is almost always underspecified.</li><li>Every user story has verifiable acceptance criteria. A criterion that cannot be independently verified is a vague goal, not a requirement.</li><li>Unique, stable identifiers exist: US-001, FR-001, NFR-001, D-001. Without them, traceability is compromised.</li><li>Implementation FAQs cover, at a minimum, the three most common edge cases: deletion cascades, conflicting state scenarios, and any edge cases related to access control.</li><li>Performance requirements are expressed using numbers, not adjectives.</li><li>The specification ends with a line stating “Confirm before compiling.”<br>The status remains “draft” until you approve it. A draft is not an approved specification.</li><li>Non-functional requirements (NFRs) cover performance, security, and accessibility — the three sections most frequently missing from initial drafts.</li></ul><p>Three or more unchecked items? The agent will guess. And assumptions in requirements turn into bugs in production.</p><p>A good specification takes between 30 and 90 minutes to create for a typical feature. That time is recouped during the first implementation session: it is spent solving truly difficult problems, rather than debugging misinterpreted requirements.</p><p>Source: <a href="https://github.com/felipefontoura/spec-driven-development-book/blob/main/BOOK.en.md">https://github.com/felipefontoura/spec-driven-development-book/blob/main/BOOK.en.md</a></p><p>See you soon!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=00fdede4b6b8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SSD (Spec Driven-Development) para IA — Diseño Estratétigco]]></title>
            <link>https://medium.com/@arielwagnermovil/ssd-spec-driven-development-para-ia-dise%C3%B1o-estrat%C3%A9tigco-82b14c6d6683?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/82b14c6d6683</guid>
            <category><![CDATA[mdd]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[tdd]]></category>
            <category><![CDATA[sdd]]></category>
            <category><![CDATA[ddd]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Sun, 27 Sep 2026 20:59:59 GMT</pubDate>
            <atom:updated>2026-09-27T20:59:59.716Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*j1Irbec_x8iT9jRRK10HZg.png" /></figure><h4>Introducción</h4><p>¿Qué es SDD (<em>Spect Driven-Development</em>)? En el sitio Web de <a href="https://www.ibm.com/think/topics/spec-driven-development">IBM Corporation</a> en la sección Pensar (Think en inglés) se hace una descripción interesante de SDD. La descripción es la siguiente: “<em>Se trata de una metodología de software en la que se elabora y se acuerda una especificación detallada de los detalles de implementación antes de que comience el desarrollo. En otras palabras, sirve como fuente única de información fidedigna sobre qué construir y cómo construirlo.</em>”</p><p>Por otro lado, me atrevo a decirte que existen muchas formas de definir de qué se trata esta propuesta de diseño. Una forma y la que más me gusta podría ser: “<em>Una propuesta para no perder el control y descuidar la calidad al desarrollar software.</em>” Esta descripción se detalla en la comunidad <a href="https://scrummanager.com/community/spec-driven-development-qu-es-de-dnde-viene-y-por-qu-importa">Scrum Manager</a>.</p><p>Ahora bien, más allá de las descripciones dadas, la idea que persigue SDD es la de diseñar de forma específica el software. Todo ello incluye diversos puntos fundamentales que contribuyen al diseño de forma ordenada, metódica, enfocada en los requisitos, funcionalidades, dependencias, tecnologías, restricciones, etc., excluyendo en lo posible toda clase de ambigüedades o recursos que no dan lugar al contexto del proyecto.</p><p>En este artículo vamos a desglosar todo lo que concierne a SDD para poder aplicar esta estrategia de forma eficaz en nuestros futuros proyectos. Para mayores detalles visita Wikipedia <a href="https://es.wikipedia.org/wiki/Desarrollo_dirigido_por_especificaciones">SDD</a>.</p><h4>Breve Evolución de SDD y sus Antecesores</h4><p>Actualmente SDD no resulta ser una novedad. Antes de SDD se desarrollaron otros enfoques muy parecidos a este, excepto que no utilizaban especificaciones, de modo tal de favorecer el proceso de diseño y construcción de software. Describamos algunos de ellos a continuación.</p><p>Comencemos por el ejemplo de <a href="https://es.wikipedia.org/wiki/Dise%C3%B1o_guiado_por_el_dominio">DDD (<em>Domain Driven Design</em>)</a> o Diseño Conducido por el Dominio. DDD básicamente consiste en el diseño de un software basándose en las estrategias del dominio, a través de un lenguaje coloquial al que se le suele llamar <em>ubicuo</em>. El lenguaje <em>ubicuo</em> no es más que el uso de un vocabulario muy estricto, que reduce las ambigüedades que suelen darse entre la comunicación humana y el diseño mismo e incluso, la que se puede especificar en los propios requerimientos del diseño de un nuevo software.</p><p>Sin embargo, DDD no es el único. También existen otros más. Por ejemplo, <a href="https://es.wikipedia.org/wiki/Desarrollo_guiado_por_comportamiento">BDD (<em>Behavior Driven Design</em>)</a> o Diseño Conducido por Comportamiento. Esta estrategia de diseño se basa particularmente en el uso de diversos tipos de escenarios que permiten determinar cada parte y cada interacción del modelo en general.</p><p>También existe otro conocido como <a href="https://es.wikipedia.org/wiki/Desarrollo_guiado_por_pruebas">TDD (<em>Test Driven-Development</em>)</a> o Desarrollo Conducido por Pruebas. Esta estrategia de diseño permite que el diseño de software parta del concepto de las pruebas evaluativas.</p><p>Finalmente, contamos con <a href="https://es.wikipedia.org/wiki/Ingenier%C3%ADa_dirigida_por_modelos">MDD (Model Driven-Development)</a> y que no ha tenido mucho éxito. Este enfoque se basa en la modelación del software desde los propios modelos, en lugar de la codificación paso a paso tradicional, de modo tal de generar de forma automática software ejecutable. Este paradigma es el menos utilizado actualmente.</p><h3>Redacción de Especificaciones para SDD</h3><p>A continuación, vamos analizar algunos de los aspectos claves para lograr una narrativa adecuada para la creación de especificaciones para el enfoque SDD.</p><h4>El Desafío de Redactar Correctamente</h4><p>El primer punto que debemos entender es que debemos realizar una redacción de especificaciones correcta. La redacción de especificaciones debe ser precisa, legible y entendible.</p><p>Por tanto, para tener eficiencia en esta labor es necesario detallar bien lo que queramos obtener. La redacción se la debe pensar como si lo que estamos especificando es para que lo lea otra persona, alguien que es muy ajeno a nuestros conocimientos implícitos e incluso, de nuestras propias presuposiciones personales. Si pretendemos que la persona entienda lo que debe y no debe hacer, siempre es mejor explicar y detallar todo de forma correcta. Si a un agente no se le especifica bien estos detalles, el agente por propia decisión podría operar de forma discresional, creando luego algo inesperado o no deseado para nosotros. Aquí es cuando el diseño prácticamente se rompe.</p><h4>El Juego del Conocimiento Implícito y las Adivinanzas</h4><p>Otro punto relevante es la separación que existe entre lo que el agente y el desarrollador respecto a los conocimientos implícitos de ambos y particularmente las presuposiciones del desarrollador.</p><p>Piénsalo de la siguiente forma. Si yo a tí te digo que pintes mi casa de color verde y no te detallo que los marcos de la ventanas no las pintes porque las quiero de otro color. Es probable que tú pintes las paredes y quizá los marcos de las ventanas también, o por el contrario, quizá pintes los marcos de las ventanas de otro color distinto y muy probablemente del color que no me gusta. Para cuando termines tu trabajo y observe lo que hiciste, terminaré dándome cuenta de que el resultado no era el que esperaba. Entonces, ¿qué pasó aquí? Pues lo obvio, no te indiqué bien lo que tenías que hacer. En mis pensamientos implícitos supuse que tú te darías cuenta de estos detalles y harías el trabajo correctamente lo cual eso no sucedió. Por otro lado, tú mismo también con tus propios conocimientos implícitos hiciste lo que te fue conveniente en ese momento.</p><p>Con las especificaciones pasa exactamente lo mismo. Se debe detallar correctamente y no dar cabida a las presuposiciones. Recuerda que el agente no es un adivino.</p><h4>La Especificidad de las Palábras</h4><p>Las palabras claves, certeras y concisas son más potentes que una narrativa extensa explicando algo. Por tanto, utiliza palábras que resulten ser claves, ajustadas al léxico apropiado al que te desenvuelves. Por ejemplo, los adjetivos no son requisitos; “<em>rápido</em>”, “<em>limpio</em>”, “<em>seguro</em>” o “<em>robusto</em>”. Cada uno es una invitación para que el agente invente su propia definición.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/771/0*z6HFEY2kKyvaHUyK" /><figcaption>Tabla 1 — Preguntas y Resultados.</figcaption></figure><p>Por lo tanto, cuando debes formular una pregunta para la especificación, deberías hacerlo de forma correcta. Por ejemplo, piensa lo siguiente. Si le entregaras esta línea a alguien sin contexto, esta persona ¿podría implementarla sin más preguntas? Si la respuesta es no, deberías especificarla. Por otro lado, ten cuidado que no caer en las autorespuestas. Es decir, cada pregunta que respondas en la especificación es una suposición errónea que omitiste en el código.</p><h4>Declarando el Alcance Negativo</h4><p>Aquí la premisa podría ser bastante obvia pero lo que construyas es tan importante como aquello que no hagas. Ante el agente más astuto y con buenas intenciones, es probable que los resultados esperados que este ejecute no sean los esperados y deseados.</p><pre>## Objetivos no incluidos (v1)<br><br>- Sin tareas recurrentes<br>- Sin integración con calendarios (previsto para la v2)<br>- Sin seguimiento del tiempo: el producto no compite en el ámbito de la analítica<br>- Sin dependencias entre tareas; solo subtareas (máximo 50 por tarea)<br>- Sin operaciones masivas (selección múltiple, eliminación masiva)<br>- Sin modo sin conexión</pre><p>Prevenir algunos tipos de errores de forma inicial es en cierto modo evitar que los procesos terminen siendo más costosos de lo esperado. El problema que podría suceder es que el agente extienda el modelo de datos para un tipo de funciones que no deseabas. Esto te obliga indirectamente que pierdas el tiempo haciendo muy probablemente un refactoreo de dicha función para corregirla pese a que no la pediste en tus requisitos.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/767/0*R-qmvhLVKrDI3Xh9" /><figcaption>Tabla 2 — Ejemplos concretos superan a los adjetivos.</figcaption></figure><p>Por tanto, las cinco filas anulan por lo menos unos cinco informes de errores. En efecto, esta última fila es la que siempre produce problemas. En consecuencia, ningún agente añadirá el caso de espacios en blanco a menos que tu lo hagas porque nada en “<em>validar el título</em>” (ver tabla 1) implica <em>recortar antes de validar</em>. En consecuencia, los ejemplos concretos convierten la interpretación en verificación. El agente produce la salida exacta para esa entrada, o no la produce.</p><p>Este patrón funciona para cualquier validación, cualquier máquina de estados, cualquier flujo condicional. Piensa en pares de entrada/salida y luego anótalos.</p><h4>Redactando Requisitos</h4><p>La redacción de los requisitos suele aparentar ser una tarea sencillamente razonable hasta que estos se implmentan. Un ejemplo rápido podría ser, para un caso de especificación dada, la siguiente premisa; “<em>Se debe validar los permisos de acceso en el área de procesamiento.</em>” Tras esta especificación es cuando surgen las ambigüedades. Se plantea la pregunta ¿<em>bajo qué operaciones</em>? En caso de producirse un error, ¿<em>proceder con el rechazo silencioso, procesar una excepción, o qué</em>?, luego a este cuestionamiento se le suma otra pregunta más; ¿<em>antes o después del proceso de validación</em>?</p><h4>EARS Como una Buena Solución</h4><p>El alemán Alistair Mavin fue el creador de un mecanismo para restringir de forma suavizada los requisitos textuales. Este se lo conoce con el nombre de EARS (<em>Easy Approach Requirements Syntaxs</em>). Su trabajo fue publicado en 2009 y es muy utilizado por muchas compañías e instituciones en el mundo donde entre ellos figura NASA, Airbus, Intel Corporation, Bosch entre otras.</p><p>Los patrones EARS proporcionan una guía estructurada que permite a los autores redactar requisitos textuales de alta calidad. Los patrones EARS se ajustan muy bien a la operativa de los Agentes IA. Ello es debido a que EARS permite establecer un enfoque donde el uso de palabras o definiciones exactas pueden funcionar eficientemente en los Agentes IA.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Mj7WbAg_LKzptYJC" /><figcaption>Tabla 3 — Redactando los Requisitos en EARS.</figcaption></figure><p>Cada una de las palabras tales como <em>CUANDO</em>, <em>SI</em>, <em>MIENTRAS</em>, <em>DEBERÁ</em>, se tratan de contratos. Estas palabras resultan claves para el ordenamiento de la redacción correcta.</p><p>Cada uno de los elementos se deben utilizar en función al contexto de requisitos con el que se esté trabajando. Se pueden utilizar todos ellos, o bien, de modo parcial algunos de ellos, según sea la necesidad. La idea principal detrás de esto es adaptar el patrón al tipo. Considerando que una constante invariante es ubicua, una acción del usuario es basada en eventos y una condición de guarda se basa en su estado.</p><p>Por último, y no menos importante, existe una práctica de uso para el vocabulario de EARS. Por ejemplo, palabras en inglés como SHALL (<em>obligatorio</em>) o SHALL NOT (<em>prohibido</em>). Estas corresponden directamente al marco de trabajo de priorización MoSCoW. Por ejemplo, estas podrían conformar palabras como SHALL=Debe tener, SHOULD=Debería tener, MAY=Podría tener, WON’T=No tendrá.</p><h4>Las Preguntas Frecuentes</h4><p>Antes de comenzar con una catarata de preguntas por defecto, resulta necesario filtrar las preguntas correctas, las más relevantes, de modo de ir refinándolas a medida que vamos analizando y avanzando en el modelo conceptual cada detalle del proyecto. Por tanto, resulta necesario enumerar todas las ambigüedades y respónderlas en la especificación como una sección explícita de preguntas y respuestas. Cada laguna o situaciones difusas que se presenten o detectes, debe convertirse en una decisión tomada intencionalmente y no en una suposición errónea incorporada silenciosamente en el código.</p><pre>## Preguntas frecuentes sobre la implementación<br><br>**P: ¿Qué sucede cuando un usuario elimina una tarea que tiene subtareas?**<br>R: Se produce una eliminación en cascada. Primero se solicita confirmación explícita:<br>&quot;Esto también eliminará 3 subtareas. ¿Continuar?&quot;<br><br>**P: ¿Quién puede ver las tareas no asignadas?**<br>R: Todos los miembros del espacio de trabajo, independientemente de su rol. Solo los propietarios<br>pueden asignar tareas a otros.<br><br>**P: ¿Qué sucede si se elimina a un responsable de un espacio de trabajo<br>mientras tiene tareas pendientes?**<br>R: Las tareas permanecen abiertas sin responsable asignado. El propietario del espacio de trabajo<br>recibe una notificación con la lista de las tareas afectadas.<br><br>**P: ¿Puede una tarea pertenecer a más de un proyecto?**<br>R: No. Una tarea pertenece exactamente a un proyecto. Es una limitación de la versión 1,<br>no una decisión que se vaya a reconsiderar.<br><br>**P: ¿Qué zona horaria se utiliza para las fechas de entrega?**<br>R: Se almacena en UTC; se muestra según la zona horaria del perfil del usuario;<br>&quot;hoy&quot; y &quot;vencida&quot; se calculan según la zona horaria del usuario.</pre><p>Las entradas que más necesitas son las que se salen del camino normal. Por ejemplo, las eliminaciones con cascadas, los estados conflictivos, los usuarios eliminados, las zonas horarias, las ediciones simultáneas. Estos son precisamente los casos que los agentes manejan peor cuando se les deja adivinar. Los datos de entrenamiento están saturados de implementaciones del camino normal y prácticamente vacíos en casos límite.</p><p>Por tanto, deberías redactar las preguntas frecuentes imaginando al agente en pleno proceso de implementación, llegando a un punto de en la tomas de decisiones y donde la especificación no lo aclara. En ese caso, ¿qué harías? Bien, esa pregunta se debiera incluir en las preguntas frecuentes junto a la respuesta correcta a su lado.</p><p>Pero, quizá podría producirse un problema aquí y es ¿qué tal si <em>no</em> conozco la respuesta al escribir? En ese caso deberías anotar la pregunta como abierta ( Q-003: open). Hacer esto resulta ser mucho mejor que el propio silencio. Ello es porque de no ser así el agente podría actuar de forma discreta tratando de adivinar la implementación que se requiere, y como sabemos, esto es una muy mala idea. Por lo tanto, no olvides que es imperioso que lo resuelvas cuanto antes. Recuerda que una pregunta abierta es indirectamente una especificación aprobada pero a su vez es un error diferido.</p><h4>Evita Facturar Más de Una Vez</h4><p>Uno de los problemas más serios que suelen producirse es la quema de tokens, lo que equivale indirectamente a la quema de dinero en los procesamientos internos de los Agentes IA. La recurrencia de tareas y acciones que se supone ya se han ejecutado, repetir todos estos procesos de nuevo asume indirectamente que el diseño pergeniado no es el adecuado y este requiere de una urgente revisión.</p><pre># Especificación: Crear un cargo de pago (POST /v1/charges)<br># Estado: requisitos:aprobados<br><br>## Descripción general<br>Un comercio crea un cargo a un cliente. Esta operación implica movimiento de dinero,<br>por lo que debe ser segura para reintentar y garantizar que no se produzca una doble facturación.<br><br>## Alcance<br>- Crear un cargo a partir de una solicitud autenticada del comercio.<br>- Devolver el ID y el estado del cargo.<br>- Garantizar una facturación única (*exactly-once*) ante reintentos del cliente.<br><br>## Fuera del alcance (v1)<br>- Reembolsos (especificación separada: 005-refunds).<br>- Capturas parciales.<br>- Multidivisa. Todos los importes están en BRL y se almacenan como números enteros (centavos). <br>Nunca como números de punto flotante (*float*).<br><br>## Requisitos funcionales (EARS)<br>- FR-1  CUANDO un comercio envía un cargo mediante POST con una clave de idempotencia (*Idempotency-Key*) válida,<br>EL SISTEMA DEBE crear como máximo un cargo para dicha clave.<br>- FR-2  CUANDO se reutiliza la misma clave de idempotencia en un plazo de 24 horas,<br>EL SISTEMA DEBE devolver el cargo original y no crear<br>ninguno nuevo.<br>- FR-3  SI el importe es &lt;= 0,<br>EL SISTEMA DEBE rechazar la solicitud con un código 422 y el mensaje &quot;amount must be positive&quot;.<br>- FR-4  SI el comercio supera su límite de tasa (*rate limit*),<br>EL SISTEMA DEBE rechazar la solicitud con un código 429 y una cabecera *Retry-After*.<br>- FR-5  MIENTRAS un cargo esté pendiente,<br>EL SISTEMA NO DEBE permitir una segunda captura. ## Criterios de aceptación (ejemplos que el agente debe cumplir)<br>- amount=1000, key=abc            -&gt; 201, status=pending<br>- misma key=abc, reintento        -&gt; 200, mismo ID de cargo, sin nueva fila<br>- amount=0                        -&gt; 422 &quot;amount must be positive&quot;<br>- amount=-50                      -&gt; 422 &quot;amount must be positive&quot;<br>- 6.ª petición en 1 s, mismo comercio -&gt; 429, Retry-After: 1<br><br>## Requisitos no funcionales<br>- Latencia p95 inferior a 300 ms con 200 peticiones/segundo por comercio.<br>- Todos los valores monetarios son enteros. No se utiliza coma flotante en ninguna parte.<br><br>## Datos<br>- charges(id, merchant_id, amount_cents, currency, status,<br>idempotency_key, created_at)<br>- UNIQUE(merchant_id, idempotency_key)   # esto garantiza el cumplimiento de FR-1<br><br>## Verificación<br>- Prueba de integración: reintento concurrente de una misma clave 50 veces; <br>verificar que solo exista una fila y un asiento contable.<br>- Prueba de carga: mantener p95 &lt; 300 ms a 200 rps.<br><br>## Confirmar antes de desarrollar<br>No escribas código hasta haber reformulado con tus propias palabras<br>los requisitos FR-1 a FR-5 y la restricción de unicidad. Si algún<br>criterio de aceptación resulta ambiguo, consulta antes de implementar.</pre><p>La cláusula “fuera de alcance” indica lo que no está cubierto en la especificación. Sin ella, el agente podría ampliar la tabla de cargos con una refund_amountcolumna porque los reembolsos parecen estar relacionados, y entonces el modelo de datos quedaría vinculado a una función que no se ha especificado.</p><p>Las reglas FR-1 y FR-2 especifican conjuntamente la idempotencia en ambas direcciones: en la primera recepción, se crea un cargo; en la segunda, se devuelve el original. Si se repite, se cierran ambas direcciones, ya que las dos situaciones generan respuestas HTTP diferentes.</p><p>FR-3 y FR-4 son los patrones de comportamiento no deseado. Especifican qué hace el sistema cuando algo falla. Sin ellos, el agente elige sus propios códigos de error: a veces 400, a veces 500, a veces ninguno.</p><p>Los criterios de aceptación no son un archivo de prueba. Son una tabla de pares de entrada/salida que se encuentra en la especificación, para que el agente pueda verificar su propio funcionamiento antes de que usted revise nada.</p><p>«Cada valor monetario es un número entero». Esta simple frase evita el error de redondeo de coma flotante que afecta a los sistemas de pago al segundo día de producción. Se encuentra en la especificación, no en un comentario de código, ya que los comentarios no se conservan tras el cierre de la sesión.</p><p>La restricción UNIQUE es la forma en que se aplica FR-1. Si se omite, el agente podría imponer idempotencia en la lógica de la aplicación. La lógica de la aplicación falla ante reintentos concurrentes. La restricción de la base de datos no.</p><p>«Confirmar antes de compilar» es la última línea, y no es un adorno. El agente repite los requisitos FR-1 a FR-5 con sus propias palabras antes de escribir un carácter. Si malinterpretó el FR-2, lo descubres ahora, sin costo alguno, no después de tres sesiones de implementación. Es la prevención de errores más económica que jamás escribirás.</p><h4>Lista de verificación: antes de entregar la especificación al agente</h4><ul><li>La prueba del niño inteligente se supera : alguien sin ningún contexto previo construye lo correcto basándose únicamente en el documento.</li><li>Todos los requisitos funcionales están incluidos en EARS. Si se ha conservado algún requisito como “debería ser rápido” o “manejar los errores de forma adecuada”, búsquelo y reemplácelo.</li><li>Alcance negativo explícito : al menos 3 elementos que no se están desarrollando. La ausencia de esta sección supone un riesgo de alcance, no una especificación limpia.</li><li>Las reglas de validación tienen tablas de entrada/salida. La validación de texto casi siempre está insuficientemente especificada.</li><li>Cada historia de usuario tiene criterios de aceptación que se pueden comprobar. Un criterio que no se puede comprobar de forma independiente es un objetivo vago, no un requisito.</li><li>Existen identificadores únicos y estables : US-001, FR-001, NFR-001, D-001. Sin ellos, la trazabilidad se ve comprometida.</li><li>Las preguntas frecuentes sobre la implementación cubren , como mínimo, los tres casos límite más comunes: la cascada de eliminación, el escenario de estado conflictivo y cualquier caso límite relacionado con el control de acceso.</li><li>Los requisitos de rendimiento se expresan con números , no con adjetivos.</li><li>La especificación finaliza con una línea que dice “Confirmar antes de compilar”.</li><li>El .statustexto permanecerequirements:draft sin revisar hasta que lo apruebes. El borrador no está aprobado.</li><li>Los requisitos no funcionales (NFR, por sus siglas en inglés) abarcan el rendimiento, la seguridad y la accesibilidad , las tres secciones que con mayor frecuencia faltan en los primeros borradores.</li></ul><p>¿Tres o más elementos sin marcar? El agente adivinará. Y las suposiciones en los requisitos se convierten en errores en producción.</p><p>Una buena especificación requiere entre 30 y 90 minutos para una funcionalidad típica. Ese tiempo se recupera en la primera sesión de implementación: se dedica a resolver problemas realmente difíciles, no a depurar requisitos mal interpretados.</p><p>Fuente: <a href="https://github.com/felipefontoura/spec-driven-development-book/blob/main/BOOK.en.md">https://github.com/felipefontoura/spec-driven-development-book/blob/main/BOOK.en.md</a></p><p>¡Hasta pronto!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=82b14c6d6683" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Agent — How to Combine AI Agent, MCP, Skills and Guards for Industrial Case]]></title>
            <link>https://medium.com/@arielwagnermovil/ai-agent-how-to-combine-ai-agent-mcp-skills-and-guards-for-industrial-case-007c60281100?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/007c60281100</guid>
            <category><![CDATA[industrial-design]]></category>
            <category><![CDATA[mcps]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[guard]]></category>
            <category><![CDATA[skills]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Sun, 20 Sep 2026 16:29:39 GMT</pubDate>
            <atom:updated>2026-09-20T16:29:39.493Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UxMkfssFqD4_AXiRHd7GQA.png" /></figure><h4>Introduction</h4><p>In previous articles, I have discussed how AI Agents utilize various additional tools to significantly enhance their performance. Here, we will examine — through a real-world industry case study — key factors that enable us to develop much more efficient software using AI Agents.</p><h4>Keys to Efficient Software Design</h4><p>Beyond simply using the right tools — such as MCPs, Skills, and Guards — one of the most critical aspects of software design is having the correct specifications for each specific use case. We must go beyond merely providing answers or generating reports. The ultimate goal is to ensure our AI Agent can comprehend requests, access enterprise systems, analyze all available information, execute various operations, and adhere to security policies, authorization protocols, and — of course — the organization’s business logic.</p><p>An AI Agent may excel at interpreting natural language; however, it should not possess unlimited authority to modify machinery, abort a production order, make a high-value purchase, or execute a potentially dangerous operation. The latter point is particularly important and warrants the greatest emphasis — especially in industrial environments where safety must always be the top priority. Consequently, the specifications applied to our design are crucial. Finally, remember that while the AI ​​handles interpretation and coordination, critical rules must be governed by deterministic mechanisms.</p><h4>Designing Effective Skills</h4><p>A common mistake developers make is creating “<em>bloated Skills.</em>” You might be wondering: what exactly is a bloated Skill? Simply put, it is a Skill overloaded with excessive specifications and details. Bloated Skills introduce distractions into the model’s context and tend to encourage extreme abstraction; this makes them costly, as they can consume more tokens than necessary. Keep this in mind! To ensure Skills are effective, the specifications applied to them must be extremely precise — almost surgical in nature. Broadly speaking, a useful rule of thumb is to use “<em>precise keywords and minimalist sentences.</em>” Essentially, a Skill encapsulates the specific knowledge you use repeatedly, ensuring the AI ​​Agent does not forget the instructions provided.</p><p>There is a website where you can download Skills designed for various use cases: <a href="https://www.skills.sh/">Skills.sh</a>.</p><h4>Designing Effective Guards</h4><p>One crucial rule that cannot be overlooked is security — specifically, the various levels of security in the broadest sense. Key aspects include operational assessment, access controls, authorization, process execution, and so on. In other words, the best strategy is to perfectly combine deterministic validations within a solid, clear architectural framework.</p><p>There are several principles for creating efficient Guards. Some critical points include the following:</p><p><strong>Optimizing for Latency and Cost</strong></p><p>This critical point highlights two important aspects. Consider, for instance, a common security risk: exposing sensitive information — such as credit card details, virtual wallet data, or an API key — on a public site. Traditional programming often employs interface validation rules, such as RegEx or similar pipeline-based solutions. However, these offer only a basic level of security and do not prevent all potential security incidents. The worst-case scenario is an LLM (Large Language Model) receiving such sensitive data, as this could lead to malicious or criminal exploitation of resources. Consequently, the golden rule should be: “Code first, LLM second.” To optimize the security model, you should design an architecture that executes Input Guardrails concurrently with the agent’s initial process — using a specific pattern — so that the process can be aborted if any anomaly or threat is detected.</p><p><strong>Preventing Jailbreak Attempts</strong></p><p>One major challenge you may face involves processes known as “<em>jailbreaks</em>” — situations where the system begins to ignore the rules established by the guardrails. This can lead to misinterpretations of processes, generating false positives that might inadvertently block the system. Therefore, mitigating false positives is essential.</p><p><strong>Balancing Rule Flexibility and Rigidity</strong></p><p>When designing your test suites, you must aim for a model that strikes a balance between flexibility and rigidity. A model that is overly strict regarding rules might block certain legitimate operations, flagging them as negative processes when they are not. Conversely, extreme flexibility could render the system entirely vulnerable and dysfunctional. A balance between these two approaches is necessary. Remember: if your code agent blocks basic commands like `git status` or standard Bash commands such as `ls`, the system’s utility would be instantly lost.</p><p>Finally — and importantly — industrial security requires a specialized approach, much like in the medical field. Certain industrial environments demand rigorous security mechanisms that strictly adhere to standard recommendations. In an industrial context, this often applies to operational machinery. Controlling these devices is crucial, as mismanagement of the environment could lead to disastrous consequences. Always keep this in mind!</p><h4>Detailing Our Industrial Use Case Example</h4><p>Below, we describe the architecture of the project we are using as a case study to implement a typical industrial solution.</p><p><strong>Note</strong>:<em> This example has been adapted for educational purposes. Implementing a real-world solution would require expanding, modifying, and refining specific aspects of this design. Covering all those intricacies here would go beyond the scope of this article; I recommend consulting specialized literature to further refine your future industrial designs.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*axhFDVMMPcgpsIvt" /><figcaption>Figure 1 — Typical Industrial Model Architecture.</figcaption></figure><p>Figure 1 outlines the project prototype we are going to analyze. Before diving into the general description, it is necessary to divide this context into two main sections. One section encompasses the processes linked to the AI ​​Agent and its supporting resources — such as the MCP, Skills, and Guards — while the other involves external solutions: an ERP (<em>Enterprise Resource Planning</em>) system used for commercial management, an MES (<em>Manufacturing Execution System</em>) for actual factory floor control, and, finally, the factory’s automation and control system.</p><p>The project’s general model requires integration between these components. For instance, suppose a machine begins to malfunction due to wear in an internal component. The AI ​​Agent detects the issue and notifies the monitoring operators. Additionally, the AI ​​Agent identifies the specific part involved. It then queries the ERP to determine the part’s cost; if granted sufficient external access, it can also search the web for the specific product or spare part to evaluate the costs associated with repairing the machinery.</p><p>As you can see, the AI ​​Agent coordinates all these processes. It then summarizes the information in a report for the operators, enabling them to make an informed decision.</p><p>Note that the final decision is made by company personnel, not the AI ​​Agent. This is a clear example of an implemented deterministic safety rule. Without such a rule, the AI ​​Agent might make its own decisions — potentially causing significant process issues or a negative impact. Indeed, I highlighted this recommended safety practice earlier in the section on Guards.</p><h4>Project Architecture</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*MNnHxon4BuwSCDNh" /><figcaption>Figure 2 — Project Architecture.</figcaption></figure><p>Figure 2 provides a visual overview of how the project is organized within the code. Broadly speaking, there is one section housing the main project and another dedicated to project testing. You can download the project from my IndustrialAI repository to explore and study it on your own machine.</p><h4>Let’s Examine Its Functions</h4><p>We will look at one of the most interesting areas: the “<em>Production</em>” section. Here, we address the industrial “<em>production</em>” process. As you might imagine, the efficient management of a company’s production model is key; therefore, having a set of skills for its governance and control is crucial in this context.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/431/0*PPn6pWVrDrDbVZPK" /><figcaption>Figure 3 — Implemented Skills in Production.</figcaption></figure><p>The SKILL.md file contains a set of basic rules. This file is mandatory and crucial, as it represents the Skill’s conceptual contract. For instance, one of its directives might be: “<em>How much was produced yesterday?</em>” Then there is the instructions.md file, which is primarily used to control the procedure the Skill should follow — in short, how the task is to be performed. In the case of the initial question, this file outlines how to handle it. Finally, the <em>ProductionSkill.cs</em> file houses the code for general processing.</p><p><strong>Note</strong>: <em>In original code the declarations is in Spanish language. However, here I translate for you understand whole process.</em></p><pre># Production Skill<br><br>## Purpose<br>Check production status (MES/SCADA) and assist in creating manufacturing orders.<br><br>## Capabilities<br>- General status of lines and orders<br>- Status of a specific line (L-01, L-02…)<br>- Create/release production order (requires confirmation + Guards)<br><br>## Rules<br>- Do not execute physical changes or irreversible orders without authorization and confirmation.<br>- All write operations pass through GuardEngine first.</pre><p>Note that our SKILL.md is quite simple and indicates the tasks assigned to its process.</p><pre>1. Identify the intent (query vs. write).<br>2. Extract relevant parameters (product, quantity, line).<br>3. Validate that the Guards have already approved the request.<br>4. Call the production MCP client.<br>5. Respond with verifiable, structured data.<br>6. For write actions, request explicit confirmation from the user.</pre><p>Then there is `<em>instructions.md</em>`, which specifies very simply what we need it to do.</p><pre>using IndustrialAI.Domain.DTOs;<br>using IndustrialAI.Domain.Models;<br>using IndustrialAI.MCP;<br><br>namespace IndustrialAI.Skills.Production;<br><br>/// &lt;summary&gt;<br>/// Skill de Producción. Traduce la intención del usuario en llamadas al cliente MCP de producción (MES/SCADA).<br>/// Las instrucciones detalladas viven en SKILL.md e instructions.md.<br>/// &lt;/summary&gt;<br>public sealed class ProductionSkill<br>{<br>    private readonly ProductionMcpClient _mcp;<br><br>    public ProductionSkill(ProductionMcpClient mcp) =&gt; _mcp = mcp;<br><br>    public async Task&lt;ProductionResultDto&gt; ExecuteAsync(string intent, AgentContext context)<br>    {<br>        var text = intent.ToLowerInvariant();<br><br>        // Crear / lanzar orden de producción<br>        if (text.Contains(&quot;crear orden&quot;) || text.Contains(&quot;lanzar orden&quot;) || text.Contains(&quot;iniciar producción&quot;) || text.Contains(&quot;iniciar produccion&quot;))<br>        {<br>            // Ejemplo simplificado de extracción de parámetros (en un sistema real lo haría el LLM)<br>            var product = ExtractAfter(text, &quot;producto&quot;) ?? &quot;PN-440&quot;;<br>            var qty = ExtractInt(text) ?? 100;<br>            var line = ExtractAfter(text, &quot;línea&quot;) ?? ExtractAfter(text, &quot;linea&quot;) ?? &quot;L-01&quot;;<br><br>            var (ok, message, order) = await _mcp.CreateOrderAsync(product, qty, line);<br>            return new ProductionResultDto(ok, message, order?.Id, order?.ProgressPercent);<br>        }<br><br>        // Estado de una línea concreta<br>        if (text.Contains(&quot;línea&quot;) || text.Contains(&quot;linea&quot;))<br>        {<br>            var line = ExtractAfter(text, &quot;línea&quot;) ?? ExtractAfter(text, &quot;linea&quot;) ?? &quot;L-01&quot;;<br>            var status = await _mcp.GetLineStatusAsync(line);<br>            return new ProductionResultDto(true, status);<br>        }<br><br>        // Estado general de producción<br>        var general = await _mcp.GetProductionStatusAsync();<br>        return new ProductionResultDto(true, general);<br>    }<br><br>    private static string? ExtractAfter(string text, string keyword)<br>    {<br>        var idx = text.IndexOf(keyword, StringComparison.OrdinalIgnoreCase);<br>        if (idx &lt; 0) return null;<br>        var rest = text[(idx + keyword.Length)..].Trim();<br>        var token = rest.Split(&#39; &#39;, StringSplitOptions.RemoveEmptyEntries).FirstOrDefault();<br>        return token?.Trim(&#39;,&#39;, &#39;.&#39;, &#39;;&#39;);<br>    }<br><br>    private static int? ExtractInt(string text)<br>    {<br>        var parts = text.Split(&#39; &#39;, StringSplitOptions.RemoveEmptyEntries);<br>        foreach (var p in parts)<br>            if (int.TryParse(p.Trim(&#39;,&#39;, &#39;.&#39;), out var n) &amp;&amp; n &gt; 0) return n;<br>        return null;<br>    }<br>}</pre><p>Finally, we have the class that executes the code along with its corresponding functions. For instance, when we run the query to determine our production output, this class helps us carry out this step. We can see how the Skills operate in coordination with the `<strong>ProductionSkill</strong>` sealed class.</p><p>When we run the program demo, it outputs a series of values ​​simulating industrial execution processes. It is interesting to observe the progress of the steps.</p><pre>╔══════════════════════════════════════════════════════════╗<br>║          IndustrialAI – Architecture Demo                ║<br>║   User → Agent → Skills → Guards → MCP (ERP/MES/…)       ║<br>╚══════════════════════════════════════════════════════════╝<br><br>────────────────────────────────────────────────────────────<br>1. Production inquiry (authenticated operator)<br>Intent : Check production status<br>User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>✅ Skill : Production<br>Msg   : Production (MES/SCADA):<br>Lines:<br>· L-01 (Extrusion Line 01): Operational, 120 units/h<br>· L-02 (Assembly Line 02): Stopped, 80 units/h<br>Active orders:<br>· Order 1001 [PN-440] 435/500 (87%) – Running<br>· Order 1002 [PN-112] 0/200 (0%) – Pending<br><br>────────────────────────────────────────────────────────────<br>2. Inventory inquiry<br>Intent : View inventory stock<br>User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>✅ Skill : Inventory<br>Msg   : Inventory (WMS):<br>· AC-001 (Rolled steel): 420 kg (min 250)<br>· PL-220 (ABS plastic): 85 kg (min 100) ⚠ BELOW MINIMUM<br>· BR-015 (M8 fasteners): 12,000 units (min 5,000)<br><br>────────────────────────────────────────────────────────────<br>3. Specific SKU inquiry (PL-220 below minimum)<br>Intent : Status of SKU PL-220<br>User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>🛑 Skill : None<br>Msg   : No industrial Skill compatible with the intent was found. ────────────────────────────────────────────────────────────<br>4. Maintenance – CMMS status<br>Intent : Maintenance status<br>User   : tech-02 | Role: Technician | Auth: True | Confirmed: False<br><br>✅ Skill : Maintenance<br>Msg   : Maintenance (CMMS):<br>· 2 scheduled preventive orders (L-01, L-03)<br>· 0 active critical alarms<br>· Next planned shutdown: L-02 on 2026-09-25 06:00<br>· Average availability last week: 97.4%<br><br>────────────────────────────────────────────────────────────<br>5. BLOCKED – unauthenticated user<br>Intent : Check production<br>User   : anon | Role: Guest | Auth: False | Confirmed: False<br><br>🛑 Skill : Guards<br>Guard : Authentication<br>Msg   : Blocked: unauthenticated user.<br><br>────────────────────────────────────────────────────────────<br>6. BLOCKED – destructive operation without confirmation<br>Intent : Shut down machine L-01<br>User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>🛑 Skill : Guards<br>Guard : DestructiveOperation<br>Msg   : Blocked: the operation requires explicit confirmation (Confirmed=true).<br><br>────────────────────────────────────────────────────────────<br>7. BLOCKED – purchase without appropriate role<br>Intent : Generate purchase order for AC-001<br>User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>🛑 Skill : Guards<br>Guard : Confirmation<br>Msg   : Blocked: this write action requires explicit confirmation.<br><br>────────────────────────────────────────────────────────────<br>8. Authorized purchase (PurchasingManager + confirmed)<br>Intent : Generate purchase order for PL-220<br>User   : buyer-01 | Role: PurchasingManager | Auth: True | Confirmed: True<br><br>✅ Skill : Purchasing<br>Msg   : Purchase request PR-9208 created: 500 units of PL-220 by buyer-01. Status: Pending approval. ────────────────────────────────────────────────────────────<br>9. Create production order (with confirmation)<br>Intent : Create order for 150 units of product PN-440 on line L-01<br>User   : supervisor-01 | Role: Supervisor | Auth: True | Confirmed: True<br><br>🛑 Skill : Production<br>Msg   : Line L-01 not found.<br><br>────────────────────────────────────────────────────────────<br>10. Authorized destructive operation (Admin + confirmed)<br>Intent : Shut down machine L-02 for maintenance<br>User   : admin-01 | Role: Admin | Auth: True | Confirmed: True<br><br>✅ Skill : Maintenance<br>Msg   : Maintenance (CMMS):<br>· 2 scheduled preventive orders (L-01, L-03)<br>· 0 active critical alarms<br>· Next planned shutdown: L-02 on 2026-09-25 06:00<br>· Average availability over the last week: 97.4%<br><br>────────────────────────────────────────────────────────────<br>Demo complete. Review the blocked vs. authorized scenarios<br>to understand the role of Guards + Skills + MCP.</pre><p>Note that each task being executed is supervised by our agent. Some of these tasks are blocked preventively. The purpose of this action is to prevent automated processes from executing dangerous tasks. Therefore, human supervision is key to better implementing industrial processes.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uFmmOYOk7EqYnI6nqq55hg.png" /><figcaption>Figure 3 — Operations scheme.</figcaption></figure><p>Next, we have the unit tests for the general evaluations.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*QXcxw92iZl4tbUl1" /><figcaption>Figure 4 — Unit Testing to The Generals Process.</figcaption></figure><p>Figure 4 shows the execution of unit tests to verify the program’s overall state through various evaluations and checks. Note how the tasks successfully pass these tests. On the right side of the image, we see the details — specifically for the `ProductionSkillTests` sealed class — as it undergoes the unit testing process required to evaluate its behavior, state, operability, functionality, and so on.</p><h4>Conclusion</h4><p>The architecture spanning the processes [User → Agent → Skills → Guards → MCP] offers a practical way to integrate AI Agents into our projects. It establishes a coherent framework bridging human elements and the machine, ensuring we do not sacrifice control, process traceability, or security.</p><p>By clearly separating responsibilities, each layer fulfills a specific role:</p><ul><li>The AI ​​Agent reasons and orchestrates.</li><li>Skills encapsulate business capabilities (production, maintenance, inventory, purchasing).</li><li>Guards act as mandatory filters for authentication, authorization, machine safety, and the confirmation of critical operations.</li><li>MCP clients connect in a controlled manner to actual plant systems (ERP, MES, SCADA/PLC).</li></ul><p>Each section facilitates a process crucial to the software’s performance. Continuous improvement of these models allows us to refine and optimize all industrialized processes within our program. Enhancements to Skills and Guards, along with the proper use of MCPs, can significantly improve the model’s integration and further perfect it.</p><p>Thus, as this example illustrates, an AI Agent does not necessarily have to do everything. However, it must only act when authorized — under proper authorization overseen by humans — while maintaining a traceability process that records exactly what was executed and why. In short, it is a solution that can be deployed on the factory floor.</p><p>To conclude, if you are building or evaluating AI Agents for production environments, remember this key rule: “Intelligence without guardrails is not automation; it is risk.” Therefore, through an appropriate architecture — very similar to the one we have examined here — AI ceases to be a sort of mysterious “black box” and instead becomes a highly effective collaborator: one that is controlled, auditable, and aligned with the best-practice rules of standardized industrial operations.</p><p>See you soon!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=007c60281100" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Agente IA — Cómo Combinar Agente IA, MCP, Skills y Guards para un Caso Industrial]]></title>
            <link>https://medium.com/@arielwagnermovil/agente-ia-c%C3%B3mo-combinar-agente-ia-mcp-skills-y-guards-para-un-caso-industrial-004244a8f64f?source=rss-10ff0a47ac49------2</link>
            <guid isPermaLink="false">https://medium.com/p/004244a8f64f</guid>
            <category><![CDATA[industrial-design]]></category>
            <category><![CDATA[guard]]></category>
            <category><![CDATA[skills]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[mcps]]></category>
            <dc:creator><![CDATA[Ariel Alejandro Wagner]]></dc:creator>
            <pubDate>Sun, 20 Sep 2026 15:54:29 GMT</pubDate>
            <atom:updated>2026-09-20T15:54:29.945Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TTEp0k59e75HRyl3g34IbQ.jpeg" /></figure><h4>Introducción</h4><p>En anteriores artículos he publicado cómo los Agentes IA hacen uso de diversos tipos de herramientas adicionales para mejorar muy significativamente su trabajo. En esta ocasión, vamos a estudiar detalladamente, desde un caso real en la industria, aquellos diversos puntos importantes que nos permitan crear un desarrollo de software mucho más eficiente, a través de los Agentes IA.</p><h4>Claves para un Diseño Eficiente de Software</h4><p>Una de las claves más importantes para el diseño de software se centra, más allá del uso de las herramientas adecuadas como los MCP, Skills y Guards, es la de contar con las especificaciones correctas para cada caso. Debemos ir más allá de responder simplemente respuestas o generar informes. El hecho más importante es lograr que nuestro Agente IA pueda comprender la solicitud, acceder a sistemas empresariales, analizar toda clase de información disponible, ejecutar diversos tipos de operaciones, respetar las políticas de seguridad, las autorizaciones, y por supuesto, el negocio de una organización.</p><p>Un Agente IA puede ser muy bueno interpretando lenguaje natural. Sin embargo, este no debería tener ningun tipo de autoridad ilimitada para modificar una máquina, abortar una orden productiva, realizar una compra de gran valor o ejecutar una operación potencialmente peligrosa. Particularmente, la última de todas dado que es la que debemos hacer mayor énfasis. Pensemos esto para un ambiente industrial donde la seguridad debe primar siempre. Por tanto, y como podrás ver, las especificaciones que apliquemos a nuestro diseño serán cruciales. Como último detalle recordar que la IA debe interpretar y coordinar mientras que las reglas críticas deben estar controladas por mecanismos determinísticos.</p><h4>Diseño de Skill Eficaces</h4><p>Uno de los errores más comunes de los desarrolladores es la de caer en el uso de “<em>Skills Infladas</em>”. Seguramente te estarás preguntando, y ¿qué es una <em>Skill inflada</em>? Bueno, simplemente puedo decirte que es un tipo de Skill que posee un exceso de carga de especificaciones y detalles. Las Skills infladas producen en el contexto un proceso que genera distracción al modelo, con una tendencia a ser proclive a la abstracción extrema, lo cual todo ello las convierte en costosas debido a que podrían consumir más tokens de lo que se debe. ¡Ten muy en cuenta esto!</p><p>Para poder contar con Skills eficaces, será necesario que las especificaciones que le apliquemos sean muy precisas, practicamente de tipo quirúrjicas. A modo groso podemos adelantar que una regla podría ser la de “<em>palabras claves, precisas y oraciones minimalistas</em>”. Por tanto, una Skill captura todo el conocimiento necesario que utilizas de forma reiterada, a los efectos de que el Agente IA no olvide las indicaciones dadas.</p><p>Existe un sitio Web en el que puedes descargar Skills diseñadas para diversos casos. Aquí te dejo el link <a href="https://www.skills.sh/">Skills.sh</a>.</p><h4>Diseño de Guards Eficaces</h4><p>Una de las reglas más importantes que no podemos pasar por alto es la seguridad, y en particular, los distintos niveles de seguridad en su más amplio sentido. La evaluación de las operaciones, los controles a los accesos, las autorizaciones, las ejecuciones de procesos, y un largo etcétera son algunos de sus puntos críticos. Dicho de otro modo, la mejor estrategia que podemos utilizar es la perfecta combinación de validaciones deterministas dentro de un contexto arquitectónico sólido y claro.</p><p>Existen una serie de llamados principios para hacer que tus Guards sean eficientes. Algunos puntos críticos pueden ser los siguientes.</p><p><strong>Optimización para la Latencia y el Costo</strong></p><p>Este punto crítico hace énfasis en dos aspectos importantes. Por ejemplo, un caso de inseguridad muy frecuente que podría ser el pasar datos sensibles de una tarjeta de crédito, datos de un monedero virtual o tal vez una API key en un sitio público. En la programación clásica se suelen aplicar reglas de validación de interface como por ejemplo un RegEx o algún tipo de solución Pipeline similar. Sin embargo, esto no deja de ser un nivel de seguridad básico que no evita potenciales incidentes de seguridad. Lo peor que podría pasar es que un LLM (<em>Large Language Model</em>) sea receptor de datos sensibles como estos. Esto podría dar lugar a un explotación de los recursos de modo intencionalmente maligno o delictivo. En consecuencia, la regla de oro debiera ser “<em>Primero el Código y luego el LLM</em>”.</p><p>Para eficientizar el modelo de seguridad deberás diseñar una arquitectura que ejecute los <em>Input Guardrail</em> al mismo tiempo que el proceso inicial del agente, a través del uso de algún patrón especial, a los efectos de abortar el proceso en caso de que se detecte algún tipo de anomalía o amenaza.</p><p><strong>Evitando Procesos de Autoexclusión</strong></p><p>Uno de los grandes problemas a los que te puedes enfrentar es a los procesos conocidos como “<em>jailbreaks</em>”. Dicho de otra forma que el sistema pase a ignorar las reglas aplicadas en el <em>guardrail</em>. Esto podría producir una lectura de los procesos generando falsos positivos que podrían indirectamente bloquear al sistema. Por tanto, mitiga los falsos positivos.</p><p><strong>Equilibrio entre Flexibilidad y Rigidez de las Reglas</strong></p><p>El diseño de tus baterías de pruebas deben considerar la implementación de un modelo que se encuentre equilibrado entre la flexibilidad y rigidez. Un modelo excesivamente celoso de las reglas podría ser bloqueante para un cierto grupo de valuaciones que podrían pasar como procesos negativos cuando realmente no lo son. Luego tenemos el otro lado donde la flexibilidad extrema podría resultar ser totalmente vulnerable e infuncional. Es necesario establecer un equilibrio entre ambos procesos. Recuerda: Si tu agente de código bloquea comandos básicos tales como <em>git status</em> o los relacionados con los procesos de Bash tales como <em>ls</em>, etc., la utilidad de tu sistema se perdería de forma inmediata.</p><p>Por último, y no menos importante, la seguridad industrial requiere de un tratamiento muy particular. Así mismo también pasa algo parecido con la medicina. Algunos ambientes industriales requieren de mecanismos de seguridad muy elevados y que cumplan de forma severa las recomendaciones de los estándares. En el caso de la industria podrían ser las maquinarias operativas. El gobierno de estos dispositivos es crucial porque en caso de un mal manejo del entorno podría causar estragos. ¡Recuerda siempre esto!</p><h4>Detallando Nuestro Ejemplo para un Caso Industrial</h4><p>A continuación, vamos a describir nuestra arquitectura de nuestro proyecto de estudio que nos permitirá implementar una típica solución industrial.</p><p>Nota: <em>Este ejemplo está adaptado pedagógicamente para su estudio. En caso de requerir una solución real, habrá que ampliar, cambiar y mejorar algunos puntos particulares en este diseño. Para nuestro caso actual tratar todos estos pormenores escaparían del espacio de este artículo. Para ello te recomiendo que busques lectura especializada de modo de perfeccionar tus futuros diseños industriales.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*7XcjucLTVWFyn0wH" /><figcaption>Figura 1 — Arquitectura de un Típico Modelo Industrial.</figcaption></figure><p>En la figura 1 se describe el prototipo de proyecto que vamos a analizar. Antes de comenzar con la descripción general, resulta necesario separar este contexto en más o menos dos grandes secciones. Una sección es donde se hallan los procesos vinculados al Agente IA y sus recursos satélites como el MCP, las Skills y los Guards, mientras que por el otro lado tenemos otras soluciones externas tales como un ERP (<em>Enterprise Resource Planning</em>) que es utilizado para la gestión comercial de la empresa, el MES (<em>Manufacturing Execution System</em>) que es en efecto el control de la factoría de la fábrica y por último, el sistema de control y automatización de la fábrica.</p><p>El modelo general de este proyecto debe incluir una instrumentación entre las partes señaladas. Por ejemplo, supongamos que una máquina comienza a presentar un problema, un desgaste en una sección interna. El Agente IA detecta que existe un problema y pasa a notificar a los operarios del monitoreo la presencia de un problema. Además, el Agente IA también se encarga de determinar cuál es la pieza que está en juego. A continuación, el Agente IA consulta al ERP para determinar cuánto cuesta la pieza, y si tiene el suficiente permiso de acceso al mundo exterior, puede explorar en la Web en búsqueda del producto o respuesto en particular para evaluar sus costos en caso de ser reparada dicha maquinaria.</p><p>Como podrás apreciar, todos estos procesos son coordinados por el Agente IA. Luego este los sumariza en un reporte para que los operarios tengan toda la información, y finalmente, pasen a tomar una decisión al respecto.</p><p>Observa que la decisión final no la toma el Agente IA sino el personal de la empresa. Aquí tenemos un claro ejemplo de una regla de seguridad determinística implementada. Si esta regla no hubiese sido trazada, es muy probable que el Agente IA tome sus propias decisiones que podrían crear un gran problema al proceso, muy probablemente produciendo un impacto negativo en el mismo. En efecto, este mismo proceso de seguridad recomendada lo señalé en párrafos anteriores en la sección de Guards.</p><h4>Arquitectura del Proyecto</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*RL6CKopryV2f5qs7" /><figcaption>Figura 2 — Arquitectura del Proyecto.</figcaption></figure><p>En la figura 2 tenemos un plano gráfico cómo se organiza nuestro proyecto en el código. Tenemos a grandes rasgos una sección donde se aloja todo el proyecto y en la otra sección el área destinada a las pruebas del proyecto. Puedes descargar este proyecto para explorarlo y estudiarlo en tu propio equipo desde mi repositorio <a href="https://github.com/Ariel-A-W/IndustrialAI">IndustrialAI</a>.</p><h4>Estudiemos Sus Funciones</h4><p>Vamos a estudiar una de las más interesantes que es la sección <em>Production</em>. Aquí estaremos haciendo mención al proceso “<em>productivo</em>” de la industria. Como puedes imaginar, la gestión eficiente de un modelo productivo en un empresa es clave. Por tanto, la presencia de un conjunto de Skills para su gobernanza y control resultan ser cruciales para este contexto.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/431/0*m0hSdUwOeQIg4nAB" /><figcaption>Figura 3 — Skills Implementadas en Production.</figcaption></figure><p>La <a href="http://skill.md/"><em>SKILL.md</em></a> encierra una serie de reglas básicas. Este archivo es obligatorio. Este archivo es muy importante porque representa el contrato conceptual de la Skill. Por ejemplo, una de sus directivas pordía ser; “¿cuánto se produjo ayer?” Luego, contamos con el archivo <a href="http://instructions.md/"><em>instructions.md</em></a> que es utilizado básicamente para controlar el procedimiento que debería seguir la Skill. En breve, es cómo debe hacer la tarea. Para el caso de la pregunta inicial, sería básicamente cómo proceder con la misma. Finalmente, el archivo <em>ProductionSkill.cs</em> es donde tenemos alojado el código para el procesamiento general.</p><pre># Production Skill<br><br>## Propósito<br>Consultar el estado de producción (MES/SCADA) y asistir en la creación de órdenes de fabricación.<br><br>## Capacidades<br>- Estado general de líneas y órdenes<br>- Estado de una línea concreta (L-01, L-02…)<br>- Crear / lanzar orden de producción (requiere confirmación + Guards)<br><br>## Reglas<br>- No ejecutar cambios físicos ni órdenes irreversibles sin autorización y confirmación.<br>- Toda escritura pasa primero por GuardEngine. </pre><p>Observa que nuestra <a href="http://skill.md/">SKILL.md</a> es bastante sencilla e indicativa de las tareas destinadas a su proceso.</p><pre>1. Identificar la intención (consulta vs escritura).<br>2. Extraer parámetros relevantes (producto, cantidad, línea).<br>3. Validar que los Guards ya hayan aprobado la solicitud.<br>4. Llamar al cliente MCP de producción.<br>5. Responder con datos verificables y estructurados.<br>6. Para acciones de escritura solicitar confirmación explícita al usuario.</pre><p>Luego <a href="http://instructions.md/">instructions.md</a> que especifica de forma muy sencilla lo que necesitamos que haga.</p><pre>using IndustrialAI.Domain.DTOs;<br>using IndustrialAI.Domain.Models;<br>using IndustrialAI.MCP;<br><br>namespace IndustrialAI.Skills.Production;<br><br>/// &lt;summary&gt;<br>/// Skill de Producción. Traduce la intención del usuario en llamadas al cliente MCP de producción (MES/SCADA).<br>/// Las instrucciones detalladas viven en SKILL.md e instructions.md.<br>/// &lt;/summary&gt;<br>public sealed class ProductionSkill<br>{<br>    private readonly ProductionMcpClient _mcp;<br><br>    public ProductionSkill(ProductionMcpClient mcp) =&gt; _mcp = mcp;<br><br>    public async Task&lt;ProductionResultDto&gt; ExecuteAsync(string intent, AgentContext context)<br>    {<br>        var text = intent.ToLowerInvariant();<br><br>        // Crear / lanzar orden de producción<br>        if (text.Contains(&quot;crear orden&quot;) || text.Contains(&quot;lanzar orden&quot;) || text.Contains(&quot;iniciar producción&quot;) || text.Contains(&quot;iniciar produccion&quot;))<br>        {<br>            // Ejemplo simplificado de extracción de parámetros (en un sistema real lo haría el LLM)<br>            var product = ExtractAfter(text, &quot;producto&quot;) ?? &quot;PN-440&quot;;<br>            var qty = ExtractInt(text) ?? 100;<br>            var line = ExtractAfter(text, &quot;línea&quot;) ?? ExtractAfter(text, &quot;linea&quot;) ?? &quot;L-01&quot;;<br><br>            var (ok, message, order) = await _mcp.CreateOrderAsync(product, qty, line);<br>            return new ProductionResultDto(ok, message, order?.Id, order?.ProgressPercent);<br>        }<br><br>        // Estado de una línea concreta<br>        if (text.Contains(&quot;línea&quot;) || text.Contains(&quot;linea&quot;))<br>        {<br>            var line = ExtractAfter(text, &quot;línea&quot;) ?? ExtractAfter(text, &quot;linea&quot;) ?? &quot;L-01&quot;;<br>            var status = await _mcp.GetLineStatusAsync(line);<br>            return new ProductionResultDto(true, status);<br>        }<br><br>        // Estado general de producción<br>        var general = await _mcp.GetProductionStatusAsync();<br>        return new ProductionResultDto(true, general);<br>    }<br><br>    private static string? ExtractAfter(string text, string keyword)<br>    {<br>        var idx = text.IndexOf(keyword, StringComparison.OrdinalIgnoreCase);<br>        if (idx &lt; 0) return null;<br>        var rest = text[(idx + keyword.Length)..].Trim();<br>        var token = rest.Split(&#39; &#39;, StringSplitOptions.RemoveEmptyEntries).FirstOrDefault();<br>        return token?.Trim(&#39;,&#39;, &#39;.&#39;, &#39;;&#39;);<br>    }<br><br>    private static int? ExtractInt(string text)<br>    {<br>        var parts = text.Split(&#39; &#39;, StringSplitOptions.RemoveEmptyEntries);<br>        foreach (var p in parts)<br>            if (int.TryParse(p.Trim(&#39;,&#39;, &#39;.&#39;), out var n) &amp;&amp; n &gt; 0) return n;<br>        return null;<br>    }<br>}</pre><p>Finalmente, contamos con nuestra clase que es la que ejecutará el código junto a sus funciones correspondientes. Por ejemplo, cuando ejecutamos la consulta para determinar cuanto hemos producido, esta clase nos ayudar a concretar este paso. Vemos como las Skills operan en coordinación con la clase sellada ProductionSkill.</p><p>Cuando ejecutamos nuestra Demo del programa, nos arroja una serie de valores que simulan los procesos de ejecución industrial. Resulta interesante ver el progreso de los pasos.</p><pre>╔══════════════════════════════════════════════════════════╗<br>║          IndustrialAI – Demo de arquitectura             ║<br>║   Usuario → Agent → Skills → Guards → MCP (ERP/MES/…)    ║<br>╚══════════════════════════════════════════════════════════╝<br><br>────────────────────────────────────────────────────────────<br>1. Consulta de producción (operador autenticado)<br>   Intent : Consultar estado de producción<br>   User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>   ✅ Skill : Production<br>   Msg   : Producción (MES/SCADA):<br>Líneas:<br>  · L-01 (Línea Extrusión 01): Operativa, 120 u/h<br>  · L-02 (Línea Ensamble 02): Detenida, 80 u/h<br>Órdenes activas:<br>  · Orden 1001 [PN-440] 435/500 (87%) – Running<br>  · Orden 1002 [PN-112] 0/200 (0%) – Pending<br><br>────────────────────────────────────────────────────────────<br>2. Consulta de inventario<br>   Intent : Ver stock de inventario<br>   User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>   ✅ Skill : Inventory<br>   Msg   : Inventario (WMS):<br>  · AC-001 (Acero laminado): 420 kg (mín 250)<br>  · PL-220 (Plástico ABS): 85 kg (mín 100) ⚠ BAJO MÍNIMO<br>  · BR-015 (Tornillería M8): 12000 un (mín 5000)<br><br>────────────────────────────────────────────────────────────<br>3. Consulta de un SKU concreto (PL-220 bajo mínimo)<br>   Intent : Estado del SKU PL-220<br>   User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>   🛑 Skill : None<br>   Msg   : No se encontró un Skill industrial compatible con la intención.<br><br>────────────────────────────────────────────────────────────<br>4. Mantenimiento – estado CMMS<br>   Intent : Estado de mantenimiento<br>   User   : tech-02 | Role: Technician | Auth: True | Confirmed: False<br><br>   ✅ Skill : Maintenance<br>   Msg   : Mantenimiento (CMMS):<br>  · 2 órdenes preventivas programadas (L-01, L-03)<br>  · 0 alarmas críticas activas<br>  · Próximo paro planificado: L-02 el 2026-09-25 06:00<br>  · Disponibilidad promedio última semana: 97.4%<br><br>────────────────────────────────────────────────────────────<br>5. BLOQUEADO – usuario no autenticado<br>   Intent : Consultar producción<br>   User   : anon | Role: Guest | Auth: False | Confirmed: False<br><br>   🛑 Skill : Guards<br>   Guard : Authentication<br>   Msg   : Bloqueado: usuario no autenticado.<br><br>────────────────────────────────────────────────────────────<br>6. BLOQUEADO – operación destructiva sin confirmación<br>   Intent : Apagar máquina L-01<br>   User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>   🛑 Skill : Guards<br>   Guard : DestructiveOperation<br>   Msg   : Bloqueado: la operación requiere confirmación explícita (Confirmed=true).<br><br>────────────────────────────────────────────────────────────<br>7. BLOQUEADO – compra sin rol adecuado<br>   Intent : Generar pedido de compra de AC-001<br>   User   : operator-01 | Role: Operator | Auth: True | Confirmed: False<br><br>   🛑 Skill : Guards<br>   Guard : Confirmation<br>   Msg   : Bloqueado: esta acción de escritura requiere confirmación explícita.<br><br>────────────────────────────────────────────────────────────<br>8. Compra autorizada (PurchasingManager + confirmada)<br>   Intent : Generar pedido de compra de PL-220<br>   User   : buyer-01 | Role: PurchasingManager | Auth: True | Confirmed: True<br><br>   ✅ Skill : Purchasing<br>   Msg   : Solicitud de compra PR-9208 creada: 500 uds de PL-220 por buyer-01. Estado: Pendiente de aprobación.<br><br>────────────────────────────────────────────────────────────<br>9. Crear orden de producción (con confirmación)<br>   Intent : Crear orden de 150 unidades producto PN-440 en línea L-01<br>   User   : supervisor-01 | Role: Supervisor | Auth: True | Confirmed: True<br><br>   🛑 Skill : Production<br>   Msg   : Línea l-01 no encontrada.<br><br>────────────────────────────────────────────────────────────<br>10. Operación destructiva autorizada (Admin + confirmada)<br>   Intent : Apagar máquina L-02 por mantenimiento<br>   User   : admin-01 | Role: Admin | Auth: True | Confirmed: True<br><br>   ✅ Skill : Maintenance<br>   Msg   : Mantenimiento (CMMS):<br>  · 2 órdenes preventivas programadas (L-01, L-03)<br>  · 0 alarmas críticas activas<br>  · Próximo paro planificado: L-02 el 2026-09-25 06:00<br>  · Disponibilidad promedio última semana: 97.4%<br><br>────────────────────────────────────────────────────────────<br>Demo finalizada. Revisa los escenarios bloqueados vs autorizados<br>para entender el papel de Guards + Skills + MCP</pre><p>Observa que cada una de las tareas que se van ejecutando son supervisadas por nuestro agente. Algunas de esas tareas son bloqueadas preventivamente. Esta acción tiene como objeto evitar que los procesos automatizados puedan ejecutar tareas peligrosas. Por tanto, la supervisión humana es clave para instrumentar mejor los procesos industriales.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/645/0*la4tqYPtFjLMKgef" /><figcaption>Figura 3 — Escenario de operaciones.</figcaption></figure><p>Luego contamos con las pruebas unitarias para las evaluaciones generales.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*X96P7eFA9-iGAuQN" /><figcaption>Figura 4 — Unit Test para los Procesos Generales.</figcaption></figure><p>En la figura 4 vemos la ejecución de los Unit Testing para la verificación de nuestro estado del programa en general a través de las evaluaciones y pruebas. Observa cómo las tareas son superadas en las pruebas. A la derecha de la imagen vemos el detalle, particularmente de nuestra clase sellada ProductionSkillTests, que es sometida al proceso las pruebas unitarias necesarias para evaluar su comportamiento, estado, operatividad, funcionalidad, etc.</p><h4>Conclusión</h4><p>La arquitenctura que recorre los procesos [Usuario → Agent → Skills → Guards → MCP] es una forma práctica de anexar a nuestros proyectos Agentes IA, estableciendo un marco coherente entre los aspectos humanos y la máquina, donde no renunciamos al control, ni a la trazabilidad de los procesos y ni tan siquiera a la seguridad.</p><p>Al separar claramente las responsabilidades, cada capa cumple un rol concreto:</p><ul><li>El Agente IA razona y orquesta.</li><li>Los Skills encapsulan capacidades de negocio (<em>producción, mantenimiento, inventario, compras</em>).</li><li>Los Guards actúan como filtro obligatorio de autenticación, autorización, seguridad de máquina y confirmación de operaciones críticas.</li><li>Los clientes MCP conectan de forma controlada con los sistemas reales de planta (ERP, MES, SCADA/PLC).</li></ul><p>Cada sección instrumenta un proceso crucial en el desempeño del software. La mejora permanente en esta clase de modelos nos permite refinar y optimizar todos los procesos industrializados en el contexto de nuestro programa. Las mejoras en las Skills, en los Guards y el uso mejor y adecuado de los MCP, pueden mejorar muy significativamente la integración del modelo y perfeccionarlo aún más.</p><p>Por tanto, como podemos apreciar en este heterodino ejemplo, un Agente IA no necesariamente debe hacerlo todo. Sin embargo, si necesita hacerlo tan solo cuando está autorizado, bajo una adecuada autorización supervisada previamente por el orden humano, dejando entre medio un proceso de traza donde se especifica qué se ejecutó y por qué se hizo esto. En breve, es una solución que puede ser trasladada en la planta.</p><p>Para cerrar, si estás construyendo o evaluando Agentes IA para entornos productivos, recuerda esta regla inicial clave. “<em>La inteligencia sin gaurdrails no es automatización, es riesgo.</em>” Por lo tanto, a través de una apropiada arquitectura, muy similar a la que hemos estudiado aquí, la IA deja de ser una suerte de caja negra misteriosa y se convierte directamente en un gran colaborador óptimo, controlado, auditable y alineado con las reglas de la operación industrial estandarizada más recomendada.</p><p>¡Hasta pronto!</p><p>Ariel</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=004244a8f64f" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>