Terminal agents: discover the workspace before changing it

Last updated: 4 Oct 202611 min read

tutorial

A terminal-agent prompt needs a verified workspace boundary. Name the desired behavior, then inspect the current directory, repository state, project instructions, and relevant entry points before proposing edits. A path inferred from an earlier conversation may be stale. A similarly named sibling checkout may contain another branch or another person's work. The agent should use narrow file discovery and inspect enough surrounding code to locate the owner of the behavior. It should record pre-existing changes so a later diff can separate its own edits from the user's work. A discovered instruction file may guide the task only within the authority assigned by the application and user.

Operational case

A fictional Manifest Gate repository imports 47 shipping manifests. The request is to reject duplicate shipment slugs before the import writes records. The agent first confirms the active checkout, finds the import handler and its tests, and reads the project rules. It sees an unrelated uncommitted stylesheet change and leaves that file alone. A second checkout has an older importer with the same filename; the verified repository root prevents an edit in the wrong tree. The agent identifies the importer as the narrow change owner before writing code.

Goal: reject duplicate shipment slugs before import writes.
Verify: repository root, branch, existing changes, project rules.
Discover: importer entry point and its focused tests.
Ownership: importer validation path only.
Leave unrelated stylesheet change untouched.

Performance and operating cost

A repository-wide scan of F files is O(F) and can flood the context with irrelevant text. A filename search followed by focused reads uses fewer tokens, though a second pass may be needed if the first hit is a wrapper. Record the base state once; repeated full-tree inspection adds latency without improving confidence. The prompt should ask for evidence of the active checkout, not assume that a path printed in a prior answer is still current.

Common Mistakes

Do not edit the first matching filename without confirming the repository root.
Do not overwrite unrelated uncommitted work.
Do not treat old conversation paths as current workspace evidence.

Connected lessons

prompt engineering

terminal agents