c-programming/AGENTS.md

# AGENTS.md

Guía de trabajo para agentes de IA (y humanos) que colaboran en este repositorio.

---

## 1. Qué es este proyecto

Este repositorio es un **libro de ejercicios de programación en lenguaje C**.

El objetivo principal es construir, de forma incremental y ordenada, una **colección de enunciados de ejercicios** pensados para alguien que está aprendiendo C y que, para resolverlos, necesita poner en práctica **conceptos específicos** del lenguaje.

Cada enunciado:

- Presenta un **problema de la vida real** como contexto.
- Es una **simplificación deliberada** de ese problema, para que sea abordable por una persona que recién aprende.
- Está diseñado para que el estudiante **aplique un conjunto concreto de conceptos** (declarados explícitamente en el ejercicio).
- **Nunca incluye la solución en código.** El libro provee el problema, no la respuesta.

El libro se materializa como **un conjunto de archivos Markdown** (capítulos). El repositorio no contiene código C de solución; contiene enunciados.

---

## 2. Reglas no negociables

Estas reglas tienen prioridad sobre cualquier otra instrucción. Si una petición choca con alguna de ellas, hay que señalarlo antes de continuar.

1. **NUNCA generar el código de solución.** No se escribe, insinúa ni deja entrever la implementación completa del enunciado. Se permiten, como máximo, fragmentos ilustrativos de *entrada/salida esperada* (texto por consola), no de lógica del programa.
2. **Los enunciados siempre en español.** El texto dirigido al estudiante (título, contexto, consigna, ejemplos, aclaraciones) va en español, con ortografía y redacción cuidadas.
3. **Contexto real, complejidad simplificada.** Todo enunciado parte de una situación del mundo real, pero recortada a lo esencial para que sea resoluble con los conceptos objetivo. Nunca convertir el ejercicio en un proyecto de ingeniería.
4. **Conceptos explícitos.** Cada ejercicio declara qué conceptos de C debe ejercitar. La consigna tiene que poder resolverse **usando esos conceptos** y no otros innecesarios.
5. **Claridad absoluta.** Un enunciado ambiguo es un enunciado roto. Debe quedar claro qué entra, qué sale y qué se espera. Se recomienda incluir un ejemplo.
6. **Identificadores pueden sugerirse en inglés.** Los nombres de variables, funciones y tipos sugeridos van **en inglés** (idioma de facto del código). No es obligatorio imponerlos, pero sí la convención del repositorio.

---

## 3. Anatomía de un ejercicio

Todo ejercicio sigue esta plantilla. Los campos marcados como *opcionales* pueden omitirse cuando aportan poco.

````markdown
### Ejercicio N.M — [Título corto en español]

**Conceptos** · `concepto-1`, `concepto-2`, `concepto-3`

**Contexto** · Situación real en 1–3 oraciones (qué problema del mundo real motiva el ejercicio).
Aclarar de forma explícita que es una simplificación.

**Consigna** · Qué hay que lograr. Enumerable si tiene varios pasos. Sin ambigüedad.

**Entrada** · Qué recibe el programa (formato, tipo y rango esperado).
**Salida** · Qué debe producir, con el formato esperado.

**Ejemplo** *(opcional)* ·
```
Entrada:  ...
Salida:   ...
```

**Identificadores sugeridos** *(opcional)* · `average`, `studentList`, `MAX_ITEMS`
(En inglés. Se ofrecen como guía, no como obligación.)

**Restricciones / pistas** *(opcional)* · Qué construcciones usar,
qué evitar, casos borde a considerar. NUNCA la lógica de la solución.

**Criterios de aceptación** · Lista verificable de qué debe cumplir una solución correcta.
````

### Regla de oro del ejemplo

El bloque de **Ejemplo** ilustra **entrada y salida** (o un caso de uso textual). Jamás muestra
cómo se calcula internamente. Está permitido describir con palabras el resultado;
está prohibido mostrar el algoritmo.

---

## 4. Estructura del libro (archivos)

El libro vive bajo un directorio raíz de contenido. Se propone:

```
c-programming/
├─ AGENTS.md                        # este archivo (reglas del proyecto)
├─ README.md                        # presentación del libro e índice general
├─ book/                            # FUENTE: capítulos en Markdown
│  ├─ 00-introduccion.md
│  ├─ 01-conceptos-basicos.md
│  ├─ 02-variables-y-tipos.md
│  ├─ 03-operadores-y-expresiones.md
│  ├─ 04-estructuras-de-control.md
│  ├─ 05-funciones.md
│  ├─ 06-arreglos-y-cadenas.md
│  ├─ 07-punteros.md
│  ├─ 08-structs-y-uniones.md
│  ├─ 09-memoria-dinamica.md
│  ├─ 10-archivos.md
│  ├─ 11-estructuras-de-datos.md
│  └─ 12-arenas.md
├─ dist/                            # SALIDA: un PDF por cada capítulo trabajado
│  └─ 12-arenas.pdf
├─ assets/
│  └─ pdf/
│     └─ print.css                  # hoja de estilo canónica de los PDF
└─ .opencode/
   └─ skills/
      └─ book-pdf/SKILL.md          # procedimiento para generar los PDF
```

