Write the project instruction file as a handoff: state, live URLs, gotchas, how to verify
Before clearing an agent's context, rewrite the repo's CLAUDE.md as a handoff, not a spec: a status line, what exists (files, endpoints, data fixtures), deployment facts (live URLs, which env vars the host needs, auto-deploy gotchas), exact commands for the machine (for example python -m uv when uv is not on PATH, and ruff format on directories because ruff format . also rewrites code blocks inside markdown), open items, and a 'hard-won lessons' list of the traps that cost time (stale deploys, test data left behind by agent memory tools, misleading scan names, shell noclobber leaving stale output, build-time env vars). Verify counts against the repo first (tests passing, files present) so the file does not drift from reality, scan it for secret values before committing, and commit and merge it so it survives, not just sits in the working tree.