--- title: "Semantic lint: catching code that uses a renamed or changed symbol · Cork" description: "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." canonical: "https://corkcli.com/blog/semantic-lint" last_updated: "2026-10-03" published: "2026-10-03" author: "Kevin Vera" --- # Semantic lint: catching code that uses a renamed or changed symbol 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. By Kevin Vera · October 3, 2026 · [Glossary](https://corkcli.com/blog/c/glossary) · 3 min read **Semantic lint** is a lint check generated from a recent change to the code's meaning, such as a function being renamed, removed or given a new signature, that flags any code (or any agent's pending edit) still using the old form. Ordinary lint rules are written once and encode style or known bug patterns. Semantic lint rules come from what just changed in this repository, and they matter most for the hours or days while other branches and agents have not caught up. ## How it works 1. **Detect a semantic change.** A commit or edit renames `get_invoice` to `fetch_invoice`, removes a parameter, or adds a required one. 2. **Turn it into a rule.** The rule says, in effect: calls to `get_invoice` are now wrong; calls to `format_price` need a `currency` argument. 3. **Check work against it.** New edits, open branches and other agents' changes are checked against the rule, and each finding names the change that caused it and the fix. Many findings have a mechanical fix (swap the name, add the argument). Others need judgement, for example when a function was split in two and the caller must choose which half it needs. ## Why it matters Semantic lint targets the [semantic merge conflict](https://corkcli.com/blog/semantic-merge-conflict): two changes that merge cleanly as text but break when combined. Martin Fowler's classic example is exactly a rename on one branch plus new calls to the old name on another. Compilers and type checkers catch some of these after the merge; tests catch others if they cover the path. Semantic lint moves the check earlier, to the moment an agent writes code against stale assumptions, and makes the finding explain itself. ## Examples - Agent A renames `UserService.load` to `UserService.get`. Agent B, in another worktree, writes `svc.load(id)`. Semantic lint flags B's line with "renamed to `get` by A" before B commits. - A teammate makes `send_email` take a `template_id`. Three call sites added later that day pass only the address; all three are flagged. - A module is deleted. Imports of it in open branches are flagged with the commit that removed it. ## How teams handle it - **Type checkers and compilers** in CI, which catch renames and arity changes in typed code after integration. - **Deprecation shims.** Keep the old name as an alias that warns, then remove it later. - **IDE refactoring tools**, which update every call they can see, but not calls on branches or in agents' unsaved work. - **Frequent integration**, so stale assumptions do not live long. Cork generates semantic lint from teammates' changes. Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) 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. A teammate's rename or signature change becomes a lint rule your agents are checked against, and when another agent changes code yours depends on, your agent hears it on its next step. ## Related terms - Semantic merge conflict - [Agent collision](https://corkcli.com/blog/agent-collision) - [Blast radius](https://corkcli.com/blog/blast-radius) - [Write gate](https://corkcli.com/blog/write-gate) ## Sources - ## Related reading - [Write gate: a check that holds an AI agent's edit before it lands](https://corkcli.com/blog/write-gate): A write gate checks each file edit an AI coding agent is about to make and holds or blocks it when it would collide with another agent's live work on that code. - [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 merge conflict: changes that merge cleanly but break the code](https://corkcli.com/blog/semantic-merge-conflict): 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. - [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. [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-lint