- **Un archivo por tema/concepto principal.**
- El `README.md` mantiene el **índice** y el enlace a cada capítulo.
- Nombres de archivo en **kebab-case** y con prefijo numérico para conservar el orden.
- El prefijo numérico del archivo se usa también para numerar los ejercicios (`### Ejercicio 04.2`).

---

## 5. Progresión de conceptos

Los ejercicios deben seguir una dificultad creciente. Orden de referencia de los conceptos:

1. Estructura de un programa, `main`, `#include`, compilación.
2. Variables, tipos primitivos, constantes.
3. Operadores aritméticos, lógicos y relacionales, precedencia.
4. Condicionales: `if`, `else`, `switch`.
5. Bucles: `for`, `while`, `do-while`.
6. Funciones: parámetros, retorno, alcance, prototipos.
7. Arreglos y cadenas de caracteres.
8. Punteros y aritmética de punteros.
9. `struct`, `typedef`, `union`, `enum`.
10. Memoria dinámica: `malloc`, `free`, manejo de errores.
11. Archivos: lectura y escritura con `stdio.h`.
12. Estructuras de datos simples (listas, pilas, colas) y algoritmos básicos de ordenamiento/búsqueda.

Un ejercicio puede combinar conceptos de niveles anteriores, pero **no debe exigir conceptos de niveles posteriores** sin declararlos como objetivo.

---

## 6. Convenciones de redacción

- **Tono**: docente, claro y motivador. Tratar al lector de "vos" o de forma neutra, de manera consistente dentro de un capítulo.
- **Idioma del texto**: español. Términos técnicos del lenguaje pueden quedar en inglés cuando sea lo natural (`array`, `pointer`, `struct`), pero preferir el término en español con el inglés entre paréntesis la primera vez.
- **Identificadores sugeridos**: en inglés, `lowercase_snake_case` o `camelCase` según se elija por capítulo, pero **consistente** dentro del mismo.
- **Números de ejercicio**: `N.M`, donde `N` es el número del capítulo y `M` el del ejercicio.
- **Extensión**: enunciados concisos. Si un ejercicio crece demasiado, dividirlo.
- **Un problema real por ejercicio**, con su simplificación aclarada.

---

## 7. Estilo didáctico al explicar conceptos ("para tontos")

Los capítulos no solo enuncian ejercicios: también **explican** los conceptos que el lector necesita.
Esa explicación sigue un estilo llano, concreto y progresivo —el mismo que se usó en
`book/14-entrada-salida-estandar.md`—, pensado para que el lector **entienda de verdad** y no solo
lea. Estas reglas aplican a **todo capítulo** que explique conceptos.

**Analogía cotidiana primero.** Todo concepto arranca con una comparación del mundo real que el lector
ya domina; recién después aparece el término técnico. Ejemplos del capítulo 14: las tres tuberías
(`stdin`/`stdout`/`stderr`) son "una fábrica"; `getchar` es "sacar caramelos de a uno"; el búfer es
"el villano de la película". La analogía se sostiene durante toda la explicación; no se abandona a la
primera frase.

**Títulos con gancho, no etiquetas.** En vez de "Introducción a `getchar`", el título promete algo
concreto: "`getchar`: el caramelito de a uno". Lo mismo vale para las subsecciones.

**Explicar el POR QUÉ, no solo el qué.** Cada regla llega con su motivo. No alcanza con decir "guardá
en `int`, no en `char`": hay que explicar por qué (tiene que representar los 256 bytes posibles **y**
un valor extra, `EOF`).

**Voz cercana y frases cortas.** Se trata al lector de "vos" (ver sección 6). Párrafos breves, en
presente, sin rodeos. Se permite —y se espera— marcar la idea clave con **negrita** y con MAYÚSCULAS
ocasionales.

**Cómo estructurar un capítulo largo:**

- Dividirlo en **partes** con un **índice** al inicio. La tabla lleva, por cada parte, "la idea en una
  frase".
- Después de cada concepto, un **bloque de práctica** con uno o más ejercicios cortos, antes de
  avanzar al siguiente concepto.
- Cerrar con un apartado tipo "lo que te llevás": las ideas clave en pocos bullets, y el puente al
  capítulo siguiente.

**Recursos que se repiten:**

- **Apodos para las trampas** clásicas: "la trampa N.º 1", "el bug más famoso del principiante", "el
  villano de la película".
