desarrollo
Punto de entrada ÚNICO para escribir, revisar o migrar código del proyecto —back, front, base de datos, seguridad, entrega—. Trae el método propio completo: TDD con evidencia del rojo, endpoints con e
SKILL.md.claude/skills/desarrollo/SKILL.md
GitHubDesarrollo — el método propio del proyecto
Esta skill es la puerta a todo lo que es código. No escribe la solución por vos: fija cómo se escribe, qué cuenta como evidencia, quién verifica y qué frena la entrega. Lo que una Tarea del tablero define (qué hay que hacer: contrato, Escenarios, tests a escribir primero) manda antes; recién después entra esto.
La idea, en tres frases
- El contrato primero, el test después, el código al final. Así el front y el back trabajan en paralelo y el test tiene algo concreto que verificar.
- Un ciclo que no deja evidencia no ocurrió. El rojo tiene que haber fallado en su aserción, antes del código, y lo verifica otro agente.
- Tres estados, nunca dos. OK / HALLAZGO / SIN DATOS, y SIN DATOS no es aprobado.
Todos los comandos de esta skill se corren parados en la raíz del repositorio del Cerebro. Las rutas son relativas a ella.
REGLA DE ORO: punto de entrada único
Ninguna guía de desarrollo —propia o de terceros— se aplica sin pasar por acá. No es burocracia: una guía ajena aplicada suelta puede imponer una estructura de paquetes por capa técnica que rompe los límites de módulo del proyecto ([[decisiones#DEC-002]]), y eso se descubre recién cuando el código ya está escrito.
Si una sesión aplicó otra guía sin pasar por acá, eso es un hallazgo: se avisa y se revisa lo que produjo contra la tabla de precedencia.
Si la organización tiene un estándar corporativo
Se envuelve, no se copia ni se instala: se lee del servidor en el momento de usarlo (por el
MCP del repositorio que lo publica), se le aplica encima la tabla de precedencia de abajo, y
se descarta. Queda declarado en DEPENDENCIAS-EXTERNAS.md con el hash de árbol contra el que se
lo revisó. Sin acceso al servidor el veredicto es SIN DATOS: no se improvisa lo que el
estándar diría, porque eso es inventar un estándar ajeno.
El método — organizado por cuándo lo vas a usar
Todos los días
| Tema | Archivo |
|---|---|
| Crear un endpoint de punta a punta: contrato → tests → código → checklist | crear-endpoint.md |
| El ciclo rojo-verde y qué cuenta como evidencia del rojo | tdd-ciclo-y-evidencia.md |
| Arreglar un bug — el ciclo, y los tres tipos que no se parecen | arreglar-un-bug.md |
Depurar — causa vs. síntoma, trace_id, qué nunca va en un log |
depurar.md |
| Refactor y deuda técnica — la fase 3, y qué no se refactoriza | refactor.md |
| Revisión de código por 5 dimensiones, con severidad | code-review.md |
| El Merge Request: tamaño, descripción, checklist, quién revisa | merge-request.md |
| Ramas, commits y espacios de trabajo | ramas-y-commits.md |
Según el stack (⚠ se completan al decidir DEC-003)
| Tema | Archivo |
|---|---|
| Back: dónde va cada cosa, cómo se ve un rojo válido en el runner, comandos | tdd-stack-back.md |
| Front: idem, más la simulación de la API | tdd-stack-front.md |
| Simular la API en el front desde el contrato | simular-api-desde-el-contrato.md |
| Accesibilidad — los 4 chequeos que cubren casi todo | accesibilidad.md |
Tests
| Tema | Archivo |
|---|---|
| Qué prueba un test unitario, y qué no | tests-unitarios.md |
| Armar la suite: 7 categorías, mutación, propiedades, tests inestables | armar-la-suite.md |
| Pruebas de aceptación: la capa que prueba el sistema desplegado contra los Escenarios de la Historia; qué expone el front; cuándo corre | pruebas-de-aceptacion.md |
Por hito
| Tema | Archivo |
|---|---|
| Arrancar una funcionalidad completa: back y front en paralelo | arrancar-funcionalidad.md |
| El contrato OpenAPI como fuente | contrato-openapi.md |
| Seguridad y datos sensibles — SAST, PHI, los controles que aplican | seguridad-y-datos-sensibles.md |
| Dependencias, configuración y secretos | dependencias-y-config.md |
| Observabilidad — las 4 señales, logs, alertas, chequeos de salud | observabilidad.md |
| Cambiar el esquema de la base sin romper: expandir/migrar/contraer | migracion-de-base.md |
| Entregar — qué tiene que exigir el pipeline, y volver atrás | entregar-a-produccion.md |
| Refactor o migración de una aplicación existente: red primero, caracterización, paridad, estrangulador | refactor-y-migracion.md |
| Ingeniería inversa de una aplicación existente | ingenieria-inversa.md |
Adoptar un proyecto que ya trabaja con IA (su CLAUDE.md, skills, MCP) sin tirar nada ni quemar tokens |
adoptar-proyecto-existente.md |
Cuando hace falta
| Tema | Archivo |
|---|---|
| Rendimiento — no se optimiza sin medir. Los 4 sospechosos | rendimiento.md |
| Incidentes en producción — contener antes de entender | incidentes.md |
| Entender código ajeno — y el arranque de alguien nuevo | entender-codigo-ajeno.md |
Bibliografía (ideas tomadas con atribución, nunca texto): referencias-externas.md.
Los seis guardarraíles
G1 — El código y el conocimiento no se mezclan
Un pedido de código activa esta skill y las de verificación de los repos. No activa las del Cerebro ni las del pipeline de Azure. Y al revés: redactar una Tarea, auditar una Historia o bajar una ficha al tablero no activa esta skill.
El cruce a evitar es concreto: una sesión de código que se pone a escribir fichas de negocio, o una sesión de tickets que se pone a generar código.
Zona gris declarada: el momento en que una Tarea se vuelve código. Ahí mandan las dos, en este orden: la Tarea define qué hay que hacer (contrato, tests a escribir primero), y recién después esta skill define cómo se escribe. Nunca simultáneo.
Las skills que viven en los repositorios de código
Esta skill es el método; la ejecución dentro del código la hacen las skills de back/ y
front/, que actúan dentro del repositorio clonado:
| Skill | Dónde vive | Qué hace | Relación con ésta |
|---|---|---|---|
guiar-tdd |
back/ y front/ |
Conduce el ciclo rojo-verde mientras se programa | Aplica tdd-ciclo-y-evidencia.md |
verificar-tdd |
back/ y front/ |
Audita la evidencia — la corre otro agente | Es el paso 5 del ciclo por Tarea. No puede vivir acá: quien produce nunca aprueba |
auditar-codigo |
back/ y front/ |
¿La entrega cumple lo que el pipeline exige? Contrato de la Tarea, límites del módulo, tests cubiertos, sin PHI ni secretos | Distinta de code-review.md, que mira si el código está bien escrito |
armar-swagger |
sólo back/ |
Consolida y valida el openapi.yaml |
Es el paso obligatorio de contrato-openapi.md |
diagnosticar-repo |
back/ y front/ |
Corre el Doctor sobre el repositorio clonado | Independiente |
consultar-cerebro |
back/ y front/ |
Lectura del Cerebro, una ficha por vez | Independiente |
El reparto, en una línea: acá está el MÉTODO; allá está la EJECUCIÓN dentro del código.
verificar-tddyauditar-codigoestán afuera a propósito. Si vivieran acá, el mismo agente que produjo leería la guía de cómo auditarse — y se pierde la independencia, que es la regla más fuerte del método.armar-swaggersólo existe enback/. En el front, ese ítem se verifica contra el contrato que consolidó el back.
Ojo con los conteos. Cuando el proyecto cuenta sus skills (el número vive en
AGENTS.mdy lo verifica el hook), habla de las decerebro-digital/configuracion-ia/skills/. Las deback/yfront/no entran en ese número, pero sí se versionan y sí las verifica el hook: compara el par.claude/skillscontra.agents/skillsde cada uno y frena el commit si difieren.
G2 — Punto de entrada único
Ya dicho arriba. Se repite acá porque sostiene a los otros cinco: si alguien entra por la puerta de atrás, ninguna corrección se aplica.
G3 — La precedencia está escrita, no se deduce
Cuando una guía externa y este proyecto dicen cosas distintas, no se resuelve por criterio del modelo: se resuelve por la tabla de abajo. Lo que no esté en la tabla y choque, se frena y se pregunta, no se elige. Una fila de la tabla puede decir "se pregunta": estar en la tabla no significa estar resuelto; significa que ya se miró.
G4 — Nada sale del repositorio
Nada sale de este repositorio hacia afuera sin un "sí" explícito sobre lo que se va a publicar. Publicar en un repositorio ajeno (una propuesta de mejora a un estándar corporativo, un issue, un Merge Request) es un turno aparte: primero se muestra el contenido exacto y se termina el turno; recién un "sí" nuevo habilita escribir afuera. Y si el token disponible es de sólo lectura, directamente no está en el alcance.
G5 — Lo externo se declara, con hash y detector de deriva
Sólo aplica si el proyecto envuelve un estándar externo; el template no trae el detector: se agrega
junto con la primera dependencia declarada, como dice DEPENDENCIAS-EXTERNAS.md. Si el proyecto sigue
skills de terceros, se declaran en DEPENDENCIAS-EXTERNAS.md con el hash
de árbol de cada una. Importa más con el mecanismo de "leer del servidor", no menos: como el
contenido se lee siempre actualizado, lo que puede quedar viejo son nuestras correcciones. Un
detector de deriva (comparar los hashes de hoy contra el ancla declarada) se corre una vez por
mes y devuelve OK / HALLAZGO / SIN DATOS; SIN DATOS no es OK. El ancla vive en el
manifiesto y en el script que compara: actualizarla es actualizar los dos.
G6 — El lenguaje lo pone el repositorio
En los repos de la aplicación se escribe en el lenguaje y con las herramientas que el repo ya
usa (los que fija DEC-003 y documentan tdd-stack-back.md / tdd-stack-front.md). Eso incluye
los tests de lo que no es la app (el pipeline, scripts, configuración): van al runner de tests del
repo, no a uno aparte.
- Permitido sin preguntar:
shadentro de un job del pipeline y elDockerfile, porque es lo que trae la imagen. - Si con el lenguaje del repo se puede, se hace así. Si otro lenguaje tenía ventajas, se anota en el Merge Request qué ganaría y qué sumaría, sin escribirlo.
- Si con el lenguaje del repo no se puede, se frena y se pregunta antes de escribir una línea: por qué no se puede, qué lenguaje se propone y qué agrega (herramienta a instalar, dependencias, jobs del template que se activan).
No aplica al repositorio del Cerebro: ahí bin/ es Python a propósito.
Por qué. En el proyecto de origen de este template entraron dos scripts en otro lenguaje para probar el pipeline: sumaron un requisito más, activaron un job del template que falló y quedaron fuera del runner de tests, así que no protegían nada.
Tabla de precedencia
⚠ A completar por el equipo si la organización publica un estándar corporativo. Mientras no haya estándar externo, gana el proyecto en todo y la tabla queda como molde. Los temas que casi siempre chocan:
| Tema | El estándar externo dice | Nosotros decimos | Gana |
|---|---|---|---|
| Estructura de paquetes del back | <completar> | Paquete por módulo de dominio con 4 capas + exceptions/ + shared/ ([[decisiones#DEC-002]]); entre módulos sólo por la application del otro |
NOSOTROS (salvo que el equipo cambie DEC-002) |
| Framework y estructura del front | <completar> | Lo que fije DEC-003 |
⚠ a decidir |
| Test primero | <completar> | Lo mismo, más evidencia: el test tiene que haber fallado en su aserción, y lo verifica un agente distinto del que escribió el código | LOS DOS (el nuestro es más exigente) |
| Publicar en el repositorio del estándar | <completar> | Nada sale sin un "sí" explícito (G4) | NOSOTROS |
| Extensiones/librerías obligatorias, registry interno, dependencias aprobadas, autenticación y roles | <completar> | Si la organización lo define, se toma tal cual | EL ESTÁNDAR (si existe) |
| Design tokens | <completar> | Design system propio (diseno/diseno-sistema.md y cerebro-mockup-design); nunca hexadecimales a mano |
⚠ se pregunta si hay dos paletas |
| Cobertura mínima | <completar> | ⚠ umbral a definir por el equipo (DEC-003) |
⚠ a decidir |
Lo que este método exige y una guía genérica no
| Agregado | Por qué |
|---|---|
| Evidencia del rojo antes del verde | Mandar «escribí el test primero» sin pedir prueba no cambia nada: un test escrito después cumple la letra |
| Verificador distinto del productor | Si el mismo agente codea y se aprueba, no hay control: hay una declaración |
| Veredicto de tres estados | Sin SIN DATOS, "no encontré nada" y "no pude mirar" se confunden, y el segundo pasa por aprobado |
| Regla del cero | Cero hallazgos sobre entrada externa no es aprobado: es no auditable |
| Límites de módulo ([[decisiones#DEC-002]]) | Sin esto, el código generado rompe la arquitectura del proyecto |
| PHI prohibido con marcadores | En código, tests, fixtures, logs, contrato y descripción del Merge Request |
Barreras
- Lo que no esté en la tabla de precedencia y choque, se pregunta. No se elige.
- Si no se puede leer una fuente externa, se reporta
SIN DATOSy se dice qué falta (red, token). No se improvisa lo que esa fuente diría. Todometodo/funciona igual: es propio y no depende de nada. - Nunca se pega contenido de terceros dentro de este repositorio. Se lee, se usa, se descarta
(G5). Las citas mínimas con atribución van en
references/referencias-externas.md. - Los comentarios del código, en español (back y front). Se comenta poco —el código se explica
por sus nombres, donde sólo los sustantivos del negocio que están en la base van en español y
los verbos, roles técnicos y técnica en inglés (
arquitectura/esqueleto-proyectos.md)—, pero el comentario que hace falta se escribe en español, igual que la documentación y los mensajes de commit. - Sin PHI en nada que se versione o se publique. Marcadores:
<persona>,<documento>,<identificador>,<telefono>,<direccion>,<dato-sensible>.