Creación de un plan técnico detallado

Completado

Una especificación define lo que necesita construir. Un plan técnico define cómo construirlo. En esta unidad se tratan técnicas de planeación avanzadas para escenarios de campo marrón empresarial.

Revisar los aspectos básicos del plan

El archivo plan.md actúa como documento de diseño, tendiendo el puente entre los requisitos de alto nivel en spec.md y las tareas de implementación concretas siguientes. Un plan técnico completo contiene:

• Información general sobre la arquitectura: vista general de cómo interactúan los componentes.
• Pila tecnológica y decisiones clave: documentación explícita de las opciones tecnológicas con razones.
• Secuencia de implementación: progresión lógica de los pasos de implementación.
• Comprobación de la Constitución: compruebe explícitamente que las soluciones propuestas cumplen los principios del proyecto.
• Suposiciones y preguntas abiertas: documentación de suposiciones y preguntas sin resolver.

Teniendo en cuenta estos aspectos básicos, vamos a explorar las consideraciones de planeación avanzadas para el desarrollo empresarial.

Separación de preocupaciones: especificación frente a plan

La separación de preocupaciones entre la especificación y el plan técnico es fundamental. Aunque la especificación permanece estable y centrada en "qué", el plan puede evolucionar a medida que experimenta con diferentes enfoques de "cómo".

Supongamos que la especificación requiere una característica de carga de documentos para un portal de empleados interno. La especificación define los requisitos de usuario: límites de tamaño de archivo, formatos admitidos, comentarios de carga y controles de acceso. El plan técnico convierte estos requisitos en decisiones arquitectónicas concretas: qué servicio de almacenamiento de Azure se va a usar, cómo estructurar la API, qué mecanismo de autenticación implementar y cómo validar archivos. Si decide cambiar de una tecnología a otra, como pasar de Azure Blob Storage a Azure Files, actualice plan.md mientras spec.md permanece en gran medida sin cambios. No se cambian los requisitos de características; solo se cambia el enfoque de implementación.

Examen de la estructura y el contenido del plan

Un plan técnico completo contiene varias secciones clave que definen colectivamente el enfoque de implementación.

Introducción a la arquitectura

La información general de la arquitectura proporciona una vista general de cómo interactúan los componentes. Para la característica de carga de documentos, la arquitectura podría describir lo siguiente:

Implemente un nuevo punto de conexión de API de back-end /api/documents/upload para gestionar las cargas de archivos de varias partes. El front-end de React incluye un nuevo componente DocumentUpload con un selector de archivos y un indicador de progreso. Cuando un usuario selecciona un archivo, el front-end valida el tamaño y el tipo antes de cargarlos. El back-end recibe el archivo, se valida de nuevo, lo almacena en Azure Blob Storage y registra los metadatos en la base de datos SQL. Después de la carga correcta, el front-end actualiza la lista de documentos para mostrar el nuevo archivo".

Este resumen establece el flujo general sin profundizar en los detalles de nivel de código. Garantiza que todos comprendan los componentes principales y sus interacciones.

Pila tecnológica y decisiones clave

El plan documenta explícitamente las opciones y las razones de la tecnología. En esta sección se evita la confusión futura sobre por qué se seleccionaron bibliotecas o servicios específicos.

Decisiones tecnológicas de ejemplo:

• Back-end: API web de .NET 8 con el SDK de Azure.Storage.Blobs v12 para las operaciones de blobs.
• Front-end: React 18 con el componente Upload de Ant Design para la coherencia de la interfaz de usuario.
• Autenticación: Usa el token de ID de Microsoft Entra existente desde el contexto de autenticación del portal.
• Storage: contenedor de Azure Blob Storage denominado employee-documents.
• Base de datos: amplíe la base de datos SQL existente con una tabla DocumentMetadata (columnas: Id, UserId, FileName, BlobUrl, UploadDate, FileSize).

