# AGENTS.md

Guía para agentes y colaboradores que trabajen en **{{PROYECTO}}**.
Léela antes de tocar cualquier fichero y respétala en cada cambio.

## Propósito del proyecto

{{DESCRIPCION}}

## Contenido del repositorio

| Ruta | Descripción |
| --- | --- |
| `AGENTS.md` | Este documento: reglas de trabajo. |
| `README.md` | Visión general y puesta en marcha. |
| `INSTALL.md` | Instalación detallada y dependencias. |
| `CHANGELOG.md` | Historial de cambios (*Keep a Changelog*). |
| `TODO.md` | Tareas pendientes y deuda técnica. |
| _(completar)_ | Añade aquí el código y los recursos del proyecto. |

## Reglas de modelo

PENDIENTE: definir qué modelo de pi se usa en este proyecto, con qué contexto y
con qué criterio de selección (coste, VRAM, ventana, velocidad). Se acuerda
tarea por tarea; hasta entonces, no fijar valores aquí.

## Reglas de funcionamiento

PENDIENTE: definir flujo de trabajo, estándares de código, comandos obligatorios,
política de ramas y de revisión, y cualquier automatización propia del proyecto.

## Reglas obligatorias

1. **Todo cambio se documenta y se commitea.** Cada vez que se modifique
   cualquier fichero del repositorio:
   - Añadir una entrada en `CHANGELOG.md` (fecha, versión y tipo:
     `Añadido` / `Cambiado` / `Corregido` / `Eliminado`).
   - Actualizar `TODO.md` si el cambio abre, cierra o modifica tareas.
   - Actualizar `README.md`, `INSTALL.md` o los documentos que correspondan si
     cambia el comportamiento, la instalación o el uso.
   - Crear **un commit de git** con mensaje claro en imperativo.
2. **Nunca dejar documentación desfasada.** Si el código y los documentos no
   coinciden, el cambio está incompleto.
3. **No commitear** secretos, binarios, artefactos de build, logs ni dependencias
   descargadas (`.gitignore` cubre lo básico; amplíalo según el stack).
4. **Idioma: español** para documentación, mensajes de commit y comentarios.

## Verificación antes de commitear

PENDIENTE: sustituir por los comandos reales del stack (formato, tipos, tests,
lint). Ningún commit sin verificación en verde.

```bash
# ejemplo
# make check
```

## Flujo de trabajo

1. Editar los ficheros necesarios.
2. Ejecutar las verificaciones anteriores.
3. Actualizar `CHANGELOG.md`, `TODO.md` y la documentación afectada.
4. `git add -A && git commit -m "tipo(alcance): descripción breve"`.
5. Informar del cambio y del hash del commit.

## Convención de mensajes de commit

`tipo(alcance): resumen` — tipos: `feat`, `fix`, `docs`, `chore`, `refactor`,
`test`, `build`, `perf`.

Ejemplos:
- `docs: documentar instalación y puesta en marcha`
- `feat(api): añadir búsqueda paginada`