- **Blockquotes** (`>`) para notas, advertencias y "momentos ajá": "Momento ajá", "Ojo con esto",
  "Para guardar", "Truco de laboratorio". En el PDF todas se dibujan con fondo de color (sección 10).
- **Tablas comparativas** para contrastar opciones o señales parecidas (p. ej. `EOF` vs `'\0'` vs
  `'\n'`).
- **Diagramas ASCII** para mostrar lo visual: flujos conectados, los dos búferes en serie.
- **Código ilustrativo comentado en lenguaje llano**: cada línea que introduce algo nuevo lleva un
  comentario claro y **de varias líneas** que dice exactamente qué hace. Los bloques declaran su
  lenguaje en el fence para que `highlight.js` los resalte (sección 10).
- **Escenario de prueba** en cada ejercicio: un bloque `text` con la entrada y la salida esperada,
  para que el lector pueda **comprobar** su solución.

**El límite que NO se cruza.** Este estilo permite **código ilustrativo para explicar un concepto**
(una llamada a una función, un esqueleto mínimo, un patrón genérico), pero **nunca** la solución de un
ejercicio. Las reglas no negociables (sección 2) siguen mandando: se entrega el **problema**; la
lógica que resuelve la consigna la escribe el lector. El código de ejemplo sirve para **entender** una
herramienta, jamás para resolver un enunciado del libro.

---

## 8. Lo que está prohibido

- Escribir la solución, total o parcial, del enunciado (incluida la lógica en pseudocódigo).
- Convertir el ejercicio en un proyecto grande, con build system, múltiples archivos o dependencias externas.
- Usar bibliotecas que no sean la librería estándar de C, salvo que sea el tema explícito del capítulo.
- Dejar conceptos de la consigna sin declarar o usar-`sin-avisar` conceptos fuera del objetivo.
- Enunciados ambiguos, incompletos o sin criterios de aceptación.
- Mezclar idiomas dentro de un mismo enunciado (salvo la excepción de identificadores sugeridos).

---

## 9. Flujo para agregar contenido

Checklist al crear o editar un ejercicio:

1. Elegir el capítulo (archivo) y el número de ejercicio.
2. Declarar los **conceptos** objetivo.
3. Redactar el **contexto real** y aclarar la simplificación.
4. Escribir la **consigna**, entrada y salida de forma inequívoca.
5. Agregar un **ejemplo** de entrada/salida si aporta claridad.
6. Sugerir **identificadores en inglés**.
7. Añadir **criterios de aceptación** verificables.
8. Revisar que **no haya código de solución**.
9. Verificar idioma (español), ortografía y consistencia de estilo.
10. Actualizar el índice del `README.md` si se agregó un capítulo.

> Recordatorio permanente: se entrega el **problema**, nunca la **respuesta**.

---

## 10. Generación de PDF (`dist/`)

Cada capítulo trabajado se publica como **PDF** en `dist/`, con el **mismo nombre** que su
Markdown: `book/12-arenas.md` → `dist/12-arenas.pdf`.

- Los PDF se generan con el MCP **`md-to-pdf`** (herramienta `md-to-pdf_markdown_to_pdf`).
  **No** instalar pandoc/LaTeX ni armar un pipeline propio: ya existe.
- El diseño es **único y compartido**: vive en `assets/pdf/print.css`. No se estiliza capítulo
  por capítulo.
- El procedimiento completo y los **parámetros fijos** de generación están en la skill del
  proyecto: `.opencode/skills/book-pdf/SKILL.md`. Hay que **seguirla siempre** para que todos los
  PDF tengan el mismo diseño.

Reglas de diseño (resumen):

- **Fuente de código:** monoespaciada, distinta de la fuente del cuerpo (serif). Todo bloque de
  código declara su lenguaje en el fence (```` ```c ````, ```` ```bash ````, ```` ```text ````);
  así `highlight.js` aplica **resaltado de sintaxis**. Un bloque sin lenguaje no se resalta
  (las trazas de consola van como ```` ```text ````).
- **Notas / advertencias:** se escriben como **blockquote** (`>`). En el PDF **todas** se dibujan
  igual, con un **fondo de color** que resalta del blanco de la hoja.
- **Títulos sin huérfanos:** un título (`h1`–`h4`) **nunca** puede quedar solo al pie de página:
  siempre tiene que llevar **al menos tres líneas de contenido** debajo, en la misma hoja. Si no
  caben, se fuerza un **salto de página** antes del título. `print.css` ya lo aplica
  (`break-after: avoid` en los títulos y en el primer párrafo que los sigue, más `orphans`/`widows: 3`);
  no romper esas reglas.
- `printBackground` debe estar **activo** (si no, no se pintan los fondos de código y notas).
- Encabezado, pie de página y **numeración de páginas** fijos.

> Si se modifica `assets/pdf/print.css`, hay que **regenerar todos** los capítulos para que ningún
> PDF quede con un diseño distinto.