Voordat CodeLynq code schrijft, legt het vast hoe het de klus gaat aanpakken: het technisch ontwerp, of TSD. Jij leest het, verbetert het en keurt het goed. Er wordt niets gebouwd voordat een TSD is goedgekeurd - dit is het moment om een misverstand op te vangen, nu het nog niets kost.
Wat er in een TSD staat
Open de taak en ga naar het tabblad Specificatie. Onder Technisch ontwerp (TSD) vind je:
- Functionele interpretatie - hoe het verzoek begrepen wordt.
- Acceptatiecriteria - één per regel: wat er waar moet zijn om de wijziging als klaar te zien.
- Technische aanpak - de oplossing en hoe die gebouwd wordt.
- Betrokken componenten - modules, services en bestanden die veranderen.
- Impact op datamodel - databasewijzigingen en migraties.
- Impact op API - nieuwe of gewijzigde endpoints.
- Risico's en maatregelen - wat er mis kan gaan, en hoe dat wordt afgevangen.
- Teststrategie - welke tests aantonen dat het werkt.
- Aannames - wat er is aangenomen waar de taak niets over zei.
Eerst de opdracht bespreken
Zolang de TSD nog leeg is, staat op het tabblad Specificatie het blok Eerst de opdracht bespreken. Klik op Eerst bespreken om de taak met de AI door te nemen voordat er iets wordt geschreven: wat moet er gebouwd worden, en waar. Klik op Laat de AI zijn vragen stellen om hem te laten beginnen met hoe hij de taak begrijpt, of typ zelf wat je voor ogen hebt.
Bij een project met meerdere repositories staat het gesprek standaard open. De AI kent de repositories van het project en vraagt welke de taak raakt en wat er in elk verandert.
Is er niets belangrijks meer open, dan zegt de AI dat en wordt TSD opstellen uit dit gesprek uitgelicht. Klik erop. De TSD wordt opgesteld uit wat jullie hebben afgesproken. Had de taak nog geen repositories geselecteerd, dan worden de repositories die in de TSD staan voor de taak geselecteerd, zodat de run in de juiste repositories werkt. Een selectie die je zelf hebt gemaakt, blijft altijd staan.
Zodra de TSD er is, wordt hetzelfde gesprek de review ervan: zie hieronder.
De TSD schrijven of laten voorstellen
- Klik op TSD voorstellen om CodeLynq alle velden te laten invullen, op basis van de taak, de context van het project en de code. Die knop staat er zolang alle velden nog leeg zijn.
- Of vul de velden zelf in.
Loop elk veld na, pas aan wat niet klopt en klik op Concept opslaan. Let vooral op Functionele interpretatie en Aannames: kloppen die niet, dan klopt de rest ook niet.
De review met je technical lead
Een voorgestelde TSD komt niet alleen. Zoals een technical lead die een ontwerp overdraagt, zegt de AI in een paar regels hoe hij het zou bouwen en vraagt hij je de keuzes te bevestigen die hij moest maken: wat er binnen de opdracht valt, hoe randgevallen zich gedragen, wat er met bestaande data gebeurt. Boven de velden laat Review met je technical lead zien hoeveel er wachten, en ook bij Goedkeuren staat het zolang er vragen open zijn.
- Klik op Vragen beantwoorden. Elke vraag heeft voorgestelde antwoorden, met de aanbeveling van de AI vooraan, gemarkeerd als aanbevolen. Bij één vraag verstuurt een klik op een antwoord het meteen; bij meerdere kies je er per vraag een en klik je op Antwoorden versturen. Met Anders… typ je je eigen antwoord.
- De AI zegt wat je antwoorden veranderen en vraagt wat er nog open is. Je kunt ook zelf alles vragen: waarom hij voor een aanpak koos, wat er mis kan gaan, of het klaar is om te bouwen.
- Is er niets belangrijks meer open, dan zegt de AI dat en wordt de balk met TSD bijwerken met deze keuzes groen. Klik op de knop: de velden worden herschreven met wat jullie hebben afgesproken, wijzigingen die je nog niet had opgeslagen blijven behouden, en het gesprek laat zien wat er veranderd is. Een ingediende TSD gaat terug naar concept, omdat hij niet meer zegt wat er is ingediend.
Je kunt je volgende bericht al typen terwijl de AI nog antwoordt. Hetzelfde gesprek staat op het tabblad Review van de taak, waar je ook zelf een review start met Review starten.
Indienen en goedkeuren
Een TSD heeft drie statussen: Concept, Ingediend en Goedgekeurd.
- Klik op Indienen voor validatie als het concept klaar is. De taak staat nu op Wacht op goedkeuring en verschijnt in de Inbox.
- Een lid van het project bekijkt hem en klikt op TSD goedkeuren.
Schrijf en keur je hem zelf goed? Opslaan en goedkeuren slaat op, dient in en keurt goed in één stap.
Vink vóór het goedkeuren Run starten bij goedkeuring aan om meteen een run te starten. Anders start je die later via het tabblad Runs - zie Runs.
Een ingediende of goedgekeurde TSD is alleen-lezen. Onderaan zie je wanneer hij is ingediend en goedgekeurd.
Een ingediende of goedgekeurde TSD opent als Samenvatting - het doel, de Acceptatiecriteria als checklist, de risico's en wat is aangenomen (bevestig dat vóór goedkeuring) - met de volledige tekst eronder en de technische secties onder Technische details. Vergelijken met v… laat zien wat er sinds de vorige versie is veranderd, en Downloaden als Markdown bewaart de spec als bestand om te delen. Onder de review staan de besluiten die je hebt bevestigd, en hoeveel vragen nog open zijn.
Gaat het om een wijziging die mensen zien, laat CodeLynq dan eerst de schermen ontwerpen: wie de TSD goedkeurt, keurt dan ook de getoonde mockup goed, en de run bouwt ernaar. Zie Mockups.
Een wijziging aanvragen op een gebouwde taak
Heeft de taak een open pull request en wil je iets anders, gebruik dan Wijziging aanvragen op het tabblad Overzicht van de taak. Beschrijf de wijziging en klik op Verwerken in de TSD. Op het tabblad Runs kun je ook feedback aanvinken en op Verwerken als wijziging in de TSD klikken.
- De AI schrijft een nieuwe versie van de TSD met de wijziging erin verwerkt. Een geel blok boven de velden toont je verzoek en Wat er verandert ten opzichte van wat er gebouwd is.
- Controleer de velden, vink Wijziging bouwen op de bestaande branch aan en keur goed.
- Een nieuwe run checkt de branch van de pull request uit, bouwt de wijziging bovenop het werk dat er al staat en pusht naar dezelfde branch. De open pull request wordt bijgewerkt; er komt geen nieuwe.
Op een eigen runner is daarvoor runner 1.9.0 of nieuwer nodig. Zie Eigen runners.
Een goedgekeurde TSD wijzigen
Klik bij een goedgekeurde TSD op Nieuwe versie aanmaken. Die kopieert hem naar een nieuw concept dat je zoals eerder bewerkt en goedkeurt. Eerdere versies blijven beschikbaar via de versiekeuze bovenaan het tabblad Specificatie, met hun datum.
Onderweg goedkeuren
In de mobiele app kun je de laatste TSD van een taak lezen en goedkeuren, met of zonder meteen een run te starten.
Tips
- Een goede taakbeschrijving scheelt een correctieronde. Noem beperkingen en wat er buiten de scope valt.
- Mist de TSD context die voor elke taak geldt, zet die dan in de context en conventies van het project of in het geheugen van de codebase, in plaats van elke specificatie te corrigeren.
- Meerdere branches? Controleer of de aanpak rekening houdt met de verschillen ertussen. Zie Op meerdere branches tegelijk werken.