Saltar al contenido
hg.Héctor GarridoCiencia de datos · Estadística · Ingeniería de datos
← Volver al blog
Portafolio RAG

De GitHub Copilot a Claude Code: Automatizando la Documentación del Proyecto

Este artículo describe cómo automatizar la documentación de un proyecto usando Claude Code, explorando sus ventajas sobre GitHub Copilot. Se introduce el archivo `CLAUDE.md` para proporcionar contexto persistente al modelo, mejorando la comprensión del proyecto. Se detalla la creación de un management command de Django, `sync_dev_posts`, para sincronizar archivos `.md` con la base de datos y corregir automáticamente los links de navegación en los posts. Aprenderás a usar LLMs para automatizar tareas de documentación y mantener la consistencia entre el código y el contenido del blog.

De GitHub Copilot a Claude Code: Automatizando la Documentación del Proyecto

Por Qué Cambié de Copilot a Claude Code

Después de 18 posts documentando la construcción de este portafolio, el proceso de escritura seguía siendo manual. Venía usando GitHub Copilot en modo agente — que entiende contexto, navega archivos y puede ejecutar tareas multi-paso — y funcionaba bien para el desarrollo día a día. Pero quise probar Claude Code para ver qué ofrecía de diferente.

La diferencia principal resultó ser el archivo CLAUDE.md — un documento que vive en la raíz del proyecto y le da al modelo contexto persistente sobre la arquitectura, los comandos, las convenciones y el flujo de trabajo. Copilot en modo agente también lee archivos .md de instrucciones, pero CLAUDE.md se carga automáticamente en cada sesión sin necesidad de referenciarlo. En la práctica, eso significa que cada conversación arranca con el modelo ya sabiendo cómo está organizado el proyecto.

La primera sesión con Claude Code lo demostró: le pedí que verificara la fidelidad de los posts de desarrollo contra el estado real del proyecto usando git, y no solo lo hizo, sino que identificó qué commits estaban documentados y cuáles no.


CLAUDE.md: El Contexto Permanente del Proyecto

El primer paso fue crear CLAUDE.md con todo lo que un desarrollador nuevo necesitaría saber:

# CLAUDE.md
## Project Overview
Full-stack portfolio + technical blog + RAG chatbot...

## Common Commands
python manage.py runserver          # Dev server
python manage.py test --verbosity=2 # 65 backend tests
npm start                           # Frontend dev server

## Architecture
| Layer    | Technology                          |
|----------|-------------------------------------|
| Frontend | React 18 (CRA) + Material UI v5     |
| Backend  | Django 5.0.1 + DRF 3.14             |
| Database | SQLite (dev) / Neon PostgreSQL (prod)|
| AI/LLM   | Vertex AI (text-embedding-005, gemini-2.5-flash) |

## Key Architectural Patterns
- RAG Engine: embeddings como pickle en BinaryField...
- Post lookup por slug, no por ID numérico...
- Frontend: React.lazy code splitting...

La clave no es la extensión del archivo sino su especificidad. No es documentación genérica — es exactamente lo que el modelo necesita para tomar decisiones informadas: qué base de datos usar en dev vs prod, cómo se nombran las cosas, qué convenciones seguir (código en inglés, UI en español).


El Comando sync_dev_posts: De Archivos .md a la Base de Datos

El Problema

Los 18 posts de la serie de desarrollo vivían como archivos .md en docs/posts/desarrollo/, pero su contenido en la base de datos podía quedar desincronizado. Editar un post significaba: modificar el .md, luego ir al admin de Django, copiar el contenido, pegarlo, guardar. Un proceso propenso a errores y que desincentivaba las correcciones.

La Solución

Creé el management command sync_dev_posts que automatiza esto:

# blog_backend/blog/management/commands/sync_dev_posts.py
DOCS_DIR = Path(__file__).resolve().parents[4] / 'docs' / 'posts' / 'desarrollo'
CATEGORY_SLUG = 'rag-blog'

El comando recorre los archivos .md, extrae el número de serie del prefijo del nombre (01-xxx.md → series_order=1), busca el post correspondiente en la base de datos y compara el contenido:

python manage.py sync_dev_posts                # Preview (dry run)
python manage.py sync_dev_posts --apply        # Aplicar cambios
python manage.py sync_dev_posts --apply --post 5  # Solo el post #5

El modo preview muestra un resumen claro:

[OK]   #01 "Cómo Construí Mi Blog..." — sin cambios
[UPD]  #09 "Mejoras al Motor RAG..." - 300->308 lineas (+8)
[ERROR] #20 — No existe post con category="rag-blog", series_order=20

Cuando se ejecuta con --apply, actualiza el campo content y Django regenera content_html automáticamente en el save() (gracias a las extensiones codehilite + mdx_math configuradas en el modelo).


Corrección Automática de Links de Navegación

El Problema de los Links .md

Cada post cierra con links de navegación "Anterior" / "Siguiente" que originalmente apuntaban a archivos .md locales:

**Anterior:** [Migración de Cloud SQL a Neon: Cómo Ahorré $115/Año en 20 Minutos](https://hectorgarrido.cl/post/migracion-de-cloud-sql-a-neon-como-ahorre-115ano-en-20-minutos)
**Siguiente:** [Optimización de Rendimiento Frontend: Code Splitting, Pre-renderizado y Caché Docker](https://hectorgarrido.cl/post/optimizacion-de-rendimiento-frontend-code-splitting-pre-renderizado-y-cache-docker)

Esto funcionaba para lectura local, pero en producción los links debían apuntar a las URLs reales del blog usando los slugs de la base de datos.

La Solución: --fix-links y Corrección Automática

Agregué al comando sync_dev_posts la capacidad de construir un mapa de links consultando la DB:

def _build_link_map(self):
    """Build mapping of .md filenames → (production URL, post title)."""
    link_map = {}
    posts = Post.objects.filter(category__slug=CATEGORY_SLUG)
    for post in posts:
        for md in DOCS_DIR.glob(f'{post.series_order:02d}-*.md'):
            link_map[md.name] = (f'{BASE_URL}/{post.slug}', post.title)
            break
    return link_map

El mapeo convierte: - 08-migracion-neon-cloud-sql.md → https://hectorgarrido.cl/post/migracion-de-cloud-sql-a-neon-como-ahorre-115ano-en-20-minutos

Y el método _fix_nav_links reemplaza tanto la URL como el texto visible del link con el título real del post:

**Anterior:** [Migración de Cloud SQL a Neon: Cómo Ahorré $115/Año en 20 Minutos](https://hectorgarrido.cl/post/migracion-de-cloud-sql-a-neon-como-ahorre-115ano-en-20-minutos)

Esto se aplica de dos formas: 1. --fix-links --apply: Corrige los archivos .md en disco directamente 2. Sync normal: Aplica la corrección al vuelo antes de comparar y guardar en la DB, sin necesidad de modificar los archivos fuente

Los 18 archivos fueron corregidos de una vez: cada link ahora apunta a la URL de producción con el slug correcto y muestra el título completo del post.


El Flujo de Trabajo: Commit → Documentación

La parte más valiosa de esta sesión no fue el código en sí, sino el establecimiento de un flujo de trabajo permanente. En CLAUDE.md quedó una instrucción que dice:

Después de completar un cambio relevante, preguntar: "¿Realizo commit + push + documentación?"

La idea es simple: cada commit con un cambio significativo es insumo para los posts de la serie de desarrollo. En lugar de intentar reconstruir semanas de trabajo de memoria, los commits van documentando incrementalmente lo que se hizo y por qué. Cuando se acumula material suficiente, se propone un nuevo post.

Este post es el primer producto de ese flujo.


Lo Que Cambió en Esta Sesión

En una sola sesión con Claude Code:

  1. Verificación con git: Revisé que los 18 posts existentes reflejaran fielmente el estado del proyecto comparando commits de código vs commits de documentación.

  2. sync_dev_posts.py: Creé el management command que sincroniza archivos .md con la base de datos, con preview, aplicación selectiva por post, y corrección automática de links.

  3. Corrección de 18 archivos: Todos los links de navegación pasaron de apuntar a .md locales a URLs de producción con slugs reales de la DB y títulos completos.

  4. Corrección de voz narrativa: El post 18 tenía una sección que leía como un reporte de tercero ("El Reporte de Usuario") cuando fui yo quien detectó los bugs. Corregido a primera persona.

  5. Flujo commit+documentación: Instrucción permanente en CLAUDE.md para que cada cambio relevante se documente incrementalmente.


Lecciones

1. El contexto persistente transforma la asistencia de IA. Tanto Copilot (modo agente) como Claude Code entienden contexto y navegan el proyecto. La diferencia está en cómo se gestiona ese contexto: CLAUDE.md se carga automáticamente en cada sesión, lo que elimina la fricción de "ponerse al día" al inicio de cada conversación.

2. La documentación debe ser un subproducto del trabajo, no una tarea separada. El flujo commit → documentación hace que escribir posts sea compilar lo que ya se hizo, no recordar lo que se hizo hace semanas. Los commits son el borrador; el post es la edición.

3. Los links rotos son deuda técnica invisible. Los 18 posts tenían links de navegación que apuntaban a archivos .md que no existían en producción. Nadie se quejó porque probablemente nadie los usaba — pero si alguien los hubiera clickeado, la experiencia habría sido un 404. La corrección automática previene que esto se repita con futuros posts.

4. Automatizar lo repetitivo libera energía para lo creativo. Sin sync_dev_posts, cada edición de un post requería copiar-pegar manualmente entre el .md y el admin de Django. Con el comando, puedo editar el .md con confianza y sincronizar con un solo comando. La fricción baja, la frecuencia de mejoras sube.


Anterior: Bugs de Producción: Cold Start, el Cuerpo Vacío del SPA y la configuración de nginx