Tasks as Code: Verplaats je tickets naar de repository

AI-coding agents werken het beste wanneer alles wat ze nodig hebben in de repository staat, aangezien de code hun 'source of truth' is. Toch houden de meeste teams taken en vereisten nog steeds bij in tools zoals Jira of Redmine die buiten de repository staan. Het opslaan van taken als eenvoudige Markdown-bestanden verandert dit: agents kunnen de vereisten en de code op één plek lezen, en elke wijziging in een taak is geversioneerd en controleerbaar, net als elke andere commit. De Docs as Code-benadering biedt al het blauwdruk voor deze evolutie, en een webinterface die synchroniseert met Git kan technische schrijvers en product owners betrokken houden zonder dat zij gedwongen worden de command line te gebruiken.

Docs as Code

Documentatie is al overgestapt van aparte documentatiesoftware naar Markdown-bestanden in een Git-repository. Tegenwoordig bevindt dit zich vaak in een /docs-map binnen de code-repository. Deze praktijk staat bekend als Docs as Code of Docs Like Code.

Met AI-coding agents wordt deze aanpak nog nuttiger. Agents kunnen documentatie lezen om een systeem te begrijpen, wijzigingen in de code aanbrengen en de relevante documentatie bijwerken als onderdeel van dezelfde workflow. Documentatie wordt hiermee een integraal onderdeel van softwareontwikkeling in plaats van een aparte activiteit die achteraf moet worden voltooid.

Tasks as Code

Dezelfde principes zijn van toepassing op development-taken. Wanneer taken worden opgeslagen als Markdown-bestanden, kunnen agents ze direct lezen, gebruiken om hun werk te plannen en de resultaten in diezelfde bestanden vastleggen. Git houdt de geschiedenis van de taken toegankelijk, naast de geschiedenis van de software en documentatie.

Dit idee komt al terug in Spec-Driven Development (SDD). SDD gebruikt specificaties in Markdown om het beoogde gedrag te definiëren voordat een AI-agent dit implementeert. Een taakbestand kan een soortgelijk doel dienen, hoewel het detailniveau afhangt van het werk. Een kleine onderhoudstaak heeft wellicht alleen een korte beschrijving nodig, terwijl een complexe feature acceptatiecriteria, technische beslissingen, afhankelijkheden en testvereisten kan vereisen.

SDD wordt vaak ondersteund door speciale tools zoals Spec Kit, maar een eenvoudigere aanpak is voldoende om te beginnen: behandel het taakbestand zelf als de specificatie. Dat maakt de overgang gemakkelijker, omdat er niets anders nodig is dan Git en een agent.

Hier is een eenvoudige workflow in vijf stappen:

1. Beschrijf de taak. Schrijf een korte beschrijving van de wijziging of feature die moet worden geïmplementeerd.
2. Analyseer de vereisten. De agent leest de taak en onderzoekt de relevante code en documentatie.
3. Maak een implementatieplan. De agent voegt een voorgestelde oplossing toe en identificeert de wijzigingen die hij wil aanbrengen.
4. Beoordeel en keur goed. Een developer beoordeelt het plan en geeft toestemming voor de implementatie.
5. Implementeer en rapporteer. De agent wijzigt de code, werkt de documentatie bij waar nodig en voegt een implementatierapport toe aan het taakbestand.

De taakbeschrijving, het implementatieplan en het rapport blijven samen in één bestand. Dit maakt het eenvoudig om de oorspronkelijke vereisten te controleren, de geplande aanpak te begrijpen en te zien wat de agent daadwerkelijk heeft gewijzigd.

De goedkeuringsstap zorgt ervoor dat mensen de controle houden. De agent gaat niet direct van de taakbeschrijving naar de implementatie; het plan kan eerst worden beoordeeld en gecorrigeerd.

Een voorbeeldopzet

In mijn eigen opzet gebruik ik drie aparte Git-repositories:

• Code
• Documentatie
• Taken

Documentatie en taken hebben vaak verschillende toegangsvereisten. Documentatie kan openbaar zijn, terwijl taken gevoelige informatie kunnen bevatten over onvoltooide beveiligingsfixes, interne planning of features die nog niet zijn aangekondigd. Aparte repositories maken het mogelijk om de toegang onafhankelijk te configureren en taken privé te houden.