Cada decisión debe alinearse con los requisitos de especificación y los principios de constitución. Si su constitución exige "Usar servicios de Azure para todos los recursos en la nube", el plan selecciona explícitamente Azure Blob Storage y hace referencia a este principio.

Secuencia de implementación

El plan describe el orden de los pasos de implementación. Aunque no es tan granular como la lista de tareas generada más adelante, esta secuencia proporciona una progresión lógica de la configuración a la finalización.

Una secuencia de implementación típica para la característica de carga de documentos:

1. Actualización del esquema de base de datos: cree una tabla DocumentMetadata con índices y restricciones adecuados.
2. Desarrollo de API de back-end: implemente POST /api/documents/upload endpoint con validación de archivos, integración de Blob Storage y persistencia de metadatos.
3. Creación de componentes front-end: compile el componente DocumentUpload con selección de archivos, validación del lado cliente y visualización del progreso de carga.
4. Integración: conecte el componente front-end a la API de back-end, controle las respuestas y actualice la lista de documentos.
5. Reforzamiento de seguridad: implemente la validación del tipo de archivo, los límites de tamaño y las comprobaciones de autenticación del lado del servidor.
6. Control de errores: agregue mensajes de error completos para errores de cliente y servidor.
7. Pruebas: cree pruebas unitarias para métodos de API y pruebas de integración para el flujo de carga.

Esta secuencia garantiza que existan elementos fundamentales (esquema de base de datos) antes de implementar componentes dependientes (API que escriben en la base de datos). Cada paso se basa en el trabajo anterior, lo que reduce la probabilidad de problemas de integración.

Verificación de la Constitución

El plan incluye una sección de verificación que comprueba explícitamente las soluciones propuestas contra la constitución. Esta comprobación evita el desfase arquitectónico y garantiza la coherencia con los principios del proyecto.

Si la constitución incluye "Todo el almacenamiento de datos debe usar servicios de Azure" y "Las API deben validar las entradas en el cliente y en el servidor", la sección de comprobación del plan confirma:

• "El uso de Azure Blob Storage satisface el requisito de los servicios de Azure".
• "La implementación de la validación en el componente react (cliente) y la API de .NET (servidor) se alinean con el principio de seguridad de defensa en profundidad".
• "El requisito de autenticación de Microsoft Entra ID se cumple mediante el contexto de autenticación del portal existente".

Esta comprobación sirve como punto de control. Si el plan propone algo que infringe la constitución, la inteligencia artificial lo marca normalmente o observa durante la revisión. Abordar los conflictos de estructura en la fase de planificación evita rehacer el trabajo más adelante.

Suposiciones y preguntas abiertas

Los planes bien elaborados documentan suposiciones y preguntas sin resolver. Esta transparencia le ayuda a identificar posibles problemas antes de que comience la implementación.

Suposiciones de ejemplo:

• "Supongamos que el contenedor de Azure Blob Storage "employee-documents" existe y está configurado para el acceso privado".
• "Supongamos que la base de datos SQL existente tiene suficiente capacidad de almacenamiento para los metadatos".
• "Supongamos que el examen de virus de los archivos cargados está fuera del ámbito de esta iteración".

Preguntas abiertas de ejemplo:

• "¿Los administradores deben tener la capacidad de eliminar los documentos cargados de otros usuarios?"
• "¿Necesitamos el registro de auditoría para todos los intentos de acceso a documentos?"
• "¿Debe el sistema enviar notificaciones por correo electrónico cuando se carguen documentos?"

La documentación de estas suposiciones y preguntas previene la desviación del alcance y garantiza que las partes interesadas aborden decisiones importantes antes de comenzar la programación. Si una suposición demuestra que es incorrecta durante la implementación, puede actualizar el plan en consecuencia.

Generación de un plan mediante /speckit.plan

GitHub Spec Kit genera planes mediante el /speckit.plan comando en GitHub Copilot Chat. Este comando usa tanto spec.md como constitution.md como entradas para generar un diseño técnico completo.

