Skills per a IA com a documentació viva d'un equip de desenvolupament

Tots els equips que conec tenen convencions que no estan escrites enlloc. Com es nomenen els endpoints. Quina estructura té un servei nou. On van els tests d’integració. Quin és el patró per gestionar errors. Quines llibreries estan aprovades i quines no. Per què es va triar Kotlin en comptes de Java per a aquell mòdul.

Tot aquest coneixement viu al cap de tres o quatre persones de l’equip. Quan algú nou entra, ho aprèn a base de code reviews, preguntes a Slack i errors que li corregeixen a les PRs. Quan algú se’n va, part d’aquest coneixement desapareix.

Les skills d’IA no són la solució màgica a aquest problema. Però són una eina sorprenentment bona per capturar-lo d’una manera que realment es fa servir. No com un document de Confluence que ningú llegeix, sinó com instruccions operatives que un agent d’IA aplica cada vegada que treballa amb el teu codi.

Què és una skill (en el context que ens interessa)

A l’article de MCP vs Skills ja explicava la diferència entre tots dos conceptes. Aquí no ho repetiré. El que m’interessa és un ús concret: les skills com a documentació viva de les pràctiques d’un equip de desenvolupament.

Una skill, en aquest context, és un document estructurat que li diu a un agent d’IA com treballa el teu equip. No és un manual genèric. És la codificació de les vostres decisions, convencions i patrons específics.

La diferència entre una skill i documentació tradicional és que la skill s’executa. No la llegeix una persona i la interpreta. La llegeix un agent i l’aplica directament en generar codi, revisar PRs o crear tests.

Això canvia radicalment el que val la pena documentar i com fer-ho.

Exemple real: skill de convencions backend

Mostraré un exemple concret de skill que faig servir en un projecte amb Kotlin i Spring Boot. No és un exemple inventat; és una versió simplificada del que tinc en un repositori real.

# Backend Conventions - [Nombre del proyecto]

## Stack y versiones
- Kotlin 2.x, Spring Boot 3.x, Gradle (Kotlin DSL)
- Base de datos: PostgreSQL 16
- Tests: JUnit 5 + MockK + Testcontainers

## Estructura de paquetes
Seguimos estructura por feature, no por capa:

src/main/kotlin/com/example/project/ ├── order/ │ ├── OrderController.kt │ ├── OrderService.kt │ ├── OrderRepository.kt │ ├── Order.kt # Entidad │ ├── OrderDto.kt # DTOs de request/response │ └── OrderException.kt # Excepciones específicas ├── product/ │ └── … └── shared/ ├── config/ ├── security/ └── exception/

## Convenciones de código

### Naming
- Controllers: `{Feature}Controller`
- Services: `{Feature}Service` (interfaz) + `{Feature}ServiceImpl` solo si hay más de una implementación
- DTOs: `{Feature}Request`, `{Feature}Response`
- Excepciones: `{Feature}{Tipo}Exception` (ej: `OrderNotFoundException`)

### Endpoints REST
- Siempre versionados: `/api/v1/{recurso}`
- Plurales: `/api/v1/orders`, no `/api/v1/order`
- Filtros como query params, no path params
- Respuestas paginadas usan `Page<T>` de Spring Data

