How to Keep an AI Agent from Breaking Your Repo

The best thing about an AI coding agent is that it can work inside a real repository. It can read files, edit files, run commands, inspect failures, and keep going.

The riskiest thing about an AI coding agent is the same thing: it can work inside a real repository.

Without guardrails, an agent can mix unrelated files into a change, overwrite uncommitted work, run a cleanup command that deletes useful state, or leave a confusing diff on the main branch. The answer is not to tell the agent to “be careful.” The answer is to use workflow and permissions.

Inspect before editing

Before an agent changes files, it should inspect the working tree:

git status
git diff --stat

This answers practical questions:

• Are we on the right branch?
• Are there uncommitted files?
• Do the existing changes belong to this task?
• Did generated files, config, or lockfiles already change?
• Is another person or another agent working in the same directory?

If the working tree is dirty, do not casually ask the agent to clean it. Cleanup can mean deleting work that someone still needs. First decide whether the current task should proceed in this directory, on a new branch, or in a separate worktree.

Branches isolate history; worktrees isolate directories

A branch is the minimum. An agent should not freely edit main or a long-lived shared branch.

But branches do not solve every problem. In a shared or busy repository, the same directory may still contain uncommitted files, build artifacts, local config, and temporary edits from another task.

This is where git worktree helps:

git worktree add ../repo-task-fix origin/main -b fix/user-export-permission

A separate worktree gives the task its own directory. That means:

• the task has a clean filesystem view
• it cannot overwrite uncommitted files in the original checkout
• the diff is easier to review
• a failed attempt can be abandoned without untangling the original directory

Not every small task needs a worktree. A small article edit or a focused test fix can be fine on a clean branch. But if the repository is dirty, the task is risky, or multiple agents are working at once, a worktree is safer than hoping everyone stays out of each other's way.

Do not let the agent revert unknown changes

Some dangerous commands look like normal cleanup:

git checkout -- .
git restore .
git reset --hard

These commands can discard uncommitted work. If that work belongs to you, another developer, or another agent, the cleanup just became data loss.

A better rule is simple: the agent must not revert files it did not create unless you explicitly approve it.

If it sees unrelated changes, it should report them:

The working tree has unrelated changes:
- ...

I will ignore them and only edit the files for this task.

This may feel conservative, but it prevents a common class of agent accidents: destroying work while trying to make the environment tidy.

Approve commands by destructive power

Not every command deserves the same trust level.

Commands that only read state or run expected validation are usually reasonable:

• rg, ls, sed
• git status, git diff
• project test, build, or lint commands

Commands that delete, overwrite, rewrite, or mutate persistent systems need a pause:

• deleting files or directories
• rewriting Git history
• force pushing
• deleting Docker volumes, databases, or cache data
• installing unknown scripts or global tools
• changing production configuration
• uploading logs, dumps, or files that may contain secrets

The decision rule is direct: if the command goes wrong, could it lose data, lose commits, affect another person, or affect production? If yes, require explicit approval.

This is not about distrusting AI. It is about separating read risk from write risk. Reading code and deleting data should not share the same default permission.

Match validation to risk

Agents often prefer the quickest check that can pass. A format check or a type check is useful, but it may not be enough.

Validation should match the risk:

• Articles and docs: build or MDX compilation may be enough.
• UI display: component tests, page build, and sometimes a manual browser check.
• Business logic: relevant unit and integration tests.
• Permissions and authentication: allowed, denied, missing binding, and cross-account paths.
• Caching and refresh behavior: verify the read path after mutation.
• Data migrations: local migration, rollback path, and idempotency checks.

If validation cannot run, the agent should say so plainly. “Not run” is a valid status. “Should be fine” is not a validation result.

Use the diff as the final boundary check

Before accepting the work, inspect the diff.

The first question is scope:

• Did it only touch allowed files?
• Did it add unnecessary dependencies?
• Did it introduce large unrelated formatting changes?
• Did it modify lockfiles, config, or generated files?
• Did it include local paths, secrets, or debug logs?
• Did it delete tests or weaken checks?

If the diff is too large to review, do not merge it as-is. Ask the agent to split the task or remove unrelated changes.

For the next gate, see What AI Code Review Should Check Before Merge.

A practical rule set

These rules are simple enough to reuse:

1. Report git status before editing.
2. Do not work directly on the main branch by default.
3. Use a new worktree for dirty repositories or parallel work.
4. Only edit files inside the task scope.
5. Do not revert unknown changes.
6. Require approval for destructive commands.
7. Match validation to the risk of the change.
8. Deliver changed files, validation results, and remaining risks.

The rules do not slow the agent down much. They reduce the chance of irreversible mistakes.

If the task itself is still unclear, start with AI Context Engineering for Real Projects. Safety rules protect the repository, but clear context is what keeps the task pointed in the right direction.

Conclusion

An AI agent is not automatically safe because it is capable. The more it can do in a real repository, the more it needs real engineering guardrails.

Branches and worktrees isolate work. Command approval controls dangerous operations. Tests validate behavior. Diffs expose facts. Dirty working tree discipline protects other people's changes.

With those rules, an agent can work productively in a real repo. Without them, it is a fast automation path with unclear boundaries.