Your test test_empty_amount_returns_validation_error
is failing. Claude Code has edited the same handler twice, reopened the same files, and now proposes the first rejected patch again. Halfway through the conversation, you also asked it to update the README. Should you continue, trigger context compaction, or start a fresh session?
Run the focused test first. If no edit has been tested, the immediate problem is diagnosis, and a new session will only repeat the guesses. If the failure is reproducible and the facts are recorded, but Claude Code mixes the bug with documentation or forgets a rejected result, choose the right context management tool.
There is no universal threshold based on tokens, messages, or tool calls. Use observable task behavior.
For this example:
Importing a row with an empty amount crashes.
Expected: return a validation error and write no data.
Run the narrowest available test:
npm test -- tests/import/empty-amount.test.ts
Two outcomes are possible:
Restarting before reproduction removes a history of guesses. It does not produce evidence about the cause.
Different symptoms require different actions. Use this decision matrix:
| Observable symptom | Likely cause | Recommended action |
|---|---|---|
| Session remembers symptom and proposes a new testable hypothesis | Clean context, normal progress | |
| Continue: keep working in current session | ||
| Context grew large due to command outputs/logs, but goal is clear | Noise accumulation in tool outputs | |
Compaction: run /compact command |
||
| Session re-proposes rejected patch `Number(value | 0)` | |
| Second task (e.g., README) mixed into dialogue | Context boundary drift | |
| New Session: split into separate branch | ||
| Agent repeatedly reads files without new hypotheses or checks | Search loop / lost direction | |
| New Session: collect facts manually |
The /compact
command is useful when the agent is on the right track but the context is overwhelmed by large terminal outputs or intermediate diffs. However, never let the agent write code immediately after compaction.
Run a mandatory post-compaction check:
We just compacted context. Before editing code, answer 4 questions:
1. What exact symptom are we fixing and what is the expected result?
2. Which approach was already tested and why was it rejected?
3. Which files are allowed to be modified?
4. What single command will verify the next step?
Number(value || 0)
and the constraint on public CSV format, continue in the same session.This is enough for the example bug:
Goal: empty amount returns a validation error and writes no data
Files: parser/amount.ts, tests/import/empty-amount.test.ts
Reproduction: npm test -- tests/import/empty-amount.test.ts -> failed
Rejected: Number(value || 0), because empty became zero
Constraint: do not change the public CSV format
Open question: where to distinguish empty from a valid zero
Next step: trace value from CSV parsing to the validation branch
Do not include API keys, cookies, .env
contents, personal data, or raw logs containing secrets. Keep the minimum error excerpt, timestamp, and path to a safely stored local log.
Give the handoff to the new session and verify it against this checklist:
Read the handoff. Before editing, state:
1) expected result;
2) two target files;
3) rejected approach and reason;
4) next check command.
Only after confirming all items should the new session read target files, make the smallest edit, and rerun the focused test.
Continue when the session remembers the symptom, uses the last test result, and can name the next check. A long conversation can remain useful while each action reduces uncertainty.
Clarify the specification instead of restarting when the unresolved question is product behavior, such as whether empty amount
should be invalid or treated as zero. A clean context cannot make that owner decision.
When Claude Code uses a separate API provider, do not copy keys or changing configuration fields into the handoff. BetterToken supports Claude Code through an Anthropic-compatible API with the user's own account and key. This is separate API access, not a replacement for Claude.ai or Claude Max.
Open the current BetterToken Claude Code guide, verify the current Base URL, key group, and model, then run a small test request. The handoff only needs to say that the setup was checked; it must not contain secret values.
Run the focused test and name the next expected result. If the symptom is reproduced, but the session repeats rejected actions, mixes tasks, or loses constraints after /compact
, write a short handoff and open a new session. Its first job is to restate the boundaries and complete one safe verification.
Originally published on the BetterToken blog.
BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.