Keeping Both Sides of an API Change in View

Modern codebases contain countless implicit couplings: an API route response in TypeScript and the client pagination helper in Python; an SQL enum schema and a configuration dictionary in Go; a CSS custom property and an SVG canvas renderer.

No compiler, import graph, or type checker connects these files. When a coding agent refactors one side, the other silently breaks at runtime.

git-span solves this by attaching declarations to exact code regions and tracking content hashes across commits.

---

1. Declaring a Span Across Boundaries

A span is a simple Markdown document stored directly inside the repository in .span/:

api/src/routes/products.ts#L4-L7 rk64:38db8e8540025b2a
client-py/pagination.py#L25-L27  rk64:f4df18e9b3e72d2a

The API pagination response is authoritative;
clients consume its continuation cursor unchanged.

Each anchored region records:

• Relative file path and line numbers
• A robust rolling content hash (rk64) of the referenced lines
• An explanation of the semantic dependency

Because spans live inside the repository, they are committed, branched, and diffed alongside the code they document.

---

2. Agent Interception Before Edits Land

When an agent tools like Claude Code or Codex reads or edits an anchored region, git-span intercepts the operation via a hook and surfaces the connected context:

● Update(api/src/routes/products.ts)
  ⎿  Added 1 line, removed 1 line
   4   return {
   5     items: items.slice(0, limit),
   6 -   page: page.nextPage,
   6 +   cursor: page.nextCursor
   7   };
  ⎿  PostToolUse says: <git-span>
## product-listing-pagination
api/src/routes/products.ts#L4-L7
client-py/pagination.py#L25-L27

The API pagination response is authoritative;
clients consume its continuation cursor unchanged.
</git-span>

The agent immediately sees that client-py/pagination.py depends on the field it just renamed. It navigates to the client file and updates it in the same task session before completing the run.

---

3. Detecting and Reconciling Drift

If a developer or another agent edits an anchored region without updating the corresponding span, git-span detects the hash mismatch:

$ git span drift
⚠️  DRIFT DETECTED in 1 span:
  • product-listing-pagination
    - api/src/routes/products.ts#L4-L7: content hash changed (38db8e85 -> 9a41f01c)
    - client-py/pagination.py#L25-L27: unchanged

Run `git span reconcile product-listing-pagination` to inspect diff and re-anchor.

By making implicit architectural knowledge explicit, inspectable, and auditable, teams prevent regressions before code reaches staging.