Antes de invocar el comando, tenga en cuenta qué otro contexto necesita la inteligencia artificial. El código base, las preferencias tecnológicas y las restricciones de infraestructura existentes influyen en el plan. Proporcionar este contexto inicialmente genera resultados más precisos y accionables.

En el caso de la característica de carga de documentos en un escenario interno del portal de empleados, puede proporcionar contexto similar al siguiente:

"El portal existente usa un front-end de React con un back-end de API web de .NET 8. Es necesario integrar la funcionalidad de subida en este conjunto tecnológico. Use Azure Blob Storage para la persistencia de archivos. Requerir autenticación de Id. de Microsoft Entra para todas las operaciones de carga. El portal ya tiene una base de datos SQL disponible para el almacenamiento de metadatos".

Este contexto instruye a la IA para que genere un plan que se adapte perfectamente a la arquitectura existente, en lugar de proponer una solución desde cero que no se alinee con la pila actual.

Invocación del comando de planeación

Abra Chat de Copilot en GitHub en Visual Studio Code y escriba /speckit.plan. Si la inteligencia artificial solicita más información, proporcione el contexto arquitectónico. GitHub Copilot procesa la especificación, la estructura y el contexto adicional para generar plan.md.

La fase de planeación podría tomar un momento, ya que la inteligencia artificial considera varios enfoques, los comprueba con su constitución y estructura el resultado en un documento de diseño coherente.

Revisión y validación del plan

La generación de un plan es solo el primer paso. La revisión crítica garantiza que el plan sea preciso, completo y alineado con las necesidades del proyecto.

Comprobación de la cobertura de los requisitos de especificación

Compare el plan con spec.md sistemáticamente. Todos los requisitos de la especificación deben asignarse a un enfoque de implementación en el plan.

Por ejemplo, si spec.md requiere "Mostrar un mensaje de error para archivos que superen los 50 MB", el plan debe describir dónde y cómo se produce esta validación. Si el plan omite esta validación, el plan está incompleto o la especificación necesita aclaración.

Comprobación de la alineación con los estándares técnicos

Asegúrese de que las opciones tecnológicas del plan se alinean con los estándares y procedimientos recomendados de su organización. Si el equipo normaliza las bibliotecas o patrones específicos, el plan debe reflejar estas preferencias.

Preguntas que se deben tener en cuenta:

• ¿La arquitectura propuesta se ajusta a los sistemas existentes?
• ¿Están aprobadas las bibliotecas seleccionadas para su uso en su entorno?
• ¿Las opciones tecnológicas cumplen con las directivas de seguridad y cumplimiento de la organización?
• ¿Hay patrones establecidos para una funcionalidad similar que se debe seguir?

Para la característica de carga de documentos en un entorno de Azure, compruebe que Azure Blob Storage es un servicio aprobado, que el enfoque de autenticación se alinea con los estándares de identidad de empresa (como el uso de Microsoft Entra ID) y que el esquema SQL propuesto sigue las convenciones de nomenclatura de la base de datos.

Validar el cumplimiento de la constitución

El plan debe incluir verificación explícita que las soluciones propuestas cumplan los requisitos de constitución. Revise esta sección de verificación cuidadosamente para asegurarse de que no se infringe ningún principio.

Si la constitución requiere "Todos los secretos deben almacenarse en Azure Key Vault" y el plan propone almacenar cadenas de conexión de Azure Storage en appsettings.json, existe un conflicto. El plan debe revisarse para recuperar cadenas de conexión de Key Vault en tiempo de ejecución.

Las violaciones de la constitución detectadas durante la planificación son fáciles de corregir. Las infracciones de constitución detectadas durante la revisión de código o la implementación de producción son costosas y perjudiciales.

Iteración y refinación del plan

