Heb je ooit een AI-coding agent gevraagd om iets te bouwen, alleen om een pull request terug te krijgen dat compleet naast de toon van je project zit? Je bent niet de enige. Volgens een groot onderzoek van GitHub ligt het probleem niet aan de intelligentie van de agents, maar aan het gebrek aan context.
In dit artikel duiken we in een fascinerende studie van GitHub waarin meer dan 2.500 custom instruction bestanden werden geanalyseerd. We ontdekken wat succesvolle AI-agents onderscheidt van de zwakke, en hoe GitHub Copilot een slimme oplossing biedt met gestructureerde context.
Het grote inzicht uit het GitHub-onderzoek
GitHub heeft een uitgebreid onderzoek gedaan naar meer dan 2.500 custom instruction bestanden in publieke repositories. Het doel was om te begrijpen waarom sommige AI-coding setups uitstekend werken, terwijl andere compleet falen.
Het resultaat is verrassend duidelijk: de meest effectieve agent setups geven de AI een specifieke persona, exacte commando's, duidelijke grenzen en voorbeelden van gewenst output. De zwakke setups daarentegen zijn vaag en beschrijven de agent slechts als "een behulpzame assistent" zonder duidelijke taakomschrijving.
Dit wijst op de kern van het probleem met coding agents vandaag de dag. Het is geen capability probleem (de agent kan wel code schrijven), maar een context probleem. Een raw agent kan prima code genereren, maar weet niets van de specifieke afspraken binnen jouw team.
Het context-probleem in de praktijk
Stel je voor dat je een nieuw feature laat bouwen door een AI-agent. De agent kan uitstekend programmeren, maar kent niet:
- De naming conventions van jouw team
- De specifieke linting en formatting regels
- Welk framework patroon jullie prefereren
- Welke beveiligingsregels er gelden
- Hoe jullie tests schrijven
Het gevolg? Het eerste pull request is vaak volledig off-target. Er volgen meerdere rondes van correcties, wat de productiviteit juist verlaagt in plaats van verhoogt.
Dit verklaart waarom veel developers teleurgesteld zijn in AI-coding tools. De technologie kan wél, maar mist de juiste instructies om binnen de context van het project te werken.
Hoe GitHub Copilot context gestructureerd aanbiedt
Gelukkig heeft GitHub Copilot een slim, gelaagd systeem ontwikkeld om dit context-probleem op te lossen. Het werkt met verschillende lagen van instructies.
Repository-brede instructies
Op repository-niveau kun je een bestand aanmaken genaamd .github/copilot-instructions.md. Dit bestand definieert projectbrede regels zoals:
- Coding conventions
- Naming standards
- Security defaults
- Verboden patronen
De AI-agent leest dit bestand vóórdat hij ook maar één regel code genereert. Dit zorgt voor consistente output die aansluit bij de standaarden van het project.
Granulaire instructies per bestandstype
Voor nog meer controle kun je specifieke instructiebestanden plaatsen in de map .github/instructions/. Deze bestanden gebruiken een applyTo frontmatter om aan te geven op welke bestanden ze van toepassing zijn.
Een TypeScript-specifiek instructiebestand activeert bijvoorbeeld alleen wanneer de agent aan .ts bestanden werkt. Dit zorgt voor zeer gerichte en relevante instructies.
Custom agents: gespecialiseerde AI-persona's
Misschien wel de meest innovatieve toevoeging zijn de custom agents. Deze worden gedefinieerd in .agent.md bestanden in de map .github/agents/.
Elke custom agent krijgt een eigen:
- Specifieke persona
- Eigen tool access
- Mogelijke MCP server verbindingen
- Duidelijke grenzen over wat hij wel en niet mag doen
Voorbeelden van nuttige custom agents
- Security Auditor Agent: Heeft alleen leesrechten, voert linters uit en flagt beveiligingsissues
- Test Writer Agent: Volgt exact de testpatronen die het team heeft vastgelegd
- Frontend Specialist: Werkt volgens de specifieke design system en component structuur van het team
Organisatie-brede standaarden met custom agents
Een van de krachtigste aspecten is dat deze custom agents ook op organisatieniveau kunnen worden gedefinieerd in een speciale .github-private repository. Van daaruit worden ze automatisch overgeërfd door alle repositories binnen de organisatie.
Dit betekent dat frontend conventies, backend patronen en security policies overal gelden zonder dat je configuratiebestanden hoeft te dupliceren. Een echte schaalbare oplossing voor development teams.
De toekomst van context-rijke AI-agents
De conclusie uit het GitHub-onderzoek is duidelijk: de volgende grote sprong in AI-coding assistants zit niet in nog slimmere modellen, maar in betere context management.
Bedrijven en teams die investeren in het zorgvuldig documenteren van hun standaarden, patronen en voorkeuren in een vorm die AI-agents kunnen begrijpen, zullen veel meer waarde halen uit deze technologie.
Het gaat niet langer om de vraag óf AI kan coderen, maar óf de AI begrijpt hoe jij wilt dat er gecodeerd wordt.
Wat kun jij nu al doen?
Wil je zelf betere resultaten halen uit GitHub Copilot en andere coding agents? Begin dan met het creëren van een duidelijke .github/copilot-instructions.md in je belangrijkste repositories.
Beschrijf niet alleen wat er gebouwd moet worden, maar vooral hoe het gebouwd moet worden volgens jullie standaarden. Geef de agent een duidelijke rol, concrete voorbeelden en expliciete grenzen.
De teams die dit nu al doen, merken dat hun AI-assistents van frustrerende correctierondes veranderen in waardevolle, productieve teamleden.
Heb jij al ervaring met custom instructions voor AI-coding agents? Deel jouw ervaringen in de comments hieronder. Welke aanpak werkt het beste voor jouw team?
Dit artikel is gebaseerd op het recente onderzoek van GitHub naar custom instructions voor coding agents.