How to stop AI coding agents breaking your code

Code tells an AI coding agent what it does. It never says why. So when an agent sees code that looks wrong but is deliberate, it “fixes” it, confidently, and breaks something. The fix: write the reason down where the agent reads it. Use a code comment for one spot, an architecture decision record for a bigger choice, an AGENTS.md file for team rules, and a test to lock it all in.

Code comment

The reason for one line, right above it.

Decision record

The reason for a choice that spans files.

AGENTS.md file

Rules every agent reads before it edits.

Test

Fails loudly if the behaviour changes.

Before you start

A repository indexed in Graphify, with your coding agent connected to the hosted MCP server. The open-source Graphify CLI works too.
Access to your git history and issue tracker.

Why AI coding agents “fix” code that isn’t broken

Agents read the code, not the history behind it. A line that’s odd on purpose, like a status mapped the “wrong” way to work around a provider, reads like a bug. Without the reason next to it, the agent cleans it up. To find the reason, run git blame on the odd lines, then read the commit, pull request and ticket behind them.

git blame -L 40,60 src/payments/status.py
git show <commit>

Write code comments that explain why

A good comment says why the code works this way, not what it does. Put it right above the code, keep it to the reason, and link the ticket or decision record.

def map_status(upstream: str) -> Status:
    # WHY: the provider reports PENDING for a short window after a charge
    # has already been captured. Treating it as a failure caused retries
    # and double charges. Map it to SUCCESS; settlement reconciles later.
    # Decision record: docs/adr/0007-pending-is-success.md
    if upstream in ("CAPTURED", "PENDING"):
        return Status.SUCCESS
    if upstream == "DECLINED":
        return Status.FAILED
    return Status.UNKNOWN

This is an illustrative example. Without the comment, PENDING → SUCCESS looks like a bug.

Record big choices in an architecture decision record

When the reason spans files, teams or trade-offs, write a short architecture decision record (ADR) in docs/adr/ and link it from the comment. This template is enough:

# 0007: Treat upstream PENDING as success

Status: Accepted
Context: The provider reports PENDING after capture. Failing it caused retries.
Decision: Map PENDING to SUCCESS. Reconcile during settlement.
Consequences: A rare real failure is caught at settlement, not at checkout.

Use	When	Where it lives
Code comment	The reason fits in a few lines and is about one spot	Right above the code
Decision record (ADR)	The reason spans files, teams or trade-offs	`docs/adr/`, linked from a comment
Test	Always, for either one	Your test suite, named after the behaviour

Put team rules in an AGENTS.md file

An AGENTS.md file at the root of your repo holds rules your coding agents read before they work. Add one line:

Before changing code that has a WHY comment, read it and any linked decision record.
If you change deliberate behaviour, update the comment, the record and its test in the same change.

The reason for one specific line still belongs next to that line. AGENTS.md tells the agent to look for it.

Lock the behaviour in with a test

Add a test that asserts the deliberate behaviour and points back to the reason. If anyone, person or agent, changes it, CI fails.

def test_pending_maps_to_success():
    # Pins the WHY in map_status (ADR 0007). If this fails, update the
    # decision record before changing the behaviour.
    assert map_status("PENDING") == Status.SUCCESS

Find the risky spots first with Graphify

You don’t need to document everything. Start where a wrong “fix” would hurt most.

Coupling hot spots from your PR reviews. Every Graphify review has an Impact & health section under Analysis details. When a change makes coupling worse, it says so, for example: Health — this change adds coupling hotspots: worse: load_cached() — 66 callers, 10 callees. Those functions are your first candidates.
The most-called code. Open Graph explorer and check Most connected, or select a node and read What a change could affect.

From your agent, ask:

Which functions in this repo have the most callers? For the top five, show what a change to each could affect.

The agent answers with the graphify_callers and graphify_impact tools. With the CLI, run graphify explain "<name>" and check the degree, or use the god_nodes MCP tool.

Hot spots here come from how code connects, not from how often files change. Graphify doesn’t rank files by git churn.

When it goes wrong

The blame points to a huge refactor commit

Run git log --follow -p on the file, or git blame --ignore-rev <commit> to skip formatting and move-only commits.

No ticket explains the reason

Ask the people in the commit history. If nobody knows, write what you found, mark it unconfirmed, and still lock the current behaviour with a test.

A caller you expected is missing

Graphify shows the connections it can see. Code called dynamically or by string name may not appear. See Check impact.

You want a CI check

Once the habit sticks, add a CI step that flags changes to files with WHY comments when the matching test or decision record didn’t change. Pair it with test impact analysis to run the tests a change touches.

FAQ

What is a code comment, and when should it explain why?

A code comment is a note in the source that the program ignores but people and agents read. Explain why whenever the code does something deliberate that looks wrong, such as a workaround, an odd mapping or a hard limit.

What is an architecture decision record?

A short file that records one decision: the context, the choice and its consequences. Teams keep them in docs/adr/ so the reason outlives the people who made it.

What goes in an AGENTS.md file?

Project-wide rules for coding agents: how to build and test, conventions, and instructions like “read WHY comments before editing”. Keep line-specific reasons in comments, not here.

What are code documentation best practices for AI agents?

Put the reason next to the code, link bigger decisions to a record, give agents rules in AGENTS.md, and lock deliberate behaviour with tests. Start with the most-connected code.

Next steps

Make agents use the graph

Tell your agent when to ask Graphify first.

Plan a refactor

List callers and tests before a change.

Review a pull request

See where coupling hot spots come from.

Try it in Graphify

We build and host the graph for you. The Free plan (up to 3 repositories) needs no card. Pro and Teams start with a 14-day trial, card required.

Essentials

Team

Agents

Data

CI and Ops

How to stop AI coding agents breaking your code

Code comment

Decision record

AGENTS.md file

Test

Before you start

Why AI coding agents “fix” code that isn’t broken

Write code comments that explain why

Record big choices in an architecture decision record

Put team rules in an AGENTS.md file

Lock the behaviour in with a test

Find the risky spots first with Graphify

When it goes wrong

FAQ

Next steps

Make agents use the graph

Plan a refactor

Review a pull request

Try it in Graphify

Code comment

Decision record

AGENTS.md file

Test

​Before you start

​Why AI coding agents “fix” code that isn’t broken

​Write code comments that explain why

​Record big choices in an architecture decision record

​Put team rules in an AGENTS.md file

​Lock the behaviour in with a test

​Find the risky spots first with Graphify

​When it goes wrong

​FAQ

​Next steps

Make agents use the graph

Plan a refactor

Review a pull request

Try it in Graphify

Before you start

Why AI coding agents “fix” code that isn’t broken

Write code comments that explain why

Record big choices in an architecture decision record

Put team rules in an AGENTS.md file

Lock the behaviour in with a test

Find the risky spots first with Graphify

When it goes wrong

FAQ

Next steps