--- title: "Semantic merge conflict: changes that merge cleanly but break the code · Cork" description: "A semantic merge conflict is when two changes merge with no textual conflict but the result is wrong, such as a rename plus new calls to the old name." canonical: "https://corkcli.com/blog/semantic-merge-conflict" last_updated: "2026-10-03" published: "2026-10-03" author: "Kevin Vera" --- # Semantic merge conflict: changes that merge cleanly but break the code A semantic merge conflict is when two changes merge with no textual conflict but the result is wrong, such as a rename plus new calls to the old name. By Kevin Vera · October 3, 2026 · [Glossary](https://corkcli.com/blog/c/glossary) · 3 min read A **semantic merge conflict** is a conflict between two changes that git can merge without any textual conflict, but whose combination makes the program fail to build or behave differently from what either author intended. Martin Fowler described it in 2011 as a situation where two developers "make changes which can be safely merged on a textual level but cause the program to behave differently." It is also called a semantic conflict or a logical merge conflict. ## Why it happens Git merges text, line by line. It has no idea what a function is, who calls it, or what a parameter means. If two changes touch different lines, git combines them, even when one change invalidates an assumption the other relies on. [Parallel AI coding agents](https://corkcli.com/blog/parallel-ai-coding-agents) make this more common for two reasons. First, agents are often isolated on purpose (separate worktrees, separate files), which removes textual overlap without removing logical dependency. Second, an agent only knows about another agent's change if it happens to read that code again, and nothing prompts it to. ## Examples - **Rename plus new callers.** This is Fowler's example: one side renames a method using a refactoring tool, updating every existing call; the other side adds new calls using the old name. The textual merge succeeds and the new calls point at a method that no longer exists. - **Signature change.** Agent A adds a required `currency` argument to `format_price`. Agent B adds a new screen that calls `format_price(amount)`. Clean merge, failing build (or, in a dynamic language, a runtime error). - **Changed meaning.** Agent A changes `timeout` from seconds to milliseconds and updates its callers. Agent B adds a caller passing `30`. Everything compiles; requests now time out after 30 milliseconds. - **Moved side effect.** One side extracts a notification out of a function into a separate call; the other side adds a new path that calls the original function and expects the notification to still happen. ## How teams handle it - **Tests and type checks after merge.** A compiler or type checker catches renames and signature changes; tests catch some behaviour changes. They run after the damage is done, and only find what they cover. - **Continuous integration.** Merging often keeps the window for semantic conflicts small. Fowler's article recommends exactly this pair: self-testing code and integrating frequently. - **Feature toggles and small changes.** Less divergence between branches means fewer hidden interactions. - **Telling the other side.** The conflict disappears if the second author knows about the rename before writing new calls. That last point is where coordination helps. Cork is the coordination layer for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. When another agent changes code yours depends on (a rename, a new signature), your agent hears about it on its next step. Its [semantic lint](https://corkcli.com/blog/semantic-lint) turns a teammate's rename or signature change into a lint rule your agents are checked against, and its landing step reruns the tests after rebasing onto teammates' commits, before pushing. ## Related terms - [Agent merge conflict](https://corkcli.com/blog/agent-merge-conflict) - [Agent collision](https://corkcli.com/blog/agent-collision) - Semantic lint - [Blast radius](https://corkcli.com/blog/blast-radius) - Landing (rebase, test and push in one step) ## Sources - - ## Related reading - [Semantic merge conflicts: when the merge is clean but the code breaks](https://corkcli.com/blog/semantic-merge-conflicts): A semantic merge conflict is a clean git merge that breaks the program. Why git misses them, examples with AI agents, and how to catch and prevent them. - [Agent collision: what it is when AI coding agents overwrite each other](https://corkcli.com/blog/agent-collision): An agent collision is when two AI coding agents change the same code, or code that depends on each other, without knowing, so one breaks or erases the other. - [Blast radius in code: everything a change can break](https://corkcli.com/blog/blast-radius): The blast radius of a code change is the set of callers, dependents, tests and teammates' work that the change can affect, used to judge risk before editing. - [Semantic lint: catching code that uses a renamed or changed symbol](https://corkcli.com/blog/semantic-lint): Semantic lint flags code that still uses a symbol a teammate or another AI agent renamed, removed or re-signatured, before it becomes a broken build or merge. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/semantic-merge-conflict