Los planes suelen requerir refinamiento después de la generación inicial. No esperes perfección en el primer intento. Use las funcionalidades de aclaración de GitHub Copilot para mejorar la calidad del plan.

Abordar ambigüedades y brechas

Si el plan contiene instrucciones vagas como "implementar el control de errores adecuado", presione para obtener detalles. ¿Qué errores pueden producirse? ¿Cómo se debe controlar cada error? ¿Qué información de error se debe registrar frente a mostrarla a los usuarios?

Use GitHub Copilot Chat para formular preguntas de seguimiento: "¿Qué errores específicos debe manejar el punto de conexión de carga?" o "¿Qué debe suceder si Azure Blob Storage no está disponible?" La inteligencia artificial puede transformar secciones vagas en especificaciones concretas.

Validación de la viabilidad técnica

Compruebe que la arquitectura propuesta es técnicamente factible dadas las restricciones. Si el plan propone cargar archivos de 50 MB de forma sincrónica a través de una API web con un tiempo de espera de 30 segundos, existe un problema. Los archivos que tienen más de 50 MB pueden requerir cargas fragmentadas o mayores tiempos de espera.

Consulte con los miembros del equipo que tengan experiencia relevante. Si el plan propone cambios en el esquema de la base de datos, revise con un administrador de bases de datos. Si requiere nuevos recursos de Azure, compruebe con los ingenieros de infraestructura que el aprovisionamiento es posible.

Considere los requisitos no funcionales

Asegúrese de que el plan aborda los requisitos no funcionales de la especificación: rendimiento, seguridad, escalabilidad, mantenimiento, accesibilidad.

Para la carga de documentos, confirme que el plan incluye:

• Rendimiento: ¿Con qué rapidez debe completarse una carga? ¿Cuál es el volumen máximo de carga simultánea?
• Seguridad: ¿Cómo se examinan los archivos para malware? ¿Cómo se controla el acceso? ¿Dónde se almacenan los registros de auditoría?
• Escalabilidad: ¿Cómo controla el sistema el aumento del volumen de carga? ¿Qué son los límites de capacidad de almacenamiento?
• Mantenimiento: ¿Cómo se limpian los archivos cargados cuando los empleados abandonan la organización?
• Accesibilidad: ¿La interfaz de usuario de carga cumple los estándares de accesibilidad de contenido web (WCAG) 2.1 AA?

Si el plan omite cualquiera de estas consideraciones, agréguelos explícitamente. Los requisitos no funcionales frecuentemente se dejan para reflexionar después durante la fase de implementación si no se abordan en la planificación.

Evaluación de la viabilidad y la integridad

Evalúe si el plan proporciona instrucciones suficientes para la implementación. Los planes demasiado imprecisos ("Implementar subida de archivos") no son útiles. Los planes que son demasiado prescriptivos ("Usar exactamente 47 líneas de código") están demasiado restringidos.

El nivel de detalle correcto proporciona una dirección clara sin eliminar toda la flexibilidad. El plan debe responder:

• ¿Qué componentes deben crearse o modificarse?
• ¿Cómo interactúan estos componentes?
• ¿Qué tecnologías y bibliotecas se usan?
• ¿Cuál es el orden de implementación?
• ¿Qué pasos de comprobación garantizan la corrección?

Si no puede prever cómo implementar la característica desde el plan, necesita más detalles. Si el plan se siente como si estuviera escribiendo el código automáticamente, podría ser demasiado detallado.

Identificación de elementos que faltan

Busque brechas en el plan. Entre las omisiones comunes se incluyen:

• Control de errores: ¿Cómo controla el sistema los errores de red, los errores de almacenamiento o los problemas de la base de datos?
• Consideraciones de rendimiento: ¿Hay alguna preocupación sobre la velocidad de carga, los usuarios simultáneos o los límites de almacenamiento?
• Estrategia de pruebas: ¿Qué pruebas deben escribirse para validar la implementación?
• Enfoque de reversión: si la implementación produce problemas, ¿cómo revierte los cambios?

