Context must serve the task
A general problem description is not enough: without concrete facts, Claude starts filling gaps with assumptions. A non-trivial task needs a compact materials package that helps clarify the symptom, find the likely change area, and verify the result.
A quality context package is not the largest possible number of files. Each element must have a clear role in investigation or verification.
| Concept | Meaning |
|---|---|
| Context | Code, logs, tickets, tests, configuration, and other materials for the work |
| Evidence | A fact that can be directly observed or confirmed |
| Noise | Material that helps neither analysis nor verification |
What can be included in an evidence package
| Artifact | Purpose |
|---|---|
| Reproduction steps | Show the sequence that leads to the problem |
| Affected files | Limit the search area |
| Log or stack trace | Provide technical facts about the failure |
| Screenshot or video | Capture actual UI behavior |
| Existing test | Show current guarantees and gaps |
| Similar code | Suggest a pattern already accepted in the project |
| Ticket and business context | Explain impact and priority |
| Safe configuration | Clarify the environment without exposing secrets |
Example package for a duplicate refund
For a problem involving repeated creation of a refund request, it is useful to combine the symptom with the technical flow: a double-click scenario, a test order identifier, a log with two requests, the UI component, the backend controller, an existing idempotency example, and a screenshot.
RefundButton.tsx— the user action point;RefundController.java— the entry point into the backend flow;CancelOrderService.java— an analogous protection against repetition;- the log and screenshot — observable evidence, not assumptions.
EVIDENCE_LOG.md and TASK_SPEC.md
`EVIDENCE_LOG.md` stores investigation facts, open questions, and materials, while `TASK_SPEC.md` formulates a concise contract for the future change. They should not be turned into duplicate versions of one document.
# EVIDENCE_LOG.md
## Problem
Double-clicking creates two refund requests.
## Reproduction
1. Open the test order.
2. Click the refund button twice.
3. Check the log entries.
## Facts
- UI: RefundButton.tsx
- Backend: RefundController.java
- Log: logs/refund-duplicate.log
## Open question
Do the two requests come from the client, or does duplication occur on the server?When the package is sufficient
- You can describe precisely what is working incorrectly.
- There is a controlled reproduction scenario.
- The likely change area is known, or it is clear what still needs investigation.
- How to confirm a successful fix has been defined in advance.
- The materials have been cleared of secrets and unnecessary personal data.
Canonical lesson source · JavaRush
Open JavaRush material