### Error handling
- Usamos `@RestControllerAdvice` centralizado
- Las excepciones de negocio extienden `BusinessException`
- El formato de error es siempre:
```json
{
  "code": "ORDER_NOT_FOUND",
  "message": "Texto descriptivo",
  "timestamp": "2026-05-18T10:00:00Z"
}

Tests

• Unit tests: MockK para mocks, sufijo Test
• Integration tests: Testcontainers, sufijo IntegrationTest
• Cada servicio tiene al menos: happy path, validación de input, caso de error principal
• NO mockeamos repositorios en integration tests

Antipatrones (no hacer)

• No usar @Autowired por field injection. Siempre constructor injection.
• No crear DTOs genéricos compartidos entre features. Cada feature tiene los suyos.
• No poner lógica de negocio en controllers.
• No usar Optional<T> de Java. Usar nullable types de Kotlin.
• No hacer queries con string concatenation. Siempre named parameters.

Ejemplo de servicio correcto

@Service
class OrderService(
    private val orderRepository: OrderRepository,
    private val eventPublisher: ApplicationEventPublisher
) {
    fun getOrder(orderId: Long): OrderResponse {
        val order = orderRepository.findByIdOrNull(orderId)
            ?: throw OrderNotFoundException(orderId)
        return order.toResponse()
    }

    @Transactional
    fun createOrder(request: CreateOrderRequest): OrderResponse {
        val order = request.toEntity()
        val saved = orderRepository.save(order)
        eventPublisher.publishEvent(OrderCreatedEvent(saved.id))
        return saved.toResponse()
    }
}

Aquest document, carregat com a skill en un agent d'IA, fa que el codi que genera segueixi automàticament les convencions de l'equip. No necessites corregir-lo al code review perquè ja sap que feu servir injecció per constructor, que els endpoints són plurals i versionats, i que els tests d'integració fan servir Testcontainers.

---

## Què posar en una skill

No tot mereix estar en una skill. El contingut hauria de complir tres criteris:

**1. És estable.** No canvia cada setmana. Les convencions de naming, l'estructura de paquets, els patrons d'error handling... això és estable. La versió exacta d'una dependència que esteu avaluant no ho és.

**2. És operatiu.** Algú (o un agent) pot aplicar-ho directament en escriure codi. "Fem servir estructura per feature" és operatiu. "Valorem la clean architecture" no ho és (és massa abstracte).

**3. És específic del vostre equip.** Si és una pràctica universal de Kotlin o Spring Boot, no cal posar-la. L'agent ja ho sap. El que l'agent no sap és que vosaltres feu servir un `@RestControllerAdvice` centralitzat amb un format d'error concret.

Concretament, el que acostumo a incloure:

### Convencions de codi
- Naming de classes, mètodes, paquets.
- Estructura de projecte.
- Patrons d'error handling.
- Com es defineixen els DTOs.
- Format de logs.

### Patrons arquitectònics
- Com es comuniquen els mòduls entre si.
- Quin patró es fa servir per a esdeveniments (si feu servir event-driven).
- Com es gestiona la transaccionalitat.
- Separació de responsabilitats entre capes.

### Decisions tècniques clau
- Per què es va triar una tecnologia per sobre d'una altra.
- Restriccions de seguretat (quines llibreries estan prohibides, quins endpoints necessiten auth).
- Polítiques de versionat d'API.

### Exemples concrets
- Un exemple de servei ben fet.
- Un exemple de test ben fet.
- Un exemple de migració de base de dades.

### Antipatrons explícits
- Coses que no s'han de fer, amb el motiu.
- Errors que s'han comès en el passat i no es volen repetir.

---

## Què NO posar en una skill

Tan important com saber què incloure és saber què deixar fora. He vist skills que intenten ser una enciclopèdia del projecte i acaben sent inútils perquè l'agent es perd entre tant soroll.

**Informació efímera.** L'estat actual d'un sprint, qui està de vacances, quins tickets estan en progrés. Això canvia constantment i contamina el context de l'agent.

**Dades sensibles.** Credencials, API keys, URLs de sistemes interns, noms de clients reals. Una skill pot acabar al context d'un LLM extern. Mai posis en una skill alguna cosa que no posaries en un repo públic.

**Detalls d'implementació de tercers.** No necessites explicar-li a l'agent com funciona Spring Security internament. Sí que necessites explicar-li com l'heu configurat vosaltres.

**Tot el que canvia cada setmana.** Si una decisió encara no està consolidada, no la posis a la skill. Espera que s'estabilitzi. Una skill amb informació contradictòria o desactualitzada és pitjor que no tenir skill.

**Opinions personals no consensuades.** "Jo prefereixo fer servir corrutines per a tot" no és una convenció de l'equip. Si l'equip ha decidit fer servir corrutines en un context específic, això sí que és documentable.

> La regla és senzilla: si no ho defensaries en un code review com a convenció de l'equip, no va a la skill.

---

## Com versionar-ho: juntament amb el codi, al repo

Les skills haurien de viure al mateix repositori que el codi. No en un wiki separat. No en un Google Doc. No en un canal de Slack fixat.

La raó és pràctica: si la skill és al repo, es versiona amb git, es revisa a les PRs i evoluciona juntament amb el codi que descriu. Si és en un altre lloc, es desincronitza en dues setmanes.

Estructura que faig servir:

projecte/ ├── .ai/ │ ├── skills/ │ │ ├── backend-conventions.md │ │ ├── testing-patterns.md │ │ ├── api-design.md │ │ └── deployment-checklist.md │ └── context/ │ ├── architecture-overview.md │ └── tech-decisions.md ├── src/ ├── build.gradle.kts └── …

La carpeta `.ai/skills/` conté les skills pròpiament dites. La carpeta `.ai/context/` conté documents de context més ampli (visió general d'arquitectura, decisions tècniques tipus ADR) que complementen les skills però no són instruccions operatives.

Avantatges d'aquest enfocament:

- **Versionat.** Cada canvi en una skill queda registrat a git. Pots veure qui el va canviar, quan i per què.
- **Code review.** Un canvi en una skill passa pel mateix procés de revisió que un canvi en codi. Això evita que una persona posi les seves preferències personals sense consens.
- **Sincronització.** Si canvies una convenció de codi, pots actualitzar la skill a la mateixa PR. Així mai es desincronitza.
- **Descobriment.** Qualsevol persona nova que cloni el repo veu les skills immediatament. No ha de buscar en tres eines diferents.

---

## Com evitar documentació escombraries

El risc més gran de les skills és que es converteixin en un altre dipòsit de documentació morta. Per evitar-ho, aplico tres pràctiques:

### 1. Review obligatori

Qualsevol canvi en una skill passa per PR amb almenys un reviewer de l'equip. No es mergeja sense consens. Si algú vol afegir una convenció nova, l'ha de justificar i l'equip l'ha d'acceptar.

Això sembla obvi però evita el problema més comú: una persona escriu una skill amb les seves preferències personals i l'equip la ignora perquè no la sent seva.

### 2. Testing de skills

Sona estrany, però té sentit. Periòdicament (jo ho faig cada dos o tres sprints) faig una prova senzilla: dono la skill a un agent d'IA i li demano que generi un component nou. Després reviso si el resultat segueix les convencions de l'equip.

Si l'agent genera codi que no compleix les vostres convencions, la skill no està ben escrita. És un test funcional de la documentació.

```bash
# Exemple de prompt per testejar una skill
"Usando las convenciones del proyecto, genera un nuevo servicio para gestionar
notificaciones. Incluye el controlador, el servicio, los DTOs, los tests
unitarios y un test de integración."

