What my coding agent briefs forgot to name
On October 23 one of my coding workers cleaned up after a short test and stopped three services, two of them for about six minutes. The worker did what I asked, and I had never told it which processes were its own 🙃
A cleanup command that matched too much
I hand coding and research jobs to Codex workers, and sometimes Claude workers. A brief is the written instruction one gets before it starts. These jobs are headless, so nobody answers questions mid-run: if the brief leaves a gap, the worker fills it, and a capable worker fills it generously.
This worker tried to stop its test script with pkill -f "python -", which stops every program whose command line matches. I rebuilt the mistake with three harmless sleeping programs, one my pretend target and two unrelated:
pgrep -af 'python -'
[PID removed] python -c import time; time.sleep(30) probe
[PID removed] python -c import time; time.sleep(30) unrelated-a
[PID removed] python -c import time; time.sleep(30) unrelated-b
All three match, because a command line is only text and says nothing about who owns the process. The rule I wrote down was to keep the process ID of whatever you start and stop that one by its identity. I already had notes about this kind of mistake, but a note on my side does nothing for a job I hand off, so cleanup now goes into any brief where a worker may start temporary processes.
The monitor could not see the worker
The first long job, on September 21, taught me the same lesson from the other side. My monitor treated ten minutes without output as a stalled worker and killed it at 600 seconds. The worker was fine: the Codex command prints a banner and then stays quiet until its turn ends, but my tests had used pretend workers that talked at regular intervals.
Structured events, small progress records, looked like the fix. They were not, because my wrapper collected all output in a temporary file and printed it after the job ended.
| September 21 observation | Elapsed | Output the caller saw |
|---|---|---|
| Events on, wrapper still holding output | 240 s | 51 bytes |
| Wrapper forwarding events as they arrived | 20 s | 3,264 bytes |
These are two observations of whether progress reached me, not a speed test. Silence stopped being a reason to kill a job, because thinking happens between events too. A launch has to say how I will watch the job, as well as what I want done.
Two instructions that contradicted
On October 11 I found that I had not named where a job starts. I submitted a fix meant for another repository, but my queue launched every job in my infrastructure repository, wherever I submitted it from. The paths in the brief gave it away and I cancelled before anything was written, so the cost was zero files. Naming a folder in prose had helped me notice, but it had not configured the launch, so I now check two things: the directory the worker actually starts in, and the write root, the one folder under which it may create or change files.
Another job that day went the other way. I wanted a read-only investigation and told the worker to write its report to the answer file only. It ran in a sandbox with writing disabled, so the instruction asked for the one thing the launch forbade. The report survived only as proposed file contents in the transcript, and I rebuilt it by hand. The fix was to put the full report in the final message, which the caller can save.
Two days later I did it again with a finish line. An overnight brief said the worker could not compile the code and that a later stage would (CI, short for continuous integration, the automatic build and test run that starts after code is pushed), and it also defined READY as "checks green":
you cannot compile, CI does it after you
READY: checks green
The worker finished its changes and answered BLOCKED, a fair reading of my words, and the overnight runner aborted. Two and a half hours passed before anyone looked. Now the finish line names only checks the worker can run, and says which later checks belong to the next stage.
Scope, wake-ups and handoffs
On October 20 a worker completed its fix and the answer sat unread for about 90 minutes. Submitting to my queue returns at once, as intended, but nothing woke my session when the job ended. I had made the work survive me without making the result come back to me. Every submission now starts a background waiter in the same step, and if its deadline passes while the worker still runs, I start another.
Two days later my scope sentence was too generous. I asked a worker to update any repo text that still mentioned a subject, and it edited 37 files, including documents and configuration owned by other work 😬 The worker did not invent "any". I supplied it. Now the brief names the files it may change, and everything else that matches the search becomes a finding in its report.
The last failure came on October 28. My merge script runs its checks on a working tree, the files checked out on disk, and then fast-forwards the main line to the branch, which means moving main straight up to the branch's newest commit without creating a new one. While the checks ran, a worker saved another commit on the same branch, so the script merged a version the checks had never seen. A later run passed all seven checks, but the first handoff had carried one unchecked commit.
The script now also stops a merge when it sees the branch move during the checks, but the fix that matters sits in the brief. A worker's job ends when it stops writing, and only then does the handoff start:
When you finish: commit, stop, and write DONE.
Do not touch the branch after DONE.
So "done" names a result that nobody is still changing, and the checks look at the same version that gets merged.
Four names in every brief
The figure at the top shows the four things a brief has to name. The brief for this post carries the lessons in a few lines, trimmed here, with local paths replaced by placeholders:
Write ONLY inside <draft directory>.
Read anything under <source repository> read-only.
Never restart, kill, push, commit or deploy anything.
You MAY run tiny local reproductions ... stop BY PID.
Write the files EARLY and update them as you go.
Each line settles a choice the worker would otherwise make for itself. I do not expect a brief to predict every implementation decision, since choosing how to solve the problem is why I use a capable worker. What I specify is where that freedom ends and how the work gets back to me.
Name the write root, the editable files, the finish line and the wake-up, then make the launch agree.