DevOps Peach

Claude Code in Practice · Long projects – Context, progress and shipping · Lesson 2 of 3

Progress you can hand over: work log, tasks and two AIs

The chat history is not a project record. We keep a work log in the repository, task files for delegated work and the same house rules for every tool, so any session, Claude or Codex, can pick up where the last one stopped.

Practice interactively →

Sessions end, contexts reset, and sometimes the next piece of work goes to a different tool. If the only record of what happened is the conversation, every handover starts with an archaeology dig. Our fix is three plain files.

1. docs/worklog.md: what was done and what state it left

Newest first. One entry per piece of work:

## 2026-11-07 (profile page)
| Commit | Message | What it actually contains |
|---|---|---|
| (not committed yet) | | Profile page #profile (design B), avatar picker,
  photo upload (dl-avatar-img, synced), other learners' profiles via
  GET /api/users/:id. Needs `wrangler deploy`. |

The "what it actually contains" column matters: commit messages are short, the log says which files, which keys, which commands still need running. We ask for an entry at the end of every task ("record what we just did so other agents know the current context"), and we mirror the latest state into the shared project notes.

2. tasks/<name>.md: delegated work as a contract

When work goes to another session or to Codex, it gets a task file from tasks/_TEMPLATE.md: inputs, expected outputs, a Definition of done, and an empty "report" section the worker fills in. tasks/QUEUE.md lists what is waiting. The reviewer checks against the task, not against memory.

3. The same rules for every tool

Claude reads CLAUDE.md; Codex reads AGENTS.md. Both say the same important things: placeholders only, never touch the owner-only files, run the validator, do not commit. When a rule changes, it changes in both.

flowchart LR
  S1["Session A"] --> WL["docs/worklog.md"]
  S1 --> TK["tasks/aws-03.md"]
  TK --> CX["Codex"]
  CX --> RV["codex-reviewer"]
  WL --> S2["Session B (fresh)"]
  RV --> S2
  %% step S1: The first session finishes a piece of work and writes what changed.
  %% step TK: Work for another tool goes into a task file with a Definition of done.
  %% step CX: Codex reads AGENTS.md and the task, then fills in its report.
  %% step RV: A reviewer agent checks it against the task.
  %% step S2: A fresh session reads the log and the reviews and continues.

A handover message that works

When you start a new session on old work, the first message can be this short:

Read docs/worklog.md (top three entries) and tasks/QUEUE.md. Continue the profile page work. Do not commit.

Claude reads two files and is caught up in a minute, with no history and no guessing.

Use case: Picking up another session’s work in one minute

The situation

Over one morning a session built a profile page, an avatar upload, other learners' profiles and a small menu fix. None of it was committed. The next day a new session was asked to "commit everything from yesterday".

What the new session did first

It read the top entries of docs/worklog.md:

Entry Pending item it found
Profile page Worker change: publicUser now returns since → needs wrangler deploy
Other learners' profiles New GET /api/users/:id and GET /api/avatar/:id → needs wrangler deploy
Case study maps site/casemaps.js is new and must be added to Git
Argo CD track Graded content still needs a tech-reviewer pass before merge

What it reported before committing

Found 4 pieces of uncommitted work. Two include Worker changes, so after the push the site needs npx wrangler deploy, otherwise the leaderboard links will 404. The Argo CD quizzes have not passed tech-reviewer yet (rule in CLAUDE.md). Commit everything except Argo CD, or run the review first?

The owner chose to run the review first. One issue was fixed, then everything went in on a new branch.

Why it worked

What we took away

Practice interactively →