Hoe je voorkomt dat meerdere code-agents elkaar overschrijven

Het draaien van één AI-codeeragent op een repository voelt als pair programming. Het draaien van drie of vijf agents op dezelfde repository kan aanvoelen als een fabriek voor mergeconflicten als ze allemaal dezelfde checkout delen. Eén agent wisselt van branch, een andere bewerkt hetzelfde bestand, een derde voert een opruimcommando uit, en plotseling weet niemand meer welke diff bij welke taak hoort.

De oplossing is geen grotere prompt. De oplossing is een workflow. Ik behandel agents als snelle junior ontwikkelaars met shell-toegang: nuttig, maar ze hebben grenzen nodig.

De korte versie

• Gebruik één Git worktree per agent.
• Gebruik één branch per taak.
• Geef elke agent een duidelijke bestands- of module-eigenschapsgrens.
• Plaats gedeelde repositoryregels in AGENTS.md, CLAUDE.md, of beide met een symlink.
• Blokkeer destructieve Git-commando's, tenzij een mens ze goedkeurt.
• Merge via pull requests met CI en branch protection.

Dat is voldoende structuur voor het meeste parallelle agentwerk.

Waarom een gedeelde checkout faalt

Een normale Git checkout heeft één werkdirectory, één index en één huidige branch. Dat is prima voor één ontwikkelaar of één agent. Het wordt rommelig wanneer meerdere agents tegelijkertijd handelen.

Als Agent A halverwege een authenticatierefactor is en Agent B git checkout main uitvoert, verandert de werkruimte van Agent A onder zijn voeten. Als Agent C git reset --hard uitvoert, kan ongecommitteerd werk verdwijnen. Zelfs onschuldige commando's zoals git stash pop kunnen ongerelateerde wijzigingen door elkaar halen.

Je kunt agents vertellen deze dingen niet te doen, en dat moet je ook. Maar bestandssysteemisolatie is sterker dan vertrouwen.

Gebruik Git worktrees voor isolatie

Git worktrees staan toe dat één repository meerdere werkdirectories heeft die aan dezelfde geschiedenis zijn gekoppeld. Elke directory kan op zijn eigen branch staan, terwijl dezelfde objectdatabase wordt gedeeld. Je vermijdt de kosten en verwarring van het vijf keer clonen van de repository, maar elke agent krijgt nog steeds zijn eigen bestanden.

git fetch origin
git worktree add ../site-auth -b agent/auth-refactor origin/main
git worktree add ../site-billing -b agent/billing-fix origin/main
git worktree add ../site-tests -b agent/test-coverage origin/main
git worktree list

Start vervolgens één agent binnen elke directory. Agent A werkt in ../site-auth. Agent B werkt in ../site-billing. Agent C werkt in ../site-tests. Ze kunnen tests uitvoeren, bestanden bewerken en commits maken zonder elkaars checkout te veranderen.

Dit is ook het patroon dat Claude Code documenteert voor parallelle sessies: aparte worktrees, aparte branches en geïsoleerde bewerkingen. De helpdocumenten van Anthropic gaan verder en beschrijven worktree-gebaseerde parallelle sessies als een veelvoorkomende workflow voor power users om meerdere Claude-sessies tegelijkertijd uit te voeren.

Geef elke agent een eigen verantwoordelijkheidsgebied

Worktrees lossen conflicten op bestandsniveau op. Ze lossen geen conflicten op productniveau op. Twee agents kunnen nog steeds incompatibele beslissingen nemen als de taak vaag is.

Voordat ik agents parallel start, splits ik het werk op basis van eigendom. Niet alleen op bestandsnamen, maar op verantwoordelijkheid.