Lokaal cloneert een developer de documentatie- en taakrepositories in mappen binnen de code-repository. Beide mappen staan in het .gitignore-bestand van de code-repository, zodat de hoofdrepository hun inhoud niet bijhoudt. Elke gecloonde repository behoudt zijn eigen Git-geschiedenis en kan onafhankelijk worden gecommit, gepusht en gesynchroniseerd.

/code-repo
  /src
  /tests
  /docs                 # Aparte documentatie-repository
    /user-guides
    /admin-manuals
    /developer-docs
  /tasks                # Aparte privé taak-repository
    /release-123
      task-551-something-descriptive.md
      task-552-something-descriptive.md
  .gitignore            # Sluit docs en tasks uit

Alle informatie is nu beschikbaar voor een lokale coding assistant zoals Claude Code of OpenCode. Bij het implementeren van een taak leest de agent de taak, analyseert de code, implementeert de wijziging en werkt de relevante documentatie bij. Het implementatierapport blijft bij de taak, terwijl de werkelijke code-wijzigingen worden geregistreerd in de code-repository. Door naar de bestandsnaam van de taak te verwijzen in een Git-commit, wordt de implementatie gekoppeld aan de oorspronkelijke vereisten.

Wanneer taken zijn georganiseerd in release-mappen, kan de agent voltooide taken en de Git-geschiedenis gebruiken om het changelog en de release notes op te stellen. Dezelfde informatie kan helpen bij het identificeren van documentatie die moet worden bijgewerkt.

Een interface toevoegen

Git en een AI-coding agent zijn voldoende om deze workflow uit te voeren. Een browsergebaseerde interface voegt een andere manier toe om bestanden te doorbladeren, te bewerken en te organiseren, zonder Git als onderliggend versiebeheersysteem te vervangen.

Typemill kan inhoud synchroniseren met Git-repositories. Omdat het meerdere repositories ondersteunt, kun je een apart project configureren voor privé-taken naast het documentatieproject. Hierdoor kun je beide beheren via dezelfde interface, ook al staat de inhoud in aparte repositories.

Dezelfde bestanden zijn toegankelijk via drie interfaces:

1. In een IDE: Developers en AI-agents werken direct met de lokale repositories.
2. Op GitHub: Bijdragers kunnen wijzigingen beoordelen en bestanden bewerken via de repository-interface.
3. In een browser: Typemill biedt een interface voor het lezen en beheren van taken en documentatie.

Elke interface dient een ander doel. De IDE ondersteunt de implementatie, GitHub zorgt voor samenwerking op repository-niveau, en het CMS biedt een content-interface en publicatieplatform voor niet-technische gebruikers zoals product owners en technische schrijvers. Git blijft verantwoordelijk voor de versiegeschiedenis en synchronisatie.

Deze opzet illustreert een belangrijk onderscheid: de interface hoeft niet de eigenaar van de data te zijn. Het biedt een handige manier om te werken met bestanden die draagbaar blijven en toegankelijk zijn voor andere tools.

Lokaal, privé en bestandsgebaseerd

Typemill en een flat-file CMS zijn slechts één snelle optie om met deze workflow te experimenteren. Elke opzet die Markdown-bestanden in Git bewaart en agents toegang geeft tot deze bestanden zal werken; je kunt zelfs beginnen met niets meer dan een map met taakbestanden.

De interessantere vraag is wat er daarna gebeurt. Zodra taken de documentatie in de repository volgen, zullen we nieuwe software en interfaces zien die voor dit model zijn ontworpen. Developers, product owners en technische schrijvers zullen een gedeelde plek nodig hebben om te werken, en agents zullen deel uitmaken van die workflow. Het is bovendien een open vraag welke functies van huidige ticketsystemen nog nodig zijn: toewijzingen, reacties, kanban-borden, sprints? Waarschijnlijk niet allemaal als agents het meeste werk doen.

Op basis van de bovenstaande opzet zijn dit de eigenschappen waar ik naar zou zoeken:

• Git-native: Taken en specificaties zijn leesbare bestanden die via Git worden beheerd en verbonden zijn met de code en documentatie.
• Documentatie en taken samen: Eén interface biedt toegang tot zowel documentatie als taakbeheer.
• Bestandsgebaseerd: Markdown blijft leesbaar, draagbaar en onafhankelijk van een specifiek platform.
• Self-hosted: Teams behouden de controle over hun data, privacy en infrastructuur.
• Open voor AI-diensten: Developers kunnen hun favoriete AI-provider kiezen, en de interface moet generieke integraties bieden in plaats van gebruikers vast te pinnen aan één enkele service.