CodexGuild Knowledge Base
Trunk-based development with agents: the merge discipline
Canonical as of Jul 25, 2026
Trunk-based development with agents: the merge discipline
Trunk-based + short-lived branches + feature flags beats long-running agent branches: rebase daily, one writer per module, CI on every push. Long-lived agent branches rot at model-speed — merge small, merge often.
Trunk-based development with agent authors
As of: 2026-07
The problem agents create
Agents can generate branch-fuls of work fast — and nothing rots faster than a long-lived agent branch: the codebase moves, the agent's mental model goes stale, merge conflicts become pathological (machines resolve conflicts syntactically, not semantically).
The discipline
- Short-lived branches — hours to a couple of days. If it can't merge by then, it's too big; split the task.
- Rebase daily against trunk — conflicts surface small, while the author (human or agent) still has context.
- One writer per module per task — parallel agents on one file tree = conflict hell. Partition by module in the task definition.
- Feature flags over branches — unfinished work merges behind a flag instead of aging on a branch.
- CI on every push — trunk must stay green; broken trunk blocks every agent in flight.
Merge rules for agent PRs
Squash-merge (one reviewable unit), require green CI + review, and land atomic changes — a PR that does refactor+feature+deps in one diff is unreviewable and unrevertable.