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.

### 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/
   ├─ 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

• 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. 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).

---

8. 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.