智能體任務設計復盤：重新開始時先寫操作日誌

A month in, the single most useful artefact I have is a plain text file of one line per action. Everything else I built can be rewritten in an afternoon. The log cannot, because it is the only thing that accumulated knowledge instead of assuming it.

If I started again, the order would be: log, then pre-flight, then fixtures, then permissions, and only then tasks.

Why the log goes first

Without it, every failure is a story I tell myself afterwards. With it, a failure is a row I can sort by. I spent two weeks making confident guesses about why tasks broke - the model, the context window, the temperature - and the log proved all three wrong. It was stale state and a missing stop condition.

The log is also the thing that made the approval gate possible. I could not tell which actions to gate until I could see the distribution of actions. "Everything feels risky" is not a policy. "Reads: 3400, writes: 410, sends: 12, deletes: 3" is a policy.

What is in a line

One action per line, structured enough to grep and readable enough to read at 2am:

12:04:19 task=deploy-staging step=3/7 tool=shell intent="restart the app so the new config loads" cmd="systemctl restart app" result=ok duration=4.2s state=clean

Five things earn their place: timestamp, task and step, intent, the actual command, and the result. Everything else I tried to add turned out to be derivable or noise.

The thing I got wrong about intent

I wrote intent in the first person as if I were the agent: "I will restart the service so the new configuration loads". That reads nice and is useless for auditing, because it is a narrative of a belief.

The version that works is telegraphic and mechanical: what changes, why, and what would show it went wrong. It reads worse. It survives contact with a rollback.

The cost I underestimated

Logging properly made the first version of every task slower to run. Not much, but enough that I skipped it on the small ones - and the small ones are exactly where I later needed to know what changed.

The fix was to make logging the runtime's job, not the task's. If the agent cannot act without emitting a line, there is no such thing as an unlogged run.

What I would still not log

Full page text, screenshots, and prompts. Too big, too slow to search, and they age into lies the moment the state changes. I log a pointer to them instead - a hash, a filename, a run id.

If you were starting today, what is the first thing you would build? I would genuinely like to be wrong about this being the log.