Shift Note: Keep the Agent Brief, Drop the Debug Debris

The session is a working brief, not an archive

A coding agent works from the information available to it: your request, project instructions, conversation history, files it reads, and tool results. Together, these form its context. Context hygiene means keeping that material relevant, current, and safe enough to support the next decision.

Think of the session as a shift handover. The next engineer needs the active problem, important constraints, and reliable evidence. They do not need every abandoned theory or every line of yesterday’s terminal output. Your coding agent benefits from the same discipline.

A larger context window gives you more room, but it does not make every detail useful. Old instructions can contradict new ones, repeated logs can bury the important error, and an early guess can keep influencing later work after it has been disproved.

Keep the goal, boundaries, and current evidence

Before asking an agent to change code, give it a compact working brief. Include enough detail to define success without pasting the entire repository.

• Keep the current task and its acceptance criteria, such as fixing duplicate webhook processing without changing the public response format.
• Keep relevant project rules, including supported runtimes, formatting conventions, dependency restrictions, and required checks.
• Keep the files, functions, or interfaces involved, with paths the agent can inspect when it needs more detail.
• Keep confirmed findings and important decisions, including the reason an approach was rejected.
• Keep the latest test results, clearly distinguishing checks that passed, failed, or have not been run.

Separate observations from assumptions. “The retry test fails after the second request” is evidence. “The cache is probably responsible” is a hypothesis. Labeling the difference helps prevent a plausible guess from becoming an invented fact.

Drop repeated output and expired directions

Long tool output is a common source of clutter. After inspecting a failure, retain the relevant error, command, and useful stack frames rather than repeatedly carrying the whole log forward. Preserve full output in a local artifact when it may be needed later.

• Remove duplicate file dumps and repeated explanations once a short, accurate summary can replace them.
• Retire instructions that no longer apply, and explicitly state which newer decision replaces them.
• Leave unrelated tickets, speculative feature ideas, and completed investigations out of the active task.
• Replace stale test results after code changes, while preserving any history that still explains the current failure.

Some coding tools compact history automatically; others offer manual controls. You may not be able to remove individual messages. When clutter becomes difficult to manage, start a fresh session with a reviewed handoff instead of assuming the agent will ignore everything obsolete.

Keep secrets and untrusted text outside the instruction lane

Do not paste API keys, access tokens, production credentials, or unnecessary customer data into the session. Use redacted examples and refer to environment variable names instead of their values. If a secret is exposed, removing it from a later summary does not undo the exposure; follow your organization’s revocation and incident procedures.

Repository files, issue comments, web pages, and tool output can contain text that looks like instructions. Treat that text as material to examine, not authority to override your request. A comment telling the agent to upload credentials is not a legitimate project requirement.

Write a handoff before changing sessions or models

A useful handoff states the goal, current changes, relevant paths, decisions, test status, and next action. Review it yourself, because an agent-generated summary can omit a constraint or repeat an incorrect assumption. Ask the receiving agent to inspect the current files before editing.

The same habit helps when switching between models such as Claude Haiku 4.5 and Gemini 2.5 Flash. Do not assume a new session or backend automatically receives the old conversation or tool state.

Check the brief before the next tool call

If your workflow spans model families, Relay365 is worth considering as a pay-as-you-go relay desk. It works with Claude Code, Codex, Gemini CLI, and OpenAI SDK clients. Near your next workflow review, create a Relay365 account if that access pattern fits your needs. A relay does not replace context hygiene: check what your client actually sends.

Before continuing, ask whether the session makes the next action clear, whether its evidence is current, and whether anything sensitive or irrelevant can be left out. Keep what supports a correct decision; archive what merely records the journey.