AnswersPublished15 sources
Houd AI-agentprojecten overzichtelijk zonder tests en documentatie overboord te zetten
Bewaar tests die blijvende kwaliteitscontroles bieden; behandel eenmalige diagnostiek en validatiebestanden als tijdelijke materialen. Maak onderscheid tussen wat in de repository staat en wat met een installatie wordt verspreid: dat zijn verschillende grenzen.
Gepubliceerd doorAfbeeldingen gegenereerd met GPT Image 2
Research answer
Key takeaways
- Bewaar tests die blijvende kwaliteitscontroles bieden; behandel eenmalige diagnostiek en validatiebestanden als tijdelijke materialen.
- Maak onderscheid tussen wat in de repository staat en wat met een installatie wordt verspreid: dat zijn verschillende grenzen.
- Laat documenten elk een eigen functie vervullen en geef het model standaard alleen de informatie die voor de taak nodig is.
- De onderbouwing voor deze aanbevelingen is gedeeltelijk: niet alle aangekondigde bronnen zijn onderzocht en er zijn geen tests opnieuw uitgevoerd.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/oBMfTzLzQzYo7VcXQdEGj2yQgAw1/images/73E9D63489E02AC46209/BEDABC175BE8FCADFC63.png)
AI Prompt
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"两个痛点都适合纳入 V4 的“产物生命周期背压”，但不应简化成“测试全部不提交”或“文档全部合并”。建议保留长期质量资产，隔离一次性验证材料，并分别控制仓库维护、安装分发和模型上下文。\n\n本次交付为阶段性调研：仓库静态证据、Geoffrey Huntley 的作者资料及部分学术资料已取得；Python 官方布. Topic tags: general web, openai, llm, agents, ai. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts with fa
De kern: beheer de levenscyclus van bestanden
Bij het opruimen van een AI-agentproject is de verleiding groot om tests uit de repository te halen of alle documentatie in één bestand te zetten. Dat kan het werkelijke probleem missen. Een duurzamere aanpak is onderscheid maken tussen blijvende kwaliteitscontroles, eenmalige validatie, documentatie en bestanden die met een installatie worden verspreid.
Dit is een tussentijdse analyse. Er is statisch naar de repository gekeken en er zijn bronnen van Geoffrey Huntley en enkele academische publicaties meegenomen. Het onderzoek naar de officiële Python-richtlijnen en naar X, Reddit, Hacker News en Lobsters is niet afgerond. De conclusies zijn daarom geen volledige inventarisatie. De tests zijn in deze analyse ook niet opnieuw uitgevoerd.
Tests: isoleer tijdelijk werk, niet de kwaliteitsbewaking
Wat de repository laat zien
De CI-configuratie gebruikt een centrale testmap, tests/, met onder meer controles voor configuratiecontracten, installatie en bescherming van assets. Alleen het uiterlijk van die map is geen reden om de tests als overbodig of tijdelijk te bestempelen. Hun onderhoudswaarde is hier niet afzonderlijk beoordeeld.
De .gitignore-regels sluiten bepaalde sandbox-, cache- en tijdelijke bestanden uit. Ze noemen echter niet expliciet de bestaande gebieden voor conceptbestanden en validatie-uitvoer. Dat die mappen bestaan, bewijst niet dat de inhoud door Git wordt bijgehouden; de indexstatus is niet gecontroleerd.
Ook repositorybeheer en installatie zijn niet hetzelfde. Het updateproces werkt de repository bij, terwijl de verzameling van bronbestanden de geselecteerde suite leest. De verzamelcode neemt gewone bestanden uit de suite recursief mee en zet die om in invoer voor de plug-ininstallatie [scripts/deployment_source.py:81]. Daaruit volgt een risico: tijdelijk materiaal dat per ongeluk in een suite-map staat, kan worden verspreid. Er is geen bewijs dat dit nu daadwerkelijk gebeurt.
Deel bestanden in naar functie
| Soort bestand | Advies voor versiebeheer | Advies voor indeling en verspreiding |
|---|---|---|
| Langdurig bruikbare regressie-, contract- en noodzakelijke integratietests | Bewaar en onderhoud ze samen met de implementatie | Volg de conventies van de taal en het project; neem ze standaard niet op in het runtime-installatiepakket |
| Eenmalige diagnostiek, validatiescripts en experimentele invoer | Houd ze standaard lokaal en commit ze niet automatisch | Gebruik een toegestane tijdelijke werkmap en plaats ze niet in een map met suite-assets |
| Logs, coveragebestanden en uitvoer van controles | Neem ze standaard niet op in broncodecommits; bewaar bewijs alleen waar dat nodig is | Houd ze gescheiden van testcode en buiten installatiepakketten |
Dit zijn voorstellen, geen regels die al zijn ingevoerd.
De officiële Go-handleiding plaatst testbestanden naast de code die ze testen. Het is dus geen goede algemene regel om alle Go-unit-tests naar één centrale map te verplaatsen.15 In deze repository bestaat voor Python al een centrale testindeling. Dat is een bruikbaar vertrekpunt, maar het beschikbare officiële bronnenmateriaal volstaat niet om daaruit een algemene aanbeveling voor Python-projecten af te leiden.
De juiste oplossing hangt af van wat je wilt opruimen. Wil je dat gebruikers een schone installatie krijgen, kijk dan eerst naar het distributiepakket en de installatielijst. Wil je vooral een overzichtelijkere ontwikkelboom, volg dan de testconventies van de gebruikte taal. Bestanden verplaatsen lost die twee vraagstukken niet automatisch tegelijk op.
Documentatie: maak de functies helder, niet per se het aantal bestanden kleiner
De bestaande routering voor projectmateriaal maakt al onderscheid tussen analyse, ADR’s, plannen en contracten, en schrijft voor dat er navraag wordt gedaan als de juiste plek onduidelijk is. ADR staat voor Architecture Decision Record: een beknopt verslag van een belangrijke technische beslissing en de reden daarvoor. De regel voor concepten beschrijft daarnaast een andere padconventie.
De statische aanwijzingen laten zien dat de afspraken over de levenscyclus van bestanden niet overal volledig op elkaar aansluiten. Ze bewijzen niet waarom er in afzonderlijke gevallen nieuwe mappen zijn aangemaakt.
Een werkbare aanpak hoeft geen nieuwe reeks mappen te introduceren. Maak binnen de bestaande structuur duidelijk wat waar thuishoort:
- Analyse: bewaar bewijs, vergelijkingen, tegenargumenten en open vragen. Een gewone vraag kan in de conversatie worden afgehandeld; maak geen rapport als er geen reden is om het te bewaren.
- ADR: leg belangrijke besluiten, hun onderbouwing en de bijbehorende beperkingen vast. Kopieer niet de volledige analyse en houd geen tweede versie van het uitvoeringslogboek bij.
- Implementatieplan: noteer alleen toestemming, reikwijdte, afhankelijkheden en acceptatiecriteria. Verwijs naar relevante besluiten in plaats van het onderzoek te dupliceren.
- Tijdelijk materiaal: plaats concepten, diagnostische invoer en ruwe uitvoer in een toegestane tijdelijke werkruimte. Een titel met het woord ‘concept’ maakt een bestand nog geen formele analyse.
- Duurzame werkinstructies: bewaar documentatie als die een herbruikbare handleiding vormt. Eén implementatie- of deploymentproces is niet automatisch reden om een nieuwe map met documentatie te maken.
Beslis afzonderlijk over het aantal documenten, versiebeheer, opname in een installatie en gebruik door het model. Alles in één map zetten is geen vervanging voor die afspraken.
Wat Geoffrey Huntley hieraan toevoegt
Huntley benadrukt in zijn artikel over back pressure het belang van geautomatiseerde feedback rond een agent. Die feedback helpt fouten tijdens het werk zichtbaar te maken; zijn punt is niet dat testbestanden moeten verdwijnen.12
Voor het overzetten van software naar een andere programmeertaal beschrijft hij een specifieke aanpak: breng het gedrag van tests eerst onder in specificaties en gebruik die vervolgens als leidraad voor de migratie.14 Dat is geen bewijs dat documentatie tests in alle projecten kan vervangen.
De bruikbare les voor V4 is dan ook beperkt maar praktisch: behoud uitvoerbare controles die laten zien of iets correct werkt, en verminder vooral overbodige of eenmalige validatiematerialen. Een specificatie beschrijft het verwachte gedrag; een test biedt een uitvoerbare controle. Vervang het ene niet zonder beoordeling door het andere.
Of Huntley een algemene standaard heeft voor tests in versiebeheer, conceptmappen en uitsluiting van installatiepakketten: daarvoor is onvoldoende bewijs. Ook is er geen onderbouwing voor een gedeelde opvatting in de genoemde online fora. Niet-onderzochte posts of repositories zijn hier niet als bewijs gebruikt.
Minder documentruis helpt, maar voorkomt hallucinaties niet vanzelf
Onderzoek naar lange context beschrijft dat taalmodellen informatie in het midden van een lange invoer soms minder goed benutten.3 HELMET benadrukt daarnaast dat je prestaties op lange context met uiteenlopende taken moet evalueren, en niet alleen met eenvoudige zoekproeven.
4
Daaruit volgt niet dat een bestand boven een vast aantal regels hallucinaties veroorzaakt. Het onderzoek meet ook niet rechtstreeks het risico in deze specifieke V4-repository.
Een voorzichtigere aanpak is om:
- documentatie per onderwerp en beslisgrens in te delen, in plaats van één bestand onbeperkt te laten groeien;
- standaard alleen de onderdelen te lezen die voor de huidige taak relevant zijn, en historische stukken zo nodig op te zoeken;
- korte samenvattingen te gebruiken die verwijzen naar bewijs en open vragen, terwijl het bronmateriaal beschikbaar blijft voor controle;
- een index als wegwijzer te behandelen, niet als tweede kopie van dezelfde informatie;
- logs en oude rapporten niet standaard volledig aan de modelcontext toe te voegen.
Een minimale verbetering voor V4
V4 heeft vooral baat bij één afspraak voor de hele levenscyclus van bestanden, van aanmaken tot verspreiden. Daarvoor is geen zwaar extra proces nodig:
- Vooraf: bepaal waarvoor het bestand dient. Breid waar passend een bestaande test of documentatie uit; maak niet automatisch voor elke wijziging iets nieuws.
- Voor opslag: kies een toegestane locatie en bepaal of het materiaal duurzaam of tijdelijk is, in versiebeheer hoort en in een installatie mag belanden. Is dat onduidelijk, verzin dan niet zelf een nieuwe map.
- Voor een commit: controleer op tijdelijke uitvoer, gevoelige inhoud, dubbele tests en dubbele documentatie. Alle tests negeren is geen aanvaardbare manier om de repository netjes te houden.
- Voor verspreiding: leg vast welke assets bij een installatie horen en voorkom dat tijdelijk materiaal in de suite belandt. Vereenvoudiging mag bestaande controles voor samenvattingen, identiteit en assetbescherming niet ongemerkt verwijderen.
- Voor opruimen: bescherm bewijs van mislukte controles, actieve taken en bestanden waarnaar elders wordt verwezen. Een geslaagde taak of verouderd bestand is op zichzelf geen toestemming om iets te verwijderen.
De voorzichtigste conclusie is: verduidelijk eerst de grenzen voor tijdelijke bestanden en installatie-assets. Maak daarna de functies van documenten consistenter en geef modellen informatie op basis van de taak. Er is geen onderbouwing om alle Go-tests te verplaatsen, structurele tests niet langer te committen of alle documentatie in één bestand samen te voegen.
Als er later toestemming komt om wijzigingen door te voeren, moeten acceptatiecriteria onder meer garanderen dat tests nog worden gevonden, relevante CI-controles blijven werken, tijdelijke bestanden niet in installaties terechtkomen en verwijzingen, open verplichtingen en historische informatie traceerbaar blijven.
Deze analyse is alleen in de conversatie opgeleverd. Er zijn geen bestanden gewijzigd, terminalcommando’s of tests uitgevoerd, of opruimacties gedaan. Ook is geen bestaand projectplan hervat of verder uitgevoerd.
Studio Global AI
Continue your research
This page includes a source-backed answer you can continue inside Studio Global.
People also ask
What is the short answer to "Houd AI-agentprojecten overzichtelijk zonder tests en documentatie overboord te zetten"?
Bewaar tests die blijvende kwaliteitscontroles bieden; behandel eenmalige diagnostiek en validatiebestanden als tijdelijke materialen.
What are the key points to validate first?
Bewaar tests die blijvende kwaliteitscontroles bieden; behandel eenmalige diagnostiek en validatiebestanden als tijdelijke materialen. Maak onderscheid tussen wat in de repository staat en wat met een installatie wordt verspreid: dat zijn verschillende grenzen.
What should I do next in practice?
Laat documenten elk een eigen functie vervullen en geef het model standaard alleen de informatie die voor de taak nodig is.
Sources
go.devAdd a test
ghuntley.comdon't waste your back pressure
doi.orgFound in the Middle: How Language Models Use Long Contexts Better via Plug-and-Play Positional Encoding