Puntos de partida reutilizables, sin burocracia adicional
Estas plantillas ilustran una forma coherente de registrar decisiones y resultados importantes en el marco SHAPE. Son deliberadamente breves. Los equipos deben adaptarlas a la complejidad del producto y la política empresarial en lugar de rellenar todos los encabezados con texto repetitivo.
El marco no prescribe un conjunto fijo de documentos Markdown con nombres determinados en agent_instructions/. Los ejemplos siguientes muestran posibles artefactos y sus responsabilidades. Las especificaciones de funcionalidades permanecen separadas de las instrucciones permanentes.
Plantilla A. `AGENTS.md` raíz
Un punto de entrada raíz debe cumplir una única función: dirigir al agente de programación a los documentos de instrucciones permanentes del proyecto. No debe requerir mantener una lista de nombres de archivo individuales.
# AGENTS.md
Lea y respete todos los archivos Markdown (`.md`) de `agent_instructions/` antes de comenzar el trabajo y durante toda la implementación.
El archivo raíz puede seguir siendo así de simple aunque los proyectos añadan más instrucciones permanentes.
Plantilla B. Documento de instrucciones que explica su propósito
Todo archivo Markdown dentro de agent_instructions/ debe comenzar declarando qué abarca. Este ejemplo es deliberadamente genérico; su nombre de archivo no es obligatorio.
# [Propósito: explique qué rige este documento de instrucciones]
## Aplicabilidad
- [Qué proyecto o actividad abarcan estas instrucciones]
## Reglas
- [Regla obligatoria y aplicable]
- [Otra regla, si es necesaria]
## Aprobación o escalado
- [Qué decisiones requieren la aprobación del responsable]
## Contexto relacionado
- [Referencias opcionales a otros materiales autorizados]
Esta plantilla puede servir para objetivos del proyecto, restricciones arquitectónicas, orientación de diseño, dependencias aprobadas u otro tema. No combine cuestiones sin relación simplemente porque todas estén escritas en Markdown. Siga las reglas de aprobación de documentos de la organización.
Plantilla C. Objetivos del proyecto
Un documento de objetivos del proyecto explica por qué existe el producto y qué debe lograr. El proyecto puede elegir su ubicación y nombre como parte de su contexto permanente.
# Objetivos y alcance del producto [Nombre del producto]
## Problema
[¿Qué problema existe actualmente y para quién?]
## Resultados previstos
- [Resultado observable]
- [Otro resultado, si corresponde]
## Usuarios y partes interesadas
- [Actor o parte interesada y su interés]
## Alcance inicial
- [Capacidad incluida]
## Exclusiones
- [Capacidad explícitamente excluida]
## Restricciones y dependencias
- [Políticas, sistemas, limitaciones o aprobaciones existentes]
## Decisiones empresariales pendientes
- [Pregunta, responsable de la decisión y estado actual]
Plantilla D. Especificación de funcionalidad
Guarde las especificaciones de funcionalidades en el área specs/ del proyecto. Utilice un identificador estable y mantenga actualizado el documento a medida que evolucione el comportamiento.
# SPEC-[ID]: [Nombre de la funcionalidad]
## Propósito
[Resultado para el usuario o el negocio y por qué existe la funcionalidad]
## Alcance
[Comportamiento incluido y exclusiones importantes]
## Actores y permisos
[Quién puede ver, iniciar, cambiar o decidir]
## Precondiciones
[Estado, datos o supuestos de política necesarios]
## Comportamiento esperado
1. [Comportamiento observable]
2. [Comportamiento observable]
## Reglas empresariales
- [Regla y sus consecuencias]
## Excepciones y fallos
- [Qué ocurre ante entradas inválidas, acceso denegado o una dependencia fallida]
## Condiciones de aceptación
- AC-01: [Condición observable y verificable]
- AC-02: [Condición observable y verificable]
## Dependencias y referencias
- [Otras especificaciones o estándares aprobados]
## Decisiones sin resolver
- [Cuestión pendiente y responsable de la decisión, si los hay]
Una especificación no necesita prescribir la estructura del código fuente ni una disposición específica de UI, salvo que esa restricción sea en sí un requisito aprobado del producto.
Plantilla E. Registro de revisión del arquitecto
# Revisión técnica: [Producto / Cambio]
## Etapa de revisión
[Inicial del Ciclo 1 / Final del Ciclo 1 / Requerida del Ciclo 2]
## Alcance
[Qué se revisó y especificaciones o cambios pertinentes]
## Hallazgos
| ID | Importancia | Hallazgo y consecuencia | Acción requerida | Responsable | Estado |
|----|-------------|------------------------|------------------|-------------|--------|
| R-01 | [Nivel] | [Problema] | [Corrección o decisión] | [Responsable] | [Abierto/Resuelto] |
## Riesgos o excepciones pendientes
[Elementos importantes y su tratamiento aprobado]
## Conclusión técnica
[Preparado / No preparado / Condicional conforme a la política, con revisor]
El registro es proporcional al cambio. Documenta criterio de ingeniería importante sin hacer que una revisión del arquitecto equivalga a la aceptación empresarial.
Plantilla F. Resultado de pruebas basadas en especificaciones
# Verificación independiente de especificaciones: [Producto / Cambio]
## Alcance
[Especificaciones y comportamientos dentro del alcance]
## Independencia de la verificación
[Cómo se separó el contexto de verificación de la implementación]
## Entorno y límites
[Contexto de prueba autorizado, datos representativos, capacidades bloqueadas]
## Resultados
| Requisito | Comprobación realizada | Esperado | Observado | Estado | Evidencia/referencia |
|-----------|------------------------|----------|-----------|--------|----------------------|
| SPEC-X / AC-01 | [Comprobación] | [Esperado] | [Observado] | Correcto / Fallo / Bloqueado / Necesita aclaración | [Referencia] |
## Hallazgos pendientes
[Fallos, bloqueos, ambigüedades y sus responsables]
## Resultado de las nuevas pruebas
[Qué cambió y qué se volvió a probar]
## Resumen
[Alcance verificado e incertidumbre restante, sin exagerar la cobertura]
Esta es una estructura de informe de ejemplo. Los procedimientos empresariales existentes de gestión de pruebas pueden proporcionar registros equivalentes.
Plantilla G. Retrospectiva ligera
# Retrospectiva de desarrollo: [Producto / Ciclo]
## Qué funcionó
- [Práctica eficaz concreta]
## Qué causó fricciones repetidas
- [Problema concreto y su efecto]
## Mejoras acordadas
| Cambio | Local o compartido | Responsable | ¿Necesita aprobación? |
|--------|--------------------|-------------|-----------------------|
| [Acción] | [Alcance] | [Responsable] | [Sí/No] |
## Decisiones de no actuar
[Explicación opcional de las cuestiones que se han dejado sin cambios intencionadamente]
Una retrospectiva no tiene que producir acciones nuevas si las prácticas existentes funcionan. Los cambios en materiales empresariales compartidos siguen su gobernanza establecida.
Utilizar las plantillas de forma responsable
Sustituya las indicaciones entre corchetes por hechos y decisiones específicos del proyecto. Elimine los encabezados irrelevantes en lugar de inventar contenido. Mantenga la coherencia de las especificaciones con el comportamiento real del producto. No copie reglas de permisos de ejemplo ni mecanismos de seguridad implícitos en un proyecto de producción sin aplicar sus políticas.