De auteur reflecteert op het gebruik van Implementation Decision Records (IDR's), een variant van Architecture Decision Records. Hij stelt vast dat IDR's vaak weinig waarde toevoegen wanneer ze door LLM's worden gegenereerd op basis van vage prompts, omdat ze dan vaak slechts een tekstuele herhaling van de code-wijzigingen (de diff) zijn.
Het belangrijkste inzicht is dat een IDR alleen effectief is als deze zich richt op de intentie en de specifieke beslissingen die tot een oplossing hebben geleid. Een kwalitatieve IDR bevat:
- Een duidelijke probleemstelling (de 'irritatie').
- Concrete doelen en expliciete niet-doelen.
- Een voorgestelde oplossing zonder te diep in implementatiedetails te treden.
Door deze structuur aan te houden, dienen IDR's als betere guard-rails voor LLM's en als waardevolle, compacte documentatie voor ontwikkelaars die later in de repository kijken.
IDR's als verslagen van intentie
Ter herinnering: ik heb ze gecreëerd met twee hoofddoelen:
- Om betere resultaten uit LLM's te halen.
- Om een duurzaam verslag te bieden van een beslissing die is genomen tijdens de implementatie van een functie.
Ik ben erachter gekomen dat een LLM, wanneer het wordt overgelaten aan zichzelf met een vage prompt, vaak simpelweg probeert het record in te vullen met een tekstuele beschrijving van wat het sowieso al van plan was te implementeren [1]. Dit maakt ze vrij verliesgevend als verslag van intentie (het is in feite niet veel beter dan een diff, en wellicht zelfs slechter) en ik ben er inmiddels sceptisch over of het de output significant verbetert.
In het beste geval stellen ze je in staat om het model naar een beter resultaat te sturen voordat er te veel code is geschreven.
Een goed voorbeeld hiervan is onderstaand fragment, waarin ik de agent vroeg om repo-parser bij te werken zodat DuckDB wordt gebruikt voor de intermediate representation:
***
# DuckDB-serialisatie Eigenaar: Will Lachance <[email protected]>
## Overzicht
### Probleemstelling repo-parser extraheert metadata en structuur uit repositories naar een in-memory Resource-boom, maar deze efemere representatie moet voor elke consument opnieuw worden aangemaakt. We hebben een persistent, querybaar serialisatieformaat nodig waardoor meerdere tools de geëxtraheerde metadata kunnen consumeren zonder de repository opnieuw te hoeven scannen.
### Context <zeer langdradige, bijna onbegrijpelijke LLM-context>
***
De probleemstelling is niet verschrikkelijk, maar wel vrij vaag. Ik denk niet dat het de agent echt een doel gaf, anders dan "gebruik DuckDB op een bepaalde manier" om een ander mechanisme te vervangen.
Hoewel het resultaat acceptabel was, vraag ik me af of de IDR in dit proces veel waarde heeft toegevoegd. Het helpt zeker niet om uit te leggen waar de DuckDB-output van repo-parser daadwerkelijk goed voor is (een BM25-zoekindex van de inhoud van een repository, mogelijk TUI-zoektools). Het is bovendien zeker niet iets wat ik later opnieuw wil lezen; ik krimpt nu al ineen als ik ernaar kijk.
Wat ik me steeds meer realiseer, is dat een IDR alleen echt effectief is als deze telkens terugkeert naar de intentie en de beslissingen die zijn genomen om die intentie te ondersteunen. Zonder dit is het slechts een langdradige manier om de diff in mensentaal te herhalen.
Ik ben veel tevredenere met dit voorbeeld:
***
# Publiceren naar PyPI via GitHub Actions Eigenaar: Will Lachance <[email protected]>
## Overzicht
### Probleemstelling repo-parser-pakketten kunnen momenteel alleen handmatig naar PyPI worden gepubliceerd, wat tijdrovend en foutgevoelig is en minder veilig dan wanneer dit via GitHub Actions gebeurt.
### Context (indien nodig) (Leeg)
### Doelen
- Het publiceren van nieuwe releases vergemakkelijken.
- De beveiliging verbeteren.
### Niet-doelen
- Het automatiseren van versie-verhogingen (dit vereist nog steeds een aparte commit om de versie te verhogen).
### Voorgestelde oplossing Gebruik de idiomatische best practice methode volgens de officiële packaging-gids: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
In algemene zin betekent dit het toevoegen van een nieuwe GitHub-workflow die uploads naar PyPI koppelt aan nieuwe releases.
## Aanvullende literatuur (indien nodig)
***
De probleemstelling beschrijft hier de "irritatie" die mij ertoe aanzette om in te grijpen. De doelen, niet-doelen en de oplossing zijn kort, krachtig en leggen het eindresultaat uit zonder in implementatiedetails te treden. Wanneer ik later terugkijk naar een repository, is dit het soort informatie dat ik wil zien.
Bonus: bij het gebruik van een LLM biedt dit duidelijkere kaders (guard-rails). Elke zin draagt bij aan het sturen van het gedrag richting het gewenste resultaat, in plaats van een set instructies te zijn die het model verkeerd zou kunnen interpreteren.
Als ik meer detail nodig heb, kijk ik gewoon naar de diff.
***
[1] LLM's doen dit ook als je ze vraagt een commit-bericht te schrijven zonder strikte kaders.
IDR's als verslagen van intentie
Ter herinnering: ik heb ze gecreëerd met twee hoofddoelen:
- Om betere resultaten uit LLM's te halen.
- Om een duurzaam verslag te bieden van een beslissing die is genomen tijdens de implementatie van een functie.
Ik ben erachter gekomen dat een LLM, wanneer het wordt overgelaten aan zichzelf met een vage prompt, vaak simpelweg probeert het record in te vullen met een tekstuele beschrijving van wat het sowieso al van plan was te implementeren [1]. Dit maakt ze vrij verliesgevend als verslag van intentie (het is in feite niet veel beter dan een diff, en wellicht zelfs slechter) en ik ben er inmiddels sceptisch over of het de output significant verbetert.
In het beste geval stellen ze je in staat om het model naar een beter resultaat te sturen voordat er te veel code is geschreven.
Een goed voorbeeld hiervan is onderstaand fragment, waarin ik de agent vroeg om repo-parser bij te werken zodat DuckDB wordt gebruikt voor de intermediate representation:
***
# DuckDB-serialisatie Eigenaar: Will Lachance <[email protected]>
## Overzicht
### Probleemstelling repo-parser extraheert metadata en structuur uit repositories naar een in-memory Resource-boom, maar deze efemere representatie moet voor elke consument opnieuw worden aangemaakt. We hebben een persistent, querybaar serialisatieformaat nodig waardoor meerdere tools de geëxtraheerde metadata kunnen consumeren zonder de repository opnieuw te hoeven scannen.
### Context <zeer langdradige, bijna onbegrijpelijke LLM-context>
***
De probleemstelling is niet verschrikkelijk, maar wel vrij vaag. Ik denk niet dat het de agent echt een doel gaf, anders dan "gebruik DuckDB op een bepaalde manier" om een ander mechanisme te vervangen.
Hoewel het resultaat acceptabel was, vraag ik me af of de IDR in dit proces veel waarde heeft toegevoegd. Het helpt zeker niet om uit te leggen waar de DuckDB-output van repo-parser daadwerkelijk goed voor is (een BM25-zoekindex van de inhoud van een repository, mogelijk TUI-zoektools). Het is bovendien zeker niet iets wat ik later opnieuw wil lezen; ik krimpt nu al ineen als ik ernaar kijk.
Wat ik me steeds meer realiseer, is dat een IDR alleen echt effectief is als deze telkens terugkeert naar de intentie en de beslissingen die zijn genomen om die intentie te ondersteunen. Zonder dit is het slechts een langdradige manier om de diff in mensentaal te herhalen.
Ik ben veel tevredenere met dit voorbeeld:
***
# Publiceren naar PyPI via GitHub Actions Eigenaar: Will Lachance <[email protected]>
## Overzicht
### Probleemstelling repo-parser-pakketten kunnen momenteel alleen handmatig naar PyPI worden gepubliceerd, wat tijdrovend en foutgevoelig is en minder veilig dan wanneer dit via GitHub Actions gebeurt.
### Context (indien nodig) (Leeg)
### Doelen
- Het publiceren van nieuwe releases vergemakkelijken.
- De beveiliging verbeteren.
### Niet-doelen
- Het automatiseren van versie-verhogingen (dit vereist nog steeds een aparte commit om de versie te verhogen).
### Voorgestelde oplossing Gebruik de idiomatische best practice methode volgens de officiële packaging-gids: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
In algemene zin betekent dit het toevoegen van een nieuwe GitHub-workflow die uploads naar PyPI koppelt aan nieuwe releases.
## Aanvullende literatuur (indien nodig)
***
De probleemstelling beschrijft hier de "irritatie" die mij ertoe aanzette om in te grijpen. De doelen, niet-doelen en de oplossing zijn kort, krachtig en leggen het eindresultaat uit zonder in implementatiedetails te treden. Wanneer ik later terugkijk naar een repository, is dit het soort informatie dat ik wil zien.
Bonus: bij het gebruik van een LLM biedt dit duidelijkere kaders (guard-rails). Elke zin draagt bij aan het sturen van het gedrag richting het gewenste resultaat, in plaats van een set instructies te zijn die het model verkeerd zou kunnen interpreteren.
Als ik meer detail nodig heb, kijk ik gewoon naar de diff.
***
[1] LLM's doen dit ook als je ze vraagt een commit-bericht te schrijven zonder strikte kaders.
Groetjes,