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