Reviso l’output i verifico:

• Estructura de paquets correcta.
• Naming correcte.
• Error handling seguint el patró.
• Tests amb el format esperat.
• Sense antipatrons.

Si falla en alguna cosa, actualitzo la skill perquè sigui més clara en aquell punt.

3. Data de revisió

Cada skill té una data d’última revisió al propi document:

# Backend Conventions

> Última revisió: 2026-05-01 | Pròxima revisió: 2026-08-01
> Responsable: @roger

Si la data de revisió passa sense que ningú la revisi, és un senyal que la skill pot estar desactualitzada. No és automatització, és disciplina de l’equip.

Skills per a onboarding

Un dels usos més potents de les skills és l’onboarding de nous membres de l’equip. En comptes d’una setmana de reunions explicant “com fem les coses aquí”, la persona nova pot:

1. Llegir les skills del repo (són documents curts i concrets).
2. Fer servir un agent d’IA amb aquestes skills carregades per fer les seves primeres contribucions.
3. L’agent li genera codi que ja segueix les convencions, i la persona aprèn els patrons de l’equip mentre treballa.

No substitueix el mentoring humà, però el complementa d’una manera que abans no era possible. La persona nova no ha d’endevinar convencions ni esperar que li ho corregeixin a la PR. L’agent ja li dona el format correcte des del principi.

He vist equips on el temps d’onboarding efectiu (fins que la persona contribueix codi que no requereix correccions majors d’estil) va passar de 3-4 setmanes a menys d’1 setmana fent servir skills ben escrites.

Relació amb specs i SDD

Les skills encaixen naturalment en un flux de Spec-Driven Development. La relació és aquesta:

• La spec defineix què es construirà i amb quins criteris d’acceptació.
• La skill defineix com es construeix en aquest equip (convencions, patrons, restriccions).
• L’agent fa servir totes dues per generar codi que compleix els requisits i segueix els estàndards.

Sense la spec, l’agent no sap què construir. Sense la skill, l’agent construeix alguna cosa genèrica que no encaixa amb el vostre projecte. Necessites les dues.

Un prompt típic que combina totes dues:

Contexto: Carga las skills de backend-conventions.md y testing-patterns.md

Tarea: Implementa el ticket ORDER-123 siguiendo la spec adjunta.
Requisitos:
- Endpoint POST /api/v1/orders/bulk para creación masiva de pedidos
- Validación de stock antes de confirmar
- Evento OrdersBulkCreated al completar
- Tests unitarios y de integración

Spec: [contenido de la spec del ticket]

El resultat és codi que compleix la funcionalitat especificada I segueix les convencions de l’equip. Això és el que fa que les skills no siguin un document decoratiu: són una peça funcional del flux de treball.

Comença petit

Si no tens skills i vols començar, no intentis documentar-ho tot el primer dia. Comença amb una sola skill: les convencions de codi més bàsiques del teu projecte. El mínim que li diries a algú nou el primer dia.

Una skill de 40-50 línies ben escrites val més que un document de 500 línies que ningú manté. Amb el temps, aniràs afegint més skills a mesura que identifiquis patrons que l’equip repeteix i que l’agent necessita conèixer.

L’important no és tenir la skill perfecta. És tenir una skill que es fa servir, es revisa i evoluciona amb el projecte. Això ja és més documentació viva de la que té el 90% dels equips.