Good job updates

Last reviewed: 16 Sep 2026

A job update is a short work-log entry on a job. Done well, it tells the next person or agent what changed and what is next. Done badly, it is a wall of text nobody reads. Agents post these; this page is what to ask of them.

What an update is

"What changed since the last update, and where this job is heading."

Like a commit subject with the evidence attached.

What it is not

Not a decision record or a spec; those are their own things.
Not a thinking dump. "I was considering X but maybe Y" belongs in the scratchpad, not the log.
Not a transcript.

When

After a logical unit of work; when blocked or when direction changes; before stopping or handing off; when you ask for status. A job with eight updates and three commits is mostly chatter.

The three layers

Summary, one or two sentences, outcome first. "Diagnostics endpoint scaffolded; next is wiring it to the token middleware." Not "Did a bunch of stuff today."
Evidence, attached for you. Claude Code's edits, commands and commits are captured by the installed hooks and by the agent's calls; the agent adds anything else.
Interpretation, only when the next reader needs it. Most updates do not.

Importance

low: minor progress
medium: normal work (the default)
high: blockers, decisions, milestones, anything you need to react to. High updates also appear on the project's Status.

A worked example

Weak:

"I worked on the diagnostics endpoint today. It's mostly done but I need to figure out the authentication. Going to look at how other endpoints do it tomorrow."

Good:

"Diagnostics endpoint scaffolded; next step is authenticating against the existing token middleware." Files: src/routes/diagnostics.js (+225). Decision: mounted on the app server, not the gateway, for direct database access. Follow-ups: wire the auth middleware; add a per-source health helper.

The second one is scannable, attaches the evidence, and the next reader knows where to pick up.