Manage Prompt and Context Hygiene in Long Coding Sessions

## TL;DR

Long coding sessions go better when context is intentionally managed. Start
with a session contract, separate durable project facts from temporary task
context, checkpoint decisions, refresh stale evidence, and close with a
privacy-safe handoff. If a prompt has become a pile of old assumptions, pause
and summarize what is still true before continuing.

## Prerequisites & Requirements

- [ ] {"task": "Session goal is narrow", "description": "The next objective can be stated in one or two sentences"}
- [ ] {"task": "Source of truth is known", "description": "Repository state, issue links, docs, and test commands are identified"}
- [ ] {"task": "Durable memory boundary exists", "description": "Stable facts are separated from temporary scratch context"}
- [ ] {"task": "Checkpoint habit is defined", "description": "Decisions, blockers, and changed files are summarized at natural pauses"}
- [ ] {"task": "Privacy filter is active", "description": "Secrets, full private logs, and unrelated files stay out of prompts and summaries"}

## Core Concepts Explained

### Context is not the same as truth

Conversation context is useful, but it can become stale. A long session may
contain old branch state, outdated issue status, failing checks that later
passed, or assumptions from before a rebase. Re-check live facts before making
decisions that depend on current repository or documentation state.

### Durable memory should stay boring

Claude Code memory and project instructions are best for stable preferences,
repository conventions, and repeated workflow notes. Avoid storing transient
debug logs, secrets, private customer details, or one-time assumptions as
durable memory.

### Slash commands reduce prompt drift

For repeated workflows, a slash command can keep the prompt shape consistent.
Use this for recurring tasks such as review summaries, release notes, test
plans, or handoff reports instead of rewriting a slightly different prompt each
time.

### Checkpoints keep the session navigable

A checkpoint is a small summary of what changed, what was decided, what remains
unknown, and what should happen next. It helps the next prompt start from a
cleaner state without dragging every old detail forward.

## Step-by-Step Workflow

1. **Start with a session contract.** Write the objective, repository or issue
   scope, constraints, and verification target. Keep this shorter than the task
   itself.

2. **Separate stable facts from scratch context.** Put stable project
   conventions in project memory or instructions. Keep experiments, error
   output, and partial theories in the active conversation only.

3. **Feed the smallest useful evidence.** Prefer changed-file lists, focused
   excerpts, source URLs, and relevant test output over full logs or whole
   directories. Add more context only when the next decision needs it.

4. **Refresh time-sensitive facts.** Re-check issue state, PR checks, package
   docs, dependency versions, or remote branches when the answer depends on the
   current state.

5. **Use checkpoints at natural breaks.** Summarize after a rebase, failed test
   investigation, design decision, merged PR, or switch to a new issue.

6. **Name stale assumptions.** When something changes, explicitly say which old
   assumption is no longer valid. This prevents later prompts from reviving it.

7. **Turn repeatable prompts into slash commands.** If a workflow is used
   repeatedly, make its instructions consistent and reviewable instead of
   improvising a new version every time.

8. **Use hooks only for narrow reminders.** Hooks can help with deterministic
   reminders or summaries, but keep them scoped and privacy-reviewed because
   they can run automatically around lifecycle events.

9. **End with a handoff.** Record completed work, remaining files, validation
   status, open risks, and exact next steps. Leave out secrets and unnecessary
   private data.

## What to Keep, Refresh, or Drop

| Context type | Action | Reason |
| --- | --- | --- |
| Stable repo conventions | Keep in memory or project instructions | Useful across sessions |
| Current issue or PR state | Refresh before action | GitHub state can change quickly |
| Test output | Keep latest summary | Old failures may no longer matter |
| Full logs | Drop after extracting evidence | Large logs add noise and may contain secrets |
| Design decisions | Checkpoint | Helps future prompts understand why |
| Temporary hypotheses | Drop or mark stale | Prevents old theories from becoming facts |
| Secrets or credentials | Never include | Not needed for prompt quality |

## Checkpoint Template

```text
Goal:
- Current objective and issue/PR link

Done:
- Files changed, decisions made, checks run

Still true:
- Confirmed constraints and source URLs

Needs refresh:
- Anything time-sensitive, remote, or unresolved

Next:
- One to three concrete next actions

Privacy:
- Notes on omitted secrets, logs, or private data
```

## Review Checklist

- [ ] {"task": "Prompt is scoped", "description": "The prompt asks for one job, not the whole project"}
- [ ] {"task": "Evidence is current", "description": "Remote state, docs, tests, and issue status were refreshed when needed"}
- [ ] {"task": "Memory is durable", "description": "Only stable non-secret facts are stored outside the conversation"}
- [ ] {"task": "Old assumptions are labeled", "description": "Changed facts are called out explicitly"}
- [ ] {"task": "Handoff is concise", "description": "The summary includes next steps without dumping raw private context"}
- [ ] {"task": "Sensitive data is filtered", "description": "Credentials, private logs, and customer data are omitted or redacted"}

## Troubleshooting

- **Claude keeps following an outdated plan**: pause and write a fresh
  checkpoint that lists which prior assumptions are stale.
- **The prompt is getting too broad**: split the work into a decision prompt, an
  implementation prompt, and a validation prompt.
- **Important details keep getting lost**: promote stable conventions into
  project memory or a reviewed slash command.
- **The session contains too much private data**: extract only the relevant
  finding, redact sensitive values, and continue from a smaller summary.
- **A handoff is too long to use**: keep only goal, current state, validation,
  blockers, and next actions.

## Duplicate Check

This guide focuses on managing prompt and context hygiene during long Claude
Code coding sessions. Existing entries cover broad multi-directory workflows,
slash command creation, hooks, and individual automation patterns, but they do
not provide a source-backed guide for checkpoints, durable memory boundaries,
stale-assumption review, and privacy-safe handoffs in long sessions.

## References

- Claude Code memory - https://code.claude.com/docs/en/memory
- Claude Code common workflows - https://code.claude.com/docs/en/common-workflows
- Claude Code slash commands - https://code.claude.com/docs/en/slash-commands
- Claude Code settings - https://code.claude.com/docs/en/settings
- Claude Code hooks - https://code.claude.com/docs/en/hooks