Safe Edit Zones: Teaching AI Agents Where They Can and Cannot Write

March 8, 2026 · SysMARA Team

Give an AI agent access to a codebase and ask it to implement a feature. It will create files, modify files, and sometimes delete files. It does not distinguish between a file that was hand-written by a senior engineer after three days of design work and a file that was auto-generated by a build tool. To the agent, they are both text files.

This is not a flaw in the agent. It is a missing abstraction in the codebase. Most projects do not declare which files are which. Generated code sits next to hand-written code. Configuration files sit next to business logic. There is no formal boundary between "safe to modify" and "do not touch."

Four Zones

SysMARA assigns every file in the project to one of four zones:

Generated. These files are produced by the capability compiler and are fully deterministic. They can be regenerated from the specs at any time. Modifying them is pointless — the next compilation will overwrite the changes. Route handler stubs, test scaffolds, and capability metadata files fall into this category. AI agents should never edit generated files directly. If the generated output needs to change, the spec that produces it should change.

Editable. These are the files where human and AI code lives. Business logic implementations, service functions, utility helpers, and custom middleware. An AI agent can freely create and modify editable files. This is where productive work happens.

Protected. These files can be modified, but changes require elevated review. System configuration, security policies, database migration scripts, and infrastructure-as-code templates are typically protected. An AI agent can propose changes to protected files, but the change plan flags them for explicit review and the risk classification increases accordingly.

Human-review-only. These files cannot be modified by an AI agent without human approval. Cryptographic key configurations, compliance-related code, and financial calculation modules are examples. The agent can read these files for context, but any change plan that proposes modifications to human-review-only files is blocked until a human explicitly approves.

Boundaries, Not Trust Levels

It is tempting to frame safe edit zones as trust levels — we trust AI with some files but not others. That framing is misleading. The zones are not about how much we trust the agent. They are about the nature of the files.

Generated files should not be edited by humans either. If a developer modifies a generated route handler, the next compilation will erase their changes. The "generated" zone protects humans and AI agents alike.

Protected files need review not because AI agents are unreliable, but because changes to those files have outsized impact. A human modifying a database migration should also go through careful review. The zone makes the review requirement explicit and automatic rather than relying on team norms.

Human-review-only files exist because some decisions should not be delegated. This is a policy choice, not a quality judgment. A financial calculation module might be simple code that any competent agent could modify correctly, but the organization requires a human to sign off on changes to billing logic. The zone enforces that requirement.

How Zones Are Declared

Zone assignments are declared in the system specs, not inferred from file paths or naming conventions:

editZones:
  generated:
    - "src/generated/**"
    - "src/routes/**/*.handler.ts"
  editable:
    - "src/services/**"
    - "src/utils/**"
  protected:
    - "src/config/**"
    - "migrations/**"
  humanReviewOnly:
    - "src/billing/calculations/**"
    - "src/security/crypto/**"

The patterns are explicit. There is no heuristic. An AI agent can check any file path against the zone declarations and know immediately whether it can modify the file, whether the modification will be flagged for review, or whether the modification is blocked without human approval.

Integration with Change Plans

When the change protocol generates a change plan, it cross-references every affected file against the zone declarations. The plan includes a breakdown: which files in the change are editable (proceed normally), which are protected (flag for review), which are human-review-only (block until approved), and which are generated (should not appear in a change plan at all — if they do, something is wrong).

This integration means that zone violations are caught before any code is written. An AI agent does not discover that it cannot modify a file after writing the modification. It discovers the constraint during planning, when the cost of adjusting the approach is low.

A Practical Necessity

As AI agents take on more coding tasks, the question of file ownership becomes unavoidable. Without explicit zones, teams resort to ad-hoc measures: .gitignore-style files that agents are told to respect, prompt instructions listing forbidden directories, or post-hoc review of every change. These measures are fragile and do not scale.

Safe edit zones make file ownership a formal part of the system architecture. They are declared in the same specs as entities and capabilities, validated at build time, and enforced by the change protocol. They are not an afterthought. They are a fundamental boundary that any system operating with AI agents needs to define.