Add AGENTS.md for project guidelines and introduce Chapter 12 on Arena Allocators
- Created AGENTS.md to outline rules and structure for contributors. - Added Chapter 12 on Arena Allocators, covering memory management strategies, implementation details, and exercises for practical understanding.
This commit is contained in:
@@ -0,0 +1,165 @@
|
||||
# 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**.
|
||||
Reference in New Issue
Block a user