Hoe je elke externe repository omzet in een interactieve cursus

Onlangs betrapte ik mezelf op de gedachte: code schrijven met neurale netwerken is zo gemakkelijk geworden dat het gemakkelijk is om in de val te lopen. Je drukt op een paar knoppen, de agent genereert een werkend prototype van een paar duizend regels, alles lijkt goed te werken, maar er is een leegte in je hoofd. Wanneer de app crasht met een vreemde fout of vastloopt in een eindeloze lus van fixes, verdwijnt de magie. Je moet in de code duiken en uitzoeken hoe deze stack eigenlijk werkt.

Meestal open je bestanden één voor één, probeer je een call graph in je hoofd te bouwen en verspil je veel tijd. Het codebase-to-course project van ontwikkelaar Zara biedt een andere aanpak. Het is een extensie (skill) voor Claude Code die elk lokaal project neemt en het assembleert tot een mooie interactieve single-page cursus in één HTML-bestandsformaat.

Voor wie is het en waarom

De auteur van het project richt zich op zogenaamde vibe coders. Dit zijn mensen die software bouwen via tekstprompts zonder formele informatica-opleiding. Wanneer de applicatie werkt, hebben ze geen saaie theorie van universiteitshandboeken nodig. Ze moeten praktische zaken begrijpen:

• Hoe je AI beter kunt aansturen en verstandige architectuurbeslissingen kunt nemen.
• Hoe je hallucinaties en slechte patronen in gegenereerde code vroegtijdig kunt herkennen.
• Welke bestanden je eerst moet controleren wanneer de assistant vastloopt.
• Hoe je dezelfde taal spreekt als engineers zonder je een buitenstaander te voelen.

De tool is echter niet alleen voor beginners. Als je snel moet opstarten met een onbekend open-source project of een nieuwe medewerker moet introduceren in de interne codebase van je bedrijf, zal zo'n interactieve handleiding uren handmatige analyse besparen.

Wat je krijgt

De skill produceert een zelfstandig HTML-document. Het heeft geen zware externe afhankelijkheden, vereist geen build-stap of lokale server. Open het bestand in een browser en begin direct met het leren van het project, zelfs zonder internettoegang.

De pagina bevat verschillende interessante mechanismen.

Synchrone code-naar-mens vertaling

Het scherm is verdeeld in twee delen. Links staat het originele codefragment uit de repository zonder vereenvoudigingen of inkortingen. Rechts staat een regel-voor-regel uitleg in gewone taal die beschrijft wat er gebeurt en waarom die regel bestaat.

Deze aanpak helpt om abstracte syntaxis te verbinden met de logica van de applicatie. Je ziet direct welk fragment event processing afhandelt en welk simpelweg de response formatteert.

Geanimeerde diagrammen en datastroomvisualisatie

In plaats van lange paragrafen die de architectuur beschrijven, genereert de cursus visuele blokken. Bijvoorbeeld een datatransferketen tussen componenten of een simulatie van service-naar-service dialoog.

De auteur heeft een duidelijke regel ingebouwd in het ontwerp: elk scherm moet minstens de helft aan visuele inhoud hebben, en tekstblokken mogen niet meer dan twee à drie zinnen bevatten. Als een verbinding kan worden getoond met een pijl of tijdlijn, wordt de tekst simpelweg niet geschreven.

Kennistoepassingstoetsen, geen geheugentoetsen

Typische quizzen in tutorials testen termijn memorisatie. Het concept hier is anders. Vragen simuleren echte engineering-taken.

Je wordt niet gevraagd "wat is een state manager." In plaats daarvan wordt gevraagd: "Een gebruiker meldde dat de filter reset bij het navigeren tussen pagina's. Welk bestand zou je eerst openen om wijzigingen aan te brengen?" Dit dwingt je om na te denken over de projectstructuur in plaats van mechanisch door opties te klikken.

Hover tooltips voor termen

Wanneer de tekst specifieke termen bevat zoals hydration, debounce of webhook, kun je er overheen hoveren om een korte uitleg te zien zonder pedante academische definities.

Het paginadesign is bewust uitgevoerd in warme tinten. Er zijn geen vertrouwde paarse gradaties en neon-gloed die bijna alle moderne AI-startups rommelig maken.

Hoe de skill intern werkt

De repository zelf is verrassend compact. Er is geen zware Python backend of complexe pipelines. Alle magie rust op duidelijke prompts en designsysteemspecificaties voor Claude Code:

codebase-to-course/
├── SKILL.md                          # Главные инструкции для агента
└── references/
    ├── design-system.md              # Токены стилей, сетка, типографика и цвета
    └── interactive-elements.md       # Паттерны квизов, анимаций и графики

Het SKILL.md bestand instrueert het model over de lesmethodologie. Het kernprincipe is een omkering van traditioneel leren: praktijk en een werkend project eerst, dan de mechanica-uitleg. De instructies verbieden het model ook strikt om code uit de repository te wijzigen of te vereenvoudigen. Cursusfragmenten moeten exact overeenkomen met de projectbestanden, zodat ontwikkelaars het project in een editor kunnen openen en direct het relevante fragment kunnen lokaliseren.

Bestanden in de references map bieden een kant-en-klaar componentframework in platte HTML, CSS en vanilla JavaScript. Dit stelt Claude in staat om een schone interface te genereren met soepel scrollen en responsive layout zonder elke keer het wiel opnieuw uit te vinden.

Hoe het te draaien op je project

Om de tool te gebruiken, heb je de command-line interface van Anthropic's Claude Code geïnstalleerd.

1. Kloon de repository of kopieer de projectmap naar de skills directory:

cp -r codebase-to-course ~/.claude/skills/

2. Navigeer naar een van de directories van je project in de terminal en start een Claude Code-sessie.

3. Schrijf een commando in natuurlijke taal:

Turn this codebase into an interactive course

Zinnen als "Leg deze codebase interactief uit" of "Leer me hoe deze code werkt" werken ook. De agent zal de repositorybestanden scannen, belangrijke knooppunten identificeren en een klaar HTML-bestand genereren in de rootmap.

Waar op te letten

Het idee van het verpakken van een architectuuruitleg in een zelfstandig interactief bestand ziet er heel fris uit. In slechts een paar dagen verzamelde het project meer dan vijfduizend sterren op GitHub, wat wijst op een hoge vraag naar tools die betekenisvol codebegrip mogelijk maken.

De belangrijkste beperking van het hulpprogramma komt neer op het contextvenster en de repositorygrootte. Bij projecten met enkele honderdduizenden regels kan het model fysiek niet alle verbindingen meenemen en zal het onvermijdelijk alleen focussen op de bovenste structuur of het entry point. Voor middelgrote bibliotheken, microservices, pet projects en typische fullstack-applicaties is dit echter een uitstekende manier om snel externe broncode te begrijpen. Probeer de skill te richten op een oud project dat je een tijdje niet hebt geopend — het resultaat zal je waarschijnlijk verrassen.