← Agent workflows guides

How to keep agents from changing the wrong files

How-To Agent workflows Intermediate 1041003HOWTO-1041003

HOWTO-1041003Agent workflowsIntermediate

This guide shows you how to prevent agents from editing files that look related but are outside the intended spec-driven development boundary.

Wrong-file changes are one of the clearest places SpecDD helps. The agent does not need to infer scope from filenames, imports, or nearby modules. It can use the nearest local spec to determine what may change.

Short answer

Put writable paths in Can modify, or in Owns when Can modify is absent. Put context paths in Can read or References. Use Must not and Forbids for tempting boundary violations. Then review plans and diffs against those sections before accepting work.

When to use this guide

Use this guide when:

Steps

1. Define the writable boundary with Can modify

Use Can modify when you want an explicit edit list.

Spec: Itinerary

Purpose:
  Keep a trip itinerary organized by day.

Can modify:
  ./itinerary.js
  ./itinerary.test.js
  ./fixtures/itinerary-validation.json

Must:
  Missing place names are rejected before an itinerary item is stored.

This tells the agent which files are writable for work under this spec.

Use explicit paths such as ./, ../, or /. Unprefixed filenames are plain text, not path references.

2. Use Owns when ownership and modification are the same

For small specs, Owns is often enough:

Spec: Itinerary

Owns:
  ./itinerary.js
  ./itinerary.test.js

When Can modify is absent, Owns acts as the modification boundary. This is useful for a first local spec.

Add Can modify later when writable files should be narrower or different from owned responsibilities.

3. Put read-only context in Can read

If the itinerary code needs storage context, say so without granting write authority:

Can read:
  ../storage/trip-storage.sdd
  ../storage/trip-storage.js

The agent can inspect those files to understand behavior. It should not edit them as part of the itinerary task unless the storage spec also grants authority for a separate task.

4. Use References for outside contracts

Use References when one spec needs another contract:

References:
  ../destinations/destination-search.sdd

References are explicit context. They do not create inherited write authority. This distinction matters in agent work: the agent can read the destination search contract to avoid breaking it, but an itinerary task should not edit destination search just because it was referenced.

5. Block likely wrong edits with Must not and Forbids

Use Must not for behavior boundaries:

Must not:
  Change destination search ranking.
  Add booking purchase behavior.

Use Forbids for blocked dependencies, paths, modules, libraries, or architectural access:

Forbids:
  ../booking/*
  Direct booking API access from itinerary behavior.

Do not list every unrelated file. Focus on paths and responsibilities an agent might plausibly touch.

6. Ask for a plan before editing

Use:

Plan the Itinerary validation change.

Before implementation, check whether the plan proposes any file outside the writable boundary. If it does, revise the spec or the plan before code changes begin.

7. Review the diff after implementation

After implementation, compare every changed file to the spec.

Acceptable:

Suspicious:

Use:

Review this change against the Itinerary spec.

Example boundary

Spec: Itinerary

Purpose:
  Keep a trip itinerary organized by day.

Can modify:
  ./itinerary.js
  ./itinerary.test.js

Can read:
  ../storage/trip-storage.sdd
  ../storage/trip-storage.js

References:
  ../destinations/destination-search.sdd

Must:
  Missing place names are rejected before an itinerary item is stored.

Must not:
  Change destination search behavior.

Forbids:
  ../booking/*

Done when:
  Missing-place behavior is covered by a check.
  Destination search behavior is unchanged.

Common mistakes

How to verify the result

The boundary is working when:

← Agent workflows guides