Solucione estas brechas editando manualmente plan.md o proporcionando más contexto y regenerando secciones pertinentes.

Regenerar contexto refinado

Si el plan inicial falla, aporte un contexto más específico y vuelva a generarlo. Por ejemplo, si el plan sugiere usar una nueva base de datos, pero necesita usar una existente, aclare: "Use la base de datos EmployeePortal existente. Agregue una tabla DocumentMetadata a esta base de datos en lugar de crear una nueva".

Vuelva a generar el plan con /speckit.plan incorporando este contexto actualizado. La inteligencia artificial ajusta el enfoque en consecuencia.

Editar manualmente el plan

Dado que plan.md es un archivo Markdown, puede editarlo directamente. Si la inteligencia artificial sugiere un enfoque que es 90% correcto, pero necesita ajustes menores, edite el archivo en lugar de regenerar todo.

Por ejemplo, si el plan propone un nombre de contenedor de blobs específico, pero su organización tiene convenciones de nomenclatura, actualice el nombre del contenedor en plan.md directamente.

Colaboración con miembros del equipo

En entornos de equipo, comparta plan.md para su revisión. Un desarrollador o arquitecto sénior puede validar las decisiones de arquitectura antes de que comience la implementación. Esta revisión por pares detecta problemas que podrían pasarse por alto en las comprobaciones automatizadas.

La revisión del equipo también crea conocimientos compartidos. Cuando varios desarrolladores trabajan en una característica, revisar el plan juntos garantiza que todos conozcan el enfoque y puedan identificar posibles conflictos con otro trabajo en curso.

Decisiones de arquitectura de documentos

Los planes no solo deben documentar lo que va a crear, sino por qué ha tomado decisiones de arquitectura específicas para ayudar a los futuros desarrolladores a comprender el contexto de decisión.

Alternativas de registro consideradas

Al elegir entre varios enfoques viables, documente las alternativas que ha considerado y por qué seleccionó una sobre otras.

En el caso del almacenamiento de archivos, puede considerar tres enfoques:

• Azure Blob Storage: seleccionado para la rentabilidad, la escalabilidad y la integración con el entorno de Azure existente.
• Azure Files: se rechaza debido a un mayor costo para el almacenamiento de archivos grande y la sobrecarga innecesaria del protocolo bloque de mensajes del servidor (SMB).
• FILESTREAM de SQL Database: rechazado para evitar aumentar el tamaño y la complejidad de la base de datos.

Esta documentación impide que los desarrolladores futuros consulten por qué no se usaron enfoques más sencillos. La justificación de la decisión se conserva en lugar de perderse con el paso del tiempo.

Capturar suposiciones

Los planes hacen suposiciones sobre los sistemas, la infraestructura y las restricciones organizativas existentes. Haga que estas suposiciones sean explícitas.

Suposiciones de ejemplo para la carga de documentos:

• El equipo de infraestructura aprovisiona el contenedor employee-documents de Azure Blob Storage antes de que comience el desarrollo.
• La autenticación del portal existente proporciona tokens de identificación de Microsoft Entra validados que son confiables para la identificación del usuario.
• SQL Database tiene capacidad suficiente para otra tabla de metadatos sin necesidad de expansión de almacenamiento.
• La infraestructura de red admite cargas HTTP de 50 MB sin restricciones de proxy o firewall.

Si alguna suposición resulta incorrecta durante la implementación, puede volver a visitar el plan y ajustarlo en consecuencia. Las suposiciones documentadas hacen que el análisis de impacto sea sencillo cuando cambian las circunstancias.

Planear la evolución futura

Tenga en cuenta cómo la característica puede evolucionar y asegurarse de que la arquitectura se adapte a las extensiones probables.

En el caso de la carga de documentos, los posibles requisitos futuros pueden incluir:

