Refactor code structure for improved readability and maintainability

2026-11-12 11:41:45 -03:00
parent 913efb475b
commit e2195a7ed2
7 changed files with 3732 additions and 0 deletions
@@ -262,3 +262,47 @@ Reglas de diseño (resumen):

 > 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.
+
+---
+
+## Protocolo de escritura de archivos extensos
+
+Cuando el agente (humano o IA) necesita escribir un archivo Markdown de contenido grande
+(≥ 600 líneas, como los capítulos del libro), **no usar una única llamada a `write` con todo el contenido**.
+Los herramientas de escritura pasan el contenido dentro de un string JSON y los caracteres especiales
+(tres backticks ```, `$`, `{`, `}`, `\`, comillas) pueden romper el parseo.
+
+### Enfoque correcto (confirmado en producción)
+
+1. **Escribir con `write` solo los primeros ~500-600 líneas**, hasta la primera sección completa
+   (hasta un `---` o final de una parte). El archivo se crea correctamente porque el contenido
+   es manejable para el parser JSON.
+
+2. **Usar `edit` para ir agregando las secciones restantes**. Cada llamada a `edit` reemplaza
+   una cadena corta (`oldString`) por otra más larga (`newString`). La cadena a buscar es siempre
+   muy breve (ej: el último texto del archivo actual) y la cadena de reemplazo incluye la nueva sección.
+
+   ```
+   oldString: "- [ ] Termina limpiamente al escribir \"exit\"."    ← solo la última línea existente
+   newString: "- [ ] Termina limpiamente al escribir \"exit\".\n\n---\n# PARTE 5 — ..."     ← misma + nueva sección
+   ```
+
+3. **Verificar el conteo de líneas** con un bash/PowerShell simple después de cada edit grande,
+   para confirmar que la sección se incorporó correctamente:
+   ```
+   Get-Content book\22-file-descriptors.md | Measure-Object -Line
+   ```
+
+### Por qué fallaba el enfoque anterior
+
+Un archivo de capítulo tiene ~1200-1500 líneas con:
+- Bloques de código C con backticks triples (```` ```c ````) que el parser JSON confunde
+- Strings con comillas escapadas (`\"`) que colisionan con las del string JSON
+- Caracteres especiales como `$` en ejemplos de shell o `\n` en strings C
+
+Con chunks de ≤ 600 líneas, el contenido cabe en un string JSON sin romper el parseo.
+
+### Regla práctica
+
+> **Nunca escribir más de 600 líneas de una sola vez con `write`.** Si el contenido total es mayor,
+> usar `write` para la primera parte y `edit` sucesivo para el resto.