After Codex, I started tidying my workspace

Recently, after finishing a somewhat long task with Codex, I noticed:

the feature was done, and the project root looked like it had been turned upside down.

It now had temporary scripts, test files, screenshots, logs, drafts, and intermediate files whose names all looked like “final version.”

Each of these may have been useful when it was generated. The trouble came a few days later:

Which are the final deliverables? Which were used only once for verification? Which did the agent create? Which did I leave there originally? Which can be deleted, and which are better left alone?

I later realized that telling a coding agent only “what to get done” isn’t enough.

If a clean workspace isn’t written into the requirements, it naturally won’t be treated as part of being done.

Any coding agent that can read and write files, run commands and generate intermediate output — whether Codex, Claude Code or Cursor Agent — runs into similar problems.

I call it workspace hygiene.

Now I mainly follow three rules.

1. First, limit where it can act

I used to care more about whether an agent could complete a task; now I also check where it can complete it.

When it only needs to inspect code or analyze a problem, I start with read-only.

When it needs to make changes, I then open up write access to the current workspace. Network access, modifying files outside the workspace, or system configuration get confirmed separately.

Taking the Codex CLI / IDE as an example, you can use a configuration like:

sandbox_mode = “workspace-write” approval_policy = “on-request” web_search = “cached” [sandbox_workspace_write] network_access = false

Roughly, that means:

it may work inside the current workspace; commands can’t go online directly by default; when it needs to cross a boundary, it asks first.

The more permissions it has, the bigger the area you need to check when something goes wrong.

If a task needs to try several approaches A, B and C at once, I also consider a temporary branch, a worktree, a sandbox or a copy of the project, so all the trial and error doesn’t happen in the main project.

2. Give process files a fixed home

For tasks like reports, data analysis and image generation, I fix two directories:

work/: temporary scripts, logs, drafts and process data. outputs/: files that finally need to be delivered or shown to people

Existing codebases keep following their original src/, tests/, docs/ and other structures; there’s no need to force an extra set of directories just to use an agent.

You can give the agent this instruction directly:

For this task, please answer directly where possible. Only create files when you genuinely need to change source code, create deliverables, or write verification scripts or intermediate data.

Please follow the project’s existing directory structure:

- put temporary process files in work/ or the project’s existing temp directory;

- put standalone deliverables in outputs/;

- put source code, tests and docs back in their original places in the project;

- don’t scatter scratch files in the project root. Before finishing, please list the files you created and modified this time.

If this is a long-term rule, you can also write it into the project’s AGENTS.md or another agent instruction file, so you don’t have to remind it every time.

3. Write housekeeping into the definition of done

After the agent says “done,” I now have it do one more wrap-up:

Please do a housekeeping wrap-up:

1. List the files this task created or modified, divided into:

- final deliverables

- source code or documentation changes

- temporary process files

2. Delete temporary files that you’ve confirmed this task created and that are no longer needed.

3. Don’t delete:

- input files I provided

- the project’s original files

- untracked files of uncertain origin

4. If the current directory is a git repo, run git status –short and explain the remaining changes and untracked files.

5. Finally, say:

- what was kept

- what was cleaned up

- what still needs my decision

The most important line here is:

don’t delete files of uncertain origin.

Housekeeping isn’t deleting as much as possible; it’s making sure every change has a clear destination. When you can’t confirm where something came from, keeping it and leaving it to a person is safer.

My definition of “task complete” now has one more line:

the result runs, and the changes can be explained.

If git status still shows a pile of files whose purpose nobody can explain, the task isn’t actually finished.