Coding Agents Need Context Hygiene

Code survives, rationale rots

After a long coding session, files on disk may be correct while the reason for the change is fading from context. The next agent sees a diff but not necessarily the decision trail, parallel-session warnings, or human authority boundaries.

That is why coding agents need live boards, narrow staging, exact validation notes, and commit messages that explain the operational boundary. A passing test is necessary; it is not the whole handoff. The commit message has to be readable by a future instance with no chat history.

Never trust stale docs blindly

Read current source. Check current git status. Verify current routes. Old history helps, but source is the object state. The first action of every coding-agent turn should be to align reading-knowledge with running-knowledge.

Stage explicit, never -A

git add -A in a multi-session repo is a context-poisoning move. It pulls in unrelated dirty files from other workflows and creates commits that no one — not the human, not the next agent — can reconstruct intent from. Stage only the paths this turn touched.

Code

Coding-agent context checklist·yaml

coding_context_checklist:
  - read repo instructions (CLAUDE.md, sibling overlays)
  - check git status (identify unrelated dirty files)
  - inspect target files
  - run focused validation (pytest path/to/test::case)
  - stage explicit paths only
  - write a commit message that future-instances can read cold
  - record commit/push boundary in handoff

Multi-session safe staging·bash

# Bad (in a repo other sessions also touch):
#   git add -A && git commit -m "..."

# Good:
git add backend/auth.py tests/test_auth.py
git commit --only \
  backend/auth.py tests/test_auth.py \
  -m "fix(auth): tighten session expiry check"

Code survives, rationale rots

Never trust stale docs blindly

Stage explicit, never -A

Code

External links

Exercise

Progress

Comments 0