• Compatibilidad con otros tipos de archivo más allá de PDF y DOCX.
• Implementación del uso compartido de archivos entre empleados.
• Agregar control de versiones de documentos.
• Habilitación de cargas masivas de varios archivos.
• Integración del examen de virus

Si la arquitectura dificulta estas extensiones, considere si se garantiza el ajuste del diseño inicial. No implementa ahora funcionalidades futuras, sino que evita llegar a situaciones que harán que los próximos cambios sean perjudiciales.

Compartir y mantener el plan durante la implementación

El plan se convierte en la referencia a lo largo de la implementación. Los desarrolladores deben consultar el plan con regularidad para asegurarse de que su código se alinea con la arquitectura documentada.

Compartir el plan con las partes interesadas

Después de finalizar el plan, compártalo con las partes interesadas pertinentes para la validación:

• Administradores de productos: compruebe que el plan ofrece todos los requisitos de especificación.
• Equipo de seguridad: confirme que los controles de seguridad cumplen los estándares de la organización.
• Equipo de infraestructura: asegúrese de que los recursos propuestos de Azure se pueden aprovisionar y configurar.
• Equipo de arquitectura: valide la alineación con los principios de arquitectura de la organización.

Esta revisión de las partes interesadas detecta problemas antes de que comience la implementación. Si los comentarios del equipo de seguridad revelan que la autenticación propuesta no es suficiente, actualice el plan antes de escribir código.

Actualizar el plan según sea necesario

Los planes son documentos vivos. Cuando detecta durante la implementación que un enfoque no funciona según lo previsto, actualice el plan para reflejar el nuevo enfoque.

Si planea almacenar el progreso de la carga en el explorador localStorage, pero detecta estos problemas en el modo de exploración privada, actualice el plan para usar el estado en memoria en su lugar. Documente por qué se necesita el cambio para que se conserve el razonamiento.

Mantenga plan.md sincronizado con la implementación real. Cuando el plan y el código difieren, el plan pierde el valor como documentación de referencia.

• ¿Los enfoques de seguridad cumplen los requisitos de la organización?
• ¿El diseño del esquema de base de datos sigue las convenciones de nomenclatura?

Si el plan sugiere el uso de una base de datos, pero su portal existente ya tiene una, es probable que sea innecesario. Si el plan propone una tecnología que su equipo suele evitar, documente el motivo o ajuste el plan.

Problemas comunes de planificación para evitar

Evite estos errores comunes al crear y revisar planes:

• Omitir la fase de planificación: saltar directamente de la especificación al código sin un plan aumenta el riesgo de errores arquitectónicos. El tiempo invertido en la planificación paga dividendos evitando el retrabajo.

• Aceptación de planes sin revisión: los planes generados por ia son puntos de partida, no diseños finales. Revise siempre de forma crítica y compruebe en su contexto específico.

• Implementación excesivamente restringida: los planes deben guiar, no dictar cada detalle. Deje espacio para que los desarrolladores tomen las decisiones tácticas adecuadas durante la implementación.

• Ignorar los conflictos de constitución: si el plan infringe los principios de constitución, solucione el conflicto inmediatamente. Ajuste el plan para cumplir o actualizar la constitución si el principio necesita revisión.

• Olvidando actualizar planes: cuando la implementación revela información nueva, actualice plan.md. Los planes desactualizados pueden confundir a los siguientes desarrolladores y reducir la utilidad de su documentación.

Resumen

El plan técnico transforma la especificación en una arquitectura accionable. Genere planes mediante /speckit.plan con el contexto adecuado sobre la pila de tecnología y la infraestructura. Revise los planes de forma crítica para asegurarse de que cubren todos los requisitos de especificación, alinearse con su constitución y proporcionar una guía de implementación suficiente. Use el plan validado para guiar la generación e implementación de tareas. Trate plan.md como un documento vivo que evoluciona con su comprensión y proporciona un contexto valioso para todo el ciclo de vida de desarrollo.