Jij bent verantwoordelijk voor src/auth/** en tests/auth/**.
Bewerk geen bestanden buiten die scope.
Wijzig geen publieke API-vormen zonder eerst te stoppen.
Voer de auth-tests uit voordat je 'klaar' rapporteert.
Open een PR met een gerichte samenvatting.

Die prompt is saai, wat precies de reden is waarom hij werkt. Agents hebben saaie grenzen meer nodig dan slimme proza.

De beste splitsingen zijn langs natuurlijke modulegrenzen: authenticatie, facturering, zoeken, documentatie, UI-componenten, migraties, tests. De slechtste splitsing is twee agents overlappende verantwoordelijkheid geven voor dezelfde service en hopen dat Git het later uitzoekt.

Gebruik AGENTS.md en CLAUDE.md als gedeelde regels

Repository-instructies moeten in de repository staan, niet alleen in een chatvenster. CLAUDE.md is de conventie die Claude Code leest. AGENTS.md is een algemenere conventie voor codeeragents. Als je beide tools gebruikt, houd dan één bron van waarheid aan en link de andere naam ernaar.

ln -s CLAUDE.md AGENTS.md

Dat bestand moet de build-commando's van de repository, testcommando's, implementatie-opmerkingen, stijlregels en eventuele harde beperkingen bevatten. Bijvoorbeeld: bewerk geen gegenereerde bestanden, raak migraties niet aan zonder goedkeuring, gebruik npm run lint voor overdracht, of houd blogcodeblokken op één HTML-regel met <br/> tags.

Het punt is simpel: elke agent moet beginnen met dezelfde lokale context.

Maak gevaarlijke Git-commando's expliciet

Ik laat agents niet improviseren met destructieve Git-commando's. Deze commando's zijn nuttig in een door mensen bestuurde terminal, maar riskant in autonoom werk:

git reset --hard
git checkout .
git clean -fd
git push --force
git stash pop

Mijn standaardregel is: lees vrijuit, schrijf beperkt, en vraag voordat je destructieve Git-commando's uitvoert. Agents kunnen git status, git diff, git log en normale commits uitvoeren. Ze mogen geen werk weggooien, force-pushen of een andere branch verplaatsen, tenzij de taak dit expliciet vereist.

Gebruik pull requests als overdrachtspunt

Merge agentwerk niet door bestanden tussen mappen te kopiëren. Laat elke agent een branch en een pull request produceren.

git status
git diff
npm test
git add src/auth tests/auth
git commit -m auth-refactor
git push origin agent/auth-refactor
gh pr create

Op GitHub kunnen branch protection rules pull request reviews, status checks, lineaire geschiedenis en merge queues vereisen. Die controles zijn belangrijker wanneer agents snel code kunnen genereren. Snelheid is alleen nuttig als main betrouwbaar blijft.

Ik houd van kleine agent PR's. Een gerichte diff van 200 regels is te beoordelen. Een gemengde refactor van 4.000 regels is waar bugs zich verbergen.

Merge in afhankelijkheidsvolgorde

Als Agent A een API wijzigt en Agent B die API gebruikt, merge dan eerst A. Rebase vervolgens B op de bijgewerkte basisbranch en laat B zijn eigen conflicten oplossen.

git fetch origin
git rebase origin/main
npm test

Dit houdt het mentale model schoon. De agent die verantwoordelijk is voor het afhankelijke werk, is verantwoordelijk voor het aanpassen aan de nieuwe basis. De menselijke reviewer ziet één coherente PR tegelijk.

De workflow die ik morgen zou gebruiken

1. Update main.
2. Maak één worktree en branch per agenttaak.
3. Start elke agent binnen zijn eigen worktree.
4. Geef elke agent een geschreven eigenschapsgrens.
5. Laat elke agent de relevante tests uitvoeren.
6. Push elke branch en open een PR.
7. Beoordeel, merge in afhankelijkheidsvolgorde, en verwijder voltooide worktrees.

git worktree remove ../site-auth
git branch -d agent/auth-refactor

Meerdere codeeragents kunnen aan dezelfde codebase werken. Ze moeten alleen niet in dezelfde checkout werken. Gebruik Git voor isolatie, pull requests voor beoordeling, en repository-brede instructiebestanden voor gedeelde regels. Dat geeft je parallelle snelheid zonder de repository te veranderen in een hoop mysterieuze diffs.

Verder lezen

• Git worktree documentatie
• Claude Code: parallelle sessies uitvoeren met worktrees
• Claude Code power user tips
• GitHub protected branches