The animated scenes show on a laptop or desktop screen.
Built-in tools
Exploring a large codebase with built-in tools
Delhivery delivers parcels across India through its own centres and partner centres. From 1 November, it wants every express cash-on-delivery shipment worth more than ₹50,000 sent only to a centre that Delhivery runs itself. The code that picks a centre is somewhere in routing_engine, a ten-year-old Python service of about 1,800 files that nobody on the current routing team wrote. This chapter follows one engineer who explores it with Claude Code, finds the rule and changes one line, and then makes sure that what Claude found is still available after a long day of work and after an overnight run.
What this chapter shows you
- Search first, then read only what the search finds. Reading every file fills Claude's context window before it reaches the code that matters.
- Edit replaces one exact piece of text. When the same text appears four times, Claude reads the whole file and writes it back.
- A long session needs notes, /compact and subagents. Claude recalls early findings less accurately as a session grows, and these three keep late answers naming the exact class and file.
- An overnight run needs phase summaries and a manifest. After a crash, the run restarts only the work that was not finished.
- Check yourself. Pick the jobs that need Grep, then answer one question in the exam's style.
Part 1: Search first, then read only what the search finds
Delhivery's operations team has asked for one rule. From 1 November, an express shipment paid by and worth more than ₹50,000 must go only to a centre that Delhivery runs itself, never to a partner centre. Today such a shipment can go to any centre. The rule has to change wherever the code picks a centre, and nobody on the routing team knows where that is.
The code is in routing_engine, Delhivery's routing : a Python service about ten years old, with about 1,800 files and about 3 lakh lines. An engineer on the routing team opens it in , Anthropic's coding tool, which runs in a on the engineer's laptop. Claude Code sends the engineer's question to Claude, runs the tools Claude asks for on the laptop and sends the results back. This back and forth, in which Claude asks for a tool and Claude Code runs it and returns the result until Claude can answer, is called the agent loop. Chapter 7 builds this loop step by step. In the drawings, Claude is an octopus and Claude Code is an operator in a cap marked >_.
are the tools that come with Claude Code itself, which Claude can ask for without anyone writing them. Claude Code has many built-in tools. The guide for Anthropic's certification exam, Claude Certified Architect (Foundations), names six of them: , , , , and . One of the exam's scenarios, developer productivity, is built on them. This part covers the three that find and read code: Read, Glob and Grep.
Reading the codebase file by file fills the context window first.
The is the amount of text Claude can take in for one request: the instructions, the conversation so far and every tool result. When it is full, nothing more fits, and well before that point Claude recalls the earlier parts less accurately.
Read returns the contents of one file, with line numbers. Each Read adds that file to the context window, where it stays until Claude Code clears older tool results, compacts the conversation or the conversation is cleared. An ordinary file in routing_engine takes about 1% of the context window, but many files in the older folders, legacy/ and v1/, run to 500 to 1,000 lines each and take three or four times as much.
The engineer asks in the obvious way: read the codebase first, then answer. Claude lists the files in each of the six folders, starts with api/, where requests come in, goes on to the oldest folders, legacy/ and v1/, and reads one file after another.
Reading every file
The engineer asks where a centre is picked for a COD shipment and asks Claude to read the codebase first. Claude asks for every file, and Claude Code starts with the twelve files in api/, adding each one to Claude's context window.
Claude Code reads the twelve files in legacy/. These files are long, so each one takes three or four times the space of an api/ file, and the context window fills fast.
After 36 files from api/, legacy/ and v1/, the context window is almost full. Claude has not read the allocation/ folder, and cod_rules.py, the file that holds the rule, is still unread.
Claude has used nearly all of its context window and has still not reached the file the engineer needs, because reading in folder order spends the space on whichever files come first.
Reading every file fills the context window
Claude asks for Glob, which lists the files whose paths match a pattern. The pattern */* means any file directly inside a folder, so Glob lists the 72 files in the six folders. Most of the 1,800 files sit in subfolders further down.
The 72 paths go up to Claude, and Claude asks for Read on the twelve files in api/.
The api/ files take the context window to 15%. Claude asks for the twelve files in legacy/.
The legacy/ files take it to 60%. Claude asks for the twelve files in v1/.
After 36 files the context window is 95% full, and Claude has not answered. cod_rules.py was in the list, but allocation/ has not been read. Next, Claude Code would clear older tool results and then replace the conversation with a short summary on its own.
Every file Claude reads stays in the context window, so reading in folder order spent the space on files chosen by their place in the list, before anything had shown which files held the rule.
The exam guide's answer is to build an understanding of the code in steps: search for the place where the behaviour starts, then read only the files that lead on from it. Searching needs the right tool, and each built-in tool does one job.
An old design note on the team's wiki says that the that picks a centre is called assign_centre, but it does not say which file it is in.
| Tool | What it looks at | What Claude asks it to do | In routing_engine |
|---|---|---|---|
| Grep | The text inside files | Find the files that contain this text. | Which files call assign_centre? |
| Glob | File names and paths | Find the files with names like this. | **/test_*cod*.py |
| Read | One file, whole or a range of lines | Show me what this file says. | Read allocation/centre_picker.py |
| Edit | One exact piece of text in one file | Replace this exact text with that text. | Change one line in cod_rules.py |
| Write | A whole file | Make this file contain exactly this. | Write a new cod_rules.py |
| Bash | The terminal | Run this command. | Run the COD tests |
Claude needs every file that calls assign_centre. Which tool should it ask for?
Glob finds files by name, and Grep finds text inside them.
Glob matches file paths against a pattern and never opens a file. In a pattern, * stands for any characters in a name and ** for any number of folders, so **/test_*cod*.py matches every file in any folder whose name starts with test_, contains cod and ends in .py. Glob returns at most 100 paths, sorted by when each file last changed. When more files match, Claude sees only the 100 most recently changed and a note that the list was cut, so it narrows the pattern.
Grep searches the text inside files for a pattern, such as a function name, an error message or an import line. Its patterns are , in which a few characters have special meanings. A bracket is one of them, so to find the text assign_centre( the pattern puts a backslash before the bracket: assign_centre\(. By default Grep returns only the paths of the files that match. It can also return the matching lines with their line numbers, or a count for each file.
Both tools send back paths, which are short, so a search across 1,800 files costs a few lines of context. Claude then reads only the files it needs. Claude asks for each search with a block, a short request in Claude's reply that names the tool and its inputs:
{ "type": "tool_use", "name": "Glob",
"input": { "pattern": "**/test_*cod*.py" } }A Glob call with one input, the name pattern. Claude Code returns the paths of the files whose names match.
{ "type": "tool_use", "name": "Grep",
"input": {
"pattern": "assign_centre\\(",A Grep call. The bracket after the name finds the places where the function is called or defined, and skips lines that only mention the name. The request writes the pattern's one backslash as two.
"output_mode": "files_with_matches" } }The default output: only the paths of the files that match. "content" would return the matching lines with line numbers, and "count" the number of matches in each file.
Glob and Grep
Claude asks for Glob with the pattern **/test_*cod*.py. Glob compares file paths with the pattern and does not open any file.
Claude Code checks every file path against the pattern. Two test files match, test_cod_rules.py and test_express_cod.py, and Claude receives their two paths with none of their contents.
Claude then asks for Grep with assign_centre(, so Claude Code searches the text inside every file.
Three files contain assign_centre(: the file that defines it and two that use it. Claude receives their three paths, and none of the files' text.
Glob found files by their names and Grep found files by the text inside them. Both sent back only paths, so two searches across 1,800 files used a few lines of the context window.
Glob matches file paths, Grep searches file contents
Because the first attempt filled the context window, the engineer starts a new session and asks where the tests for the COD rules are. Claude asks for Glob with **/test_*cod*.py, and two file names match.
Two paths go up to Claude, and the context window moves from 3.1% to 3.2%. The engineer then asks which files call assign_centre.
Claude asks for Grep with assign_centre\(. Three files contain a match: the file where the function is defined, and two that use it. Their three paths go up to Claude.
Suppose Claude had asked Glob for **/*assign_centre* instead. No file is named after the function, so Glob would find nothing, although three files contain the name.
Suppose it had asked Grep for test_ to find the tests. Grep would match 214 files that contain those letters anywhere, and Claude would have to sort through all of them to find the two test files.
Glob compared only file names and Grep searched only file text, and each sent back a short list of paths. With the two tools swapped, Glob found nothing because no file is named after assign_centre, and Grep found 214 files because so many files mention test_.
Anthropic's docs, checked on 22 October 2026, add one detail. On macOS, Linux and , Claude Code does not offer Glob and Grep as separate tools by default, and Claude runs the same searches as terminal commands through Bash. Starting a with Grep or Glob named in , the list of tools Claude may use without asking each time, switches both tools on. Delhivery's team starts its sessions that way. The exam guide treats Grep and Glob as tools, and so does this chapter.
A related exam question: a team adds a better code-search tool from an , a separate program that offers extra tools to Claude, and the agent keeps using Grep. The exam's answer is a clearer description of the new tool, so that Claude can tell when to choose it, and Grep stays available. Chapter 5 covers MCP servers.
Grep finds where the flow starts, and Claude reads each imported file from there.
An is the place in the code where a flow starts, such as the function that runs when a new shipment is booked. An is a line at the top of a Python file that brings in code from another file, so it names the next file in the flow.
The exam guide's way to understand a large codebase is to build an understanding in steps. Claude searches with Grep for a name or message that marks the entry point, reads that file, sees which it imports and calls, reads those next, and stops when the flow is clear. Every file Claude reads is chosen because the file before it pointed there.
Grep has found where assign_centre is defined, but the definition alone does not show which code calls it. The rule must apply to every COD shipment, so the engineer needs the path a COD shipment takes from booking to the centre choice. Claude starts from the data the rule is about. It asks Grep for cod_amount, a field that every COD shipment carries. A field is a named value stored on each shipment, and this one holds the amount the rider must collect. This time Claude asks for content mode, which returns each matching line with its file and line number. Seven files match. In api/shipments.py the matching line checks a shipment's COD amount, and the file's name suggests the place where shipments are booked, so Claude reads that file first. It holds create_shipment(), which runs for every new booking:
from allocation import pick_dcAn import: bring in pick_dc from the allocation folder. This line names the next file to read.
def create_shipment(shipment):
...
centre = pick_dc(shipment)The entry point. Every new booking runs create_shipment(), which calls pick_dc to choose a centre. ... stands for lines left out here.
When code imports from a folder, Python looks in that folder's __init__.py file, so allocation/__init__.py is the next file to read.
Following the imports
Claude asks for Grep with cod_amount, a field that every COD shipment carries. Seven files contain it, among them allocation/rebalance.py, and Claude receives each matching line. One is line 6 of api/shipments.py, which checks a shipment's COD amount.
Claude reads only api/shipments.py. It holds create_shipment(), the function that runs for every new booking, and its import line shows that the code that picks the centre comes from the allocation/ folder, through allocation/__init__.py.
Claude reads allocation/__init__.py, whose import names centre_picker.py, and then reads centre_picker.py.
Claude has read three files, each one named by an import in the file before it. Most of the context window is still free, and every other file is unread.
From the entry point along the imports
Next the engineer asks Claude to trace a COD shipment from booking to the centre it gets. Grep for cod_amount in content mode matches seven files, and one matching line is line 6 of api/shipments.py, if shipment.cod_amount > 0:.
Read api/shipments.py: line 1 imports pick_dc from allocation, and line 8 calls pick_dc to choose the centre.
Read allocation/__init__.py: line 2 imports assign_centre under the name pick_dc. Read allocation/centre_picker.py: line 212 defines assign_centre, and line 1 imports the COD rules.
3 of about 1,800 files read, and the context window is 6.3% full. The next file to read is cod_rules.py.
Following the imports reached the function that picks a centre after three files, where reading in folder order had used 95% of the context window without reaching it.
A wrapper module gives a function other names, so a Grep for one name misses the rest.
A is a file that passes on code from another file, often under a new name. The new name is called an . In routing_engine, allocation/__init__.py is a wrapper. It passes on assign_centre under its own name and under two others:
from .centre_picker import assign_centrePass on assign_centre from centre_picker.py under its own name.
from .centre_picker import assign_centre as pick_dcPass on the same function under a second name, pick_dc. A file that imports pick_dc calls assign_centre without ever writing that name.
def route_to_centre(shipment):
return assign_centre(shipment)A third name: a short function that only calls assign_centre. Older code calls it as route_to_centre.
Grep matches text, so a search for assign_centre cannot find a line that says pick_dc(shipment). The guide's method is to read the wrapper first, list every name it exports for the function, and then search with Grep for each name.
Wrapper module
Claude asks for Grep with assign_centre. Grep matches only that exact name, so it finds 1 of the 15 files that call the function. The other 14 call it under a different name.
Claude reads the wrapper module, allocation/__init__.py. Its export lines give the function three names: assign_centre, pick_dc and route_to_centre, a short function that calls assign_centre.
Claude asks for Grep with pick_dc and then with route_to_centre. The two searches find the other 14 callers, so all 15 files that call the function are found.
Grep finds only the name it is given, and one function can have several names. Reading the wrapper first gives Claude every name to search for.
Every name a wrapper exports
Claude asks for Grep with assign_centre. Three files match: centre_picker.py, where the function is defined, the wrapper allocation/__init__.py, and legacy/old_router.py, the only caller that uses this name.
Read allocation/__init__.py: line 1 exports assign_centre, line 2 exports it again as pick_dc, and line 4 defines route_to_centre, which calls it.
Grep for pick_dc adds 9 callers, and Grep for route_to_centre adds 5. Leaving out the definition and the wrapper itself, 15 files call the function.
Two of the nine pick_dc callers matter here: api/shipments.py, the entry point for every booking, and returns_handler.py in the returns flow, which sends undelivered shipments back. The first search found neither.
The first search found 1 caller, and the real number was 15. A change planned from the first search would have missed the call in create_shipment(), which every new booking makes, and the two calls in returns_handler.py.
Part 2: Edit replaces one exact piece of text
Claude now knows where the rule is: allocation/cod_rules.py, and it asks for on the file. A script wrote this file in 2016, which is why the four rule blocks are word for word the same. It has a list of four products, PRODUCTS, and a list of four rules, RULES, matched by position, so RULES[1] belongs to the second product, express.
PRODUCTS = ["surface", "express", "heavy", "b2b"]The four products, in order. Surface is delivery by road. Counting starts at 0, so express is number 1.
RULES = [
Rule(
limit=COD_LIMIT,
above_limit=ANY_CENTRE,
),The first rule, for surface. COD_LIMIT is ₹50,000, set in cash_limits.py in the repository's top folder, and above it the shipment can go to any centre.
Rule(
limit=COD_LIMIT,
above_limit=ANY_CENTRE,
),
...The second rule, for express, is word for word the same as the first. Two more identical rules follow, for heavy and for .
Only the express rule should change: its above_limit must become DELHIVERY_RUN_ONLY.
Edit needs text that appears exactly once.
changes one piece of text in a file. Claude gives the exact text to find, , and the text to put in its place, new_string. Edit does not use patterns or close matches. old_string must appear in the file exactly as written, down to the spaces, and it must appear exactly once, so that there is only one place for Edit to change.
{ "type": "tool_use", "name": "Edit", "input": {
"file_path":
"/Users/dev/routing_engine/allocation/cod_rules.py",Edit works on one file, named by its full path on the engineer's laptop.
"old_string": "above_limit=ANY_CENTRE,",The exact text to find. In this file it appears four times, once in each rule.
"new_string": "above_limit=DELHIVERY_RUN_ONLY," } }The text to put in its place.
rejects the edit and leaves the file unchanged, because the text appears four times. Anthropic's docs describe two ways to handle a repeated old_string. The first is a longer old_string that takes in enough of the lines around the change to appear only once. Here the lines around the express rule do not help. The lines just above it are the end of the surface rule, and the lines just below it are the start of the heavy rule, and both are the same as in every other rule. Text that appears only once has to reach up to RULES = [ or down to the closing bracket, so it also takes in the whole surface rule, or the heavy and B2B rules. The second way is , which changes every copy, and here it would also change surface, heavy and B2B.
When Edit fails because its text is not unique, the exam guide's answer is to Read the whole file and then it back, and that is the answer to give in the exam. Write makes a file contain exactly the content Claude gives it. It does not match anything, so it cannot fail for that reason, and it does not merge with the old file, so anything Claude leaves out of the new content is deleted. That is why Claude works from a full Read of the file, and reads it again just before writing when the file may have changed since, for example because a teammate saved a change to it.
As of 22 October 2026, Anthropic's docs suggest trying a longer old_string first. Here that would be an old_string from RULES = [ down to the express line, with the surface rule copied unchanged into new_string. That Edit would work, and to change one line it would also rewrite the surface rule's text. The exam guide's answer for this case is still Read followed by Write.
The engineer reviews every change as a , a proposed change that teammates check before it goes in. Claude Code also asks the engineer for permission before it runs Edit, Write or a command that is not on its list of read-only commands, unless the team has allowed that tool in advance. Read, Grep and Glob run without asking inside the project folder.
After the change, Claude adds a test for the new express rule and asks for Bash, which runs a command in the , to run the with pytest, the command that runs Python tests. In the exam's framing Bash is for running commands, such as the command that runs the tests, while finding files is the job of and searching inside them is the job of .
Edit needs one exact match
Claude has already read cod_rules.py. It asks for Edit to replace above_limit=ANY_CENTRE, with above_limit=DELHIVERY_RUN_ONLY,. That text appears in four places, so Claude Code rejects the edit and the file is unchanged.
Claude tries the whole four-line rule block as the text to find. The four blocks are identical, so this is rejected too. Text that appears only once has to run up to RULES = [ or down to the closing bracket, so it takes in other products' rules.
Edit's replace_all: true setting would change every place the text appears, including the surface, heavy and B2B rules. Claude does not use it.
Before writing, Claude asks for Read on the whole file again, because Write replaces all of it and the file may have changed since the first Read.
Claude sends the complete file back with Write, with only the express rule changed. Write replaces the whole file with what Claude sends.
Edit cannot choose between four identical places. When no text that appears once covers the express rule alone, the exam guide's answer is to read the whole file and write it back with one change.
Edit, then Read and Write
Edit with old_string set to above_limit=ANY_CENTRE, matches lines 11, 15, 19 and 23. Claude Code rejects the edit and leaves the file unchanged.
Edit with the whole four-line rule block also matches four times and is rejected. Text that appears once has to reach up to RULES = [, taking in the surface rule, or down to the closing bracket, taking in heavy and B2B.
With replace_all: true the edit would change lines 11, 15, 19 and 23, and three of them belong to surface, heavy and B2B, so Claude does not run it.
Read allocation/cod_rules.py returns all 29 lines.
Write sends all 29 lines with line 15 changed, and the pull request's diff for cod_rules.py shows one changed line, in the express rule.
Claude adds a test for an express COD shipment above ₹50,000 to tests/test_cod_rules.py. Bash runs pytest on the file: 13 passed, the 12 existing tests and the new one.
Edit needs exactly one place to change, and this file had four identical places, so Claude read the whole file and wrote it back with only line 15 changed. The pull request the engineer reviews shows that one line.
The exam marks Read followed by Write as the answer when an Edit fails because its text is not unique. Two wrong answers recur: retrying the same Edit, which fails the same way, and writing a new version of the file from memory without reading it, which can delete lines Claude did not know were there.
Part 3: A long session needs notes, /compact and subagents
With the rule changed, the engineer spends the rest of Thursday 22 October mapping everything else the 1 November change touches: the weight checks, the tests and the , the code in returns_handler.py that sends undelivered shipments back. By 4:30 pm the has run for more than six hours, and its holds dozens of file reads, mostly line ranges, and well over a hundred searches.
Context degradation makes late answers generic.
is the drop in answer quality as a session's context window fills. Earlier content is still in the context window, and Claude recalls it less accurately. The exam guide describes the symptom: answers start to mention typical patterns where earlier answers named the specific classes Claude had found, and two answers about the same code disagree. Anthropic's engineering team reports that this happens with every model.
At 10:15 am Claude had found that WeightSlabValidator, a in allocation/slabs.py, checks a shipment's weight slab, the weight range the shipment falls in, before a centre is picked. assign_centre calls it on line 213.
Context degradation
At 10:15 am Claude reads allocation/slabs.py. Asked what checks the weight slab, it names the class and the file, WeightSlabValidator in allocation/slabs.py, and the engineer can open that code directly.
Through the day Claude reads many more files and search results, and by 4:30 pm the context window is nearly full. The 10:15 am finding is still there, near the start of a long conversation, and Claude now recalls it less accurately.
At 4:30 pm the engineer asks the same question, and Claude answers “Typically, a routing service would check the weight slab here.” That answer names no class and no file, so the engineer cannot find the code from it.
Later answers became vague although the earlier finding was still in the context window. This is context degradation. The exam guide's sign of it is an answer that describes a typical pattern where an earlier answer named the class.
Context degradation: the late answer turns generic
10:15, “What checks the weight slab?”: the answer names WeightSlabValidator in allocation/slabs.py, with the context window at 18%.
Grep and Read calls run until 16:30, and the context window reaches 92%.
16:30, the same question: the answer begins “Typically” and names no class.
Nothing was removed from the context window between 10:15 am and 4:30 pm. The finding was still there and Claude recalled it less accurately, which is what context degradation means.
Switching to a model with a larger context window does not fix this, because recall drops as the context grows on every model. Telling Claude to remember the classes it found does not fix it either. The class is already in the context, and an instruction to remember it adds one more line to the same long context without making the earlier part easier to recall.
A scratchpad file keeps each finding outside the conversation.
A is an ordinary file in the where Claude writes each finding once it is confirmed: the file, the or class, the line and what it does. Before answering a later question, Claude reads the file. The answer then comes from a short file on disk instead of from a long conversation. This helps within one long session too, because reading the file puts the confirmed finding in one short line at the end of the context, next to the question, instead of where it was first found, near the start of a long conversation. The file also stays exactly as it is when the engineer types in Claude Code's terminal, a command that empties the conversation, and when a new session starts.
Thursday's findings exist only as answers in Thursday's long session, which the engineer closes at the end of the day. On Friday morning the engineer starts a new session, pastes in the list of Thursday's answers and gives one more instruction. Claude re-checks each answer with and before writing it in the file, using Grep's content mode where it needs a line number. By noon the file holds five confirmed findings and one open question:
> Record each confirmed finding in exploration-notes.md,
and read it before you answer a question about the code.The engineer's instruction at the start of the session. It is English that Claude reads, like any prompt.
# exploration-notes.md: COD centre assignmentThe file Claude keeps in the repository's top folder. Its first line says what the notes are about.
- Entry point: api/shipments.py create_shipment() calls pick_dc()
- allocation/__init__.py exports assign_centre, pick_dc (alias),
route_to_centre
- assign_centre() in allocation/centre_picker.py, line 212,
picks the centre by pin codeEach confirmed finding is one line with the file, the function and what it does, so a later answer can name them exactly.
- COD rules: allocation/cod_rules.py RULES, matched to PRODUCTS
by position; express is RULES[1]
- Weight check: WeightSlabValidator in allocation/slabs.py
- Open: returns_handler.py calls pick_dc (lines 88, 141);
which COD rule applies to returns?The class, confirmed again on Friday, is written down, and the last line records what is still open, so that in the next session Claude can see where to continue.
Claude creates the file with . To add each later finding it uses , which can only replace text, so it replaces the file's last line with that same line followed by the new finding.
To make every new session start this way, the team can put the same instruction in the project's , a file of instructions that loads at the start of every session. Chapter 2 covers it.
Scratchpad
Friday morning is a new session. Claude re-checks each of Thursday's answers with Grep and Read and writes one line about each confirmed finding in exploration-notes.md, a file in the repository. By noon it holds five findings and one open question.
Claude keeps reading files through the afternoon, and the context window fills past half. The notes file stays exactly as Claude wrote it.
On Friday evening the engineer types /clear, which empties the conversation, and on Monday a new session starts with an empty context window. The notes file is still in the repository with every line Claude wrote.
On Monday the engineer asks Claude to read exploration-notes.md first, and Claude names WeightSlabValidator in allocation/slabs.py. The file is on disk, so its findings stay exact between sessions.
Scratchpad file: exploration-notes.md
Friday, new session: Write creates exploration-notes.md with the first finding, and an Edit adds each later one. By noon the file holds five findings and one open question, and the context window is at 18%.
Friday evening, /clear: the context window drops to 3%, and the file still holds every line.
Monday, new session: the engineer asks Claude to read the notes first. Read exploration-notes.md, and the answer is WeightSlabValidator in allocation/slabs.py, with the context window 4% full.
The notes file stays the same through /clear and into a new session, because it is a file in the repository, outside the context window.
The findings were in a file on disk, outside the context window, so clearing the conversation and starting a new session removed nothing from them. On Monday the answer came from the file, and it named the class again.
/compact replaces the conversation with a summary.
is a Claude Code command that replaces the conversation so far with a summary, and the session continues from the summary. It frees most of the context window and keeps the main decisions. Text typed after the command tells the summary what to keep, as in /compact focus on COD centre assignment and keep every file path. Claude Code also compacts on its own when the context window is nearly full, and then it decides what the summary keeps. Typing /compact earlier lets the engineer choose the moment and say what the summary must keep.
/compact suits a session whose findings are still needed. /clear empties the conversation completely and suits a switch to an unrelated task. Neither of them changes files on disk, such as the scratchpad.
On Monday afternoon, after a few more hours of searching, the context window is 94% full again.
Compact
The context window is full again. The engineer types /compact with focus text asking to keep COD centre assignment and every file path. Claude writes a one-page summary that follows the focus.
Claude Code replaces the whole conversation with that summary. Search output left out of the summary is no longer in the session, and exploration-notes.md does not change.
/compact frees most of the context window and keeps what the focus text asked for. Any detail the summary leaves out is gone from the session, and files on disk are not touched.
/compact with a focus
The context window is 94% full. The engineer types /compact focus on COD centre assignment and keep every file path.
The context window drops from 94% to 12%. The summary keeps the entry point, the three names, the express rule, the open question about returns_handler.py and the file paths.
exploration-notes.md is unchanged, with every finding. It still gives line 212 for assign_centre, which the summary did not keep. The session continues from the summary.
A focused /compact keeps what the engineer names and drops the rest, so exact details such as line numbers last only in the notes file, which no command touches.
A subagent searches in its own context window and sends back only its answer.
A is a separate Claude instance with its own context window. Claude starts one by asking for a tool, with one question as the subagent's prompt. The exam guide calls this tool Task, and so does this chapter. The subagent runs all its searches and reads in its own context, and only its final message comes back. The main context window receives the answer and none of the search output. Chapter 12 covers subagents step by step.
Claude Code has a built-in subagent for this job, . It can use only read-only tools, such as Read, Grep and , and Write and Edit are denied to it. When Claude starts Explore, it chooses one of three levels of search: quick, medium or very thorough. Anthropic's docs say Claude uses Explore to keep exploration results out of the main conversation.
The engineer needs every file that covers allocation or the rules. Run in the main conversation, that search would put hundreds of paths and file excerpts into the context window.
Subagents
Claude starts a subagent with one question as its prompt: find all test files that cover allocation or the COD rules, and return the paths by module. The subagent's context window holds its own instructions and that prompt, and nothing from Claude's conversation.
The subagent asks for searches and reads in tests/, and Claude Code runs them. The results fill the subagent's own context window, and Claude's context window does not change.
The subagent sends back one final message, “14 test files, by module”. Only that message reaches Claude, and the search output stays with the subagent.
Explore is Claude Code's built-in subagent for searching a codebase. It can use read-only tools such as Glob, Grep and Read, and it cannot use Write or Edit.
Claude can ask Explore to search at one of three levels, quick, medium or very thorough, and it chooses the level when it starts Explore. A subagent keeps search output out of Claude's context window and returns only its answer.
The Explore subagent keeps search output out of the main context window
Claude starts Explore, very thorough, and the terminal shows the call as one row, Explore(Find test files for allocation and the COD rules). The prompt goes to the subagent's own conversation.
Glob, Grep and Read lines fill the subagent's context window to 70%. The main context window stays at 12%.
Only “14 test files, by module” comes back to the terminal, and the main context window moves to 13%. None of the files the subagent read reaches Claude.
Explore's tools are read-only, such as Read, Grep and Glob, and Write and Edit are denied. Claude chose the most thorough of the three levels.
The search output stayed in the subagent's own context window, so the main conversation took in only the answer: one line, and one percentage point of its context window.
Anthropic's Agent SDK docs, checked on 22 October 2026, name the tool Agent. It appears as Agent in Claude's requests and as Task in the SDK's list of tools, and code may list either name. The exam guide says Task, and the exam expects Task. Claude Code's terminal shows a subagent call under the subagent's name, such as the Explore row above.
The three fixes in this part do different jobs, and a long exploration often uses all three:
| Fix | What it does | Choose it when |
|---|---|---|
| Notes file | Keeps each confirmed finding in a file on disk, which Claude reads before it answers. | The work runs long or continues in another session, and later answers must name exact classes and files. |
/compact | Replaces the conversation with a summary that keeps what the focus text names. | The context window is filling with old search output and the session still needs its findings. |
| Subagent or Explore | Runs a search in its own context window and returns only the answer. | A question needs many searches and reads whose output the main conversation does not need. |
Part 4: An overnight run needs phase summaries and a manifest
Before 1 November the team wants a complete map of every place where centre assignment happens. Nobody sits at a terminal overnight, so the team writes a small Python program that starts Claude itself through the , Anthropic's library that runs the same agent loop and built-in tools inside Delhivery's own program, and runs until the work is done. A , the main agent, starts three and keeps track of them. test-finder lists the that cover allocation, cod-flow-tracer traces the COD flow from create_shipment() to the chosen centre, and rto-flow-tracer finds which COD rule the applies when returns_handler.py picks a centre again. rto-flow-tracer starts only after cod-flow-tracer has finished, because the returns flow calls the same functions that cod-flow-tracer maps. Each subagent writes its findings as it works to its own , at a path that its instructions give it and that the coordinator knows, such as .explore/rto-flow-tracer.json. The coordinator also keeps a , one file that lists each subagent, its status and where its state file is. The work of Thursday, Friday and Monday was phase 1, and the overnight run is phase 2. Before it starts any subagent, the coordinator reads exploration-notes.md and writes a short summary of phase 1 from its confirmed lines.
AGENTS = {
"rto-flow-tracer": AgentDefinition(
description="Finds which COD rule the returns flow applies.",One of the three subagents. The coordinator reads the description to decide when to start this subagent.
prompt="You trace one flow in routing_engine. After each "
"confirmed finding, update your state file, "
".explore/rto-flow-tracer.json.",The subagent's own instructions, which it reads at the start of its conversation, including the path of its state file. The instructions are one piece of text, split across three lines here.
tools=["Read", "Grep", "Glob", "Write"],
),
...
}The tools this subagent can use: the three that search and read, and Write for its state file. It cannot run commands. ... stands for the other two subagents.
options = ClaudeAgentOptions(
system_prompt=COORDINATOR_PROMPT,
allowed_tools=["Read", "Grep", "Glob", "Write", "Task"],
agents=AGENTS,
)The coordinator's settings. system_prompt holds its instructions. allowed_tools lists the tools the SDK runs without asking anyone, including Task, which starts a subagent. agents holds the three subagent definitions. The exam guide's answer is that allowedTools must include "Task" for a coordinator to start subagents.
Each new subagent needs the phase 1 summary in its prompt.
A is a short list of what one phase of the work confirmed, written before the next phase starts. A new subagent begins with a fresh conversation: apart from its own instructions, the only content it receives from the coordinator is the prompt the coordinator writes when it starts the subagent, and nothing from the coordinator's conversation. The overnight run does not load the project's , so an instruction about exploration-notes.md in that file would not reach a subagent either. Anything phase 1 learned, such as the two other names of assign_centre and the calls in returns_handler.py, reaches the subagent only if the coordinator puts it in that prompt.
A new subagent does not know the notes file exists, or which lines matter, unless its prompt tells it. The guide's design puts the confirmed summary in the prompt so that every subagent starts with it.
Phase summary
Phase 1 is done. Before the overnight run starts any subagent, the coordinator reads exploration-notes.md and writes three confirmed findings and the open question into a phase 1 summary.
Suppose a new subagent got only the question “Which COD rule does the returns flow apply?” It would search returns_handler.py for assign_centre alone and report that the returns flow picks no centre.
The coordinator puts the phase 1 summary in the subagent's prompt. The subagent searches for all three names, finds the calls in returns_handler.py and reports that returned shipments get the surface rule.
A new subagent has only its prompt to work from. The coordinator has to put the phase 1 summary in that prompt for the subagent to use what phase 1 found.
Putting the phase 1 summary in the next prompts
Suppose the Task call to rto-flow-tracer carried only the task line. The subagent's context would hold its own instructions and that line.
Its Grep for assign_centre in returns_handler.py would find no calls, and its result would say that the returns flow picks no centre.
When the coordinator puts the phase 1 summary above the same line, the subagent searches with Grep for all three names and reads returns_handler.py: the product is set to surface before the pick_dc calls on lines 88 and 141.
The prompt that carried the phase 1 summary gave the subagent the other names of assign_centre and where the returns flow calls it, and the subagent found the rule; with the task line alone, it would have searched for one name and reported that the returns flow picks no centre.
Because the returns flow sets every returned shipment to surface before it picks a centre, the 1 November change to the express rule does not reach returns. The routing team reports this to the operations team, which decides whether returns need the same rule.
A manifest lets the coordinator restart only the unfinished work.
A manifest is one file that lists every agent in a run, its status and where its state file is. Delhivery already uses the word for the list of shipments on a vehicle and where each one goes. A run that lasts all night can stop halfway: the program crashes, a timeout ends it, or the laptop running it shuts down. When that happens, every running agent stops and its context window is emptied, and nobody is watching, so the run stays stopped until an engineer starts the program again in the morning. The SDK also saves each conversation to a file on disk, and resuming that file brings back one conversation in full, with all of its search output. After a crash the coordinator needs to know which agents finished and where each agent's findings are. The guide's design for recovery has two parts: each agent writes its findings, as it works, to its own state file at a known path, and the coordinator keeps the manifest.
On restart, the coordinator reads the manifest, skips the agents marked done, and starts each unfinished agent again with its saved findings in the prompt. The manifest is a file, written as names and values.
{
"task": "Map COD centre assignment before 1 November",
"phase": 2,What the run is for, and which phase it is in.
"phase_1_summary": "Entry point create_shipment(); pick_dc
and route_to_centre are aliases of assign_centre; express
COD rule is RULES[1] in cod_rules.py; open: which rule
returns_handler.py applies to returns",The phase 1 summary, which the coordinator wrote from exploration-notes.md before it started any subagent. It is kept in the manifest so that a restarted coordinator has it too. The summary is one piece of text, shown here on four lines.
"agents": [
{"name": "test-finder", "status": "done",
"state_file": ".explore/test-finder.json"},One entry per agent: its name, its status and the path of its state file. test-finder finished at 1:30 am.
{"name": "cod-flow-tracer", "status": "in_progress",
"state_file": ".explore/cod-flow-tracer.json"},This agent was halfway through when the run crashed. Its state file holds what it had confirmed so far.
{"name": "rto-flow-tracer", "status": "not_started",
"state_file": ".explore/rto-flow-tracer.json"}
]
}This agent had not started.
COORDINATOR_PROMPT = (
"Before anything else, read .explore/manifest.json. "
"If it has no phase_1_summary, read exploration-notes.md "
"and write the confirmed findings into phase_1_summary. "
"Skip every agent marked done. Start every agent that "
"is not done with the phase 1 summary in its prompt. "
"For an agent in progress, also put the findings from "
"its state file in that prompt. Start rto-flow-tracer "
"only after cod-flow-tracer is done. Update the "
"manifest whenever an agent's status changes."
)The coordinator's instructions, English that Claude reads. They make every start of the run, including a restart, begin from the manifest. On the first start the coordinator writes the phase 1 summary from the notes file before it starts any subagent, and it puts that summary into the prompt of every agent that still has work to do. They also hold rto-flow-tracer back until cod-flow-tracer is done.
async for message in query(prompt="Continue the mapping run.",
options=options):
...query sends the prompt “Continue the mapping run.” to the coordinator with the settings in options, and the program reads each message as it comes back. After a crash, an engineer starts the program again, which runs these lines and starts a new conversation.
Manifest
At 11:00 pm the coordinator writes the manifest: three subagents, each one's status and state file, and the phase 1 summary. test-finder and cod-flow-tracer start and write their findings as they work, and at 1:30 am test-finder is done.
At 2:10 am the run crashes. Every running agent stops and its context window is emptied, the coordinator's included. The manifest and the state files stay on disk.
Suppose there were no manifest. No file would record which subagents finished or where their findings are, so in the morning all three would start again from their original prompts, and test-finder's two and a half hours of work would be done again.
With the manifest, the coordinator reads it first. test-finder is done, so it is not started again. cod-flow-tracer was in progress, so it starts again with its saved findings and the manifest's phase 1 summary in its prompt.
When cod-flow-tracer is done, rto-flow-tracer, which had not started, starts with the phase 1 summary in its prompt. Both are done by 10:15 am.
The crash emptied every context window and removed no file. Because the manifest and the state files were on disk, the run repeated no finished work.
Crash recovery: state files and a manifest
11:00 pm: test-finder and cod-flow-tracer start, and two state files appear in .explore/. rto-flow-tracer waits for cod-flow-tracer to finish.
1:30 am: test-finder finishes, and its status in manifest.json changes to done.
At 2:10 am the run crashes with cod-flow-tracer halfway through, and every running agent's context window is emptied. The files in .explore/ are still on disk.
8:30 am: an engineer finds the run stopped and starts the program again. The new coordinator reads manifest.json and skips test-finder; without the manifest, test-finder would run again until 11:00 am.
Read cod-flow-tracer.json: the new prompt holds the manifest's phase 1 summary and three saved findings, and cod-flow-tracer continues from its last saved finding.
When cod-flow-tracer is done, rto-flow-tracer starts with the phase 1 summary in its prompt, and all three agents have finished by 10:15 am.
The crash removed the context windows and left the files, so recovery depended only on what the agents and the coordinator had written to disk as they worked.
Without the manifest, the run would have started again from nothing and repeated two and a half hours of finished work.
Claude Code's option works differently. It reloads one saved conversation
with its whole history, including everything that made it long and degraded. Chapter 16 covers sessions and --resume. The manifest restores each agent's status and the path of its saved findings, and the coordinator puts those findings into a fresh conversation. Each agent also has a state file of its own, because several agents writing to one shared notes file can overwrite each other's lines.
Part 5: Check yourself
Pick the jobs that need Grep.
The engineer has seven jobs for Claude in routing_engine. Select every job where Grep is the right tool, then check.
Select at least one item first.
Exam question: keep late answers specific.
Your team uses Claude Code to explore Delhivery's routing codebase of about 1,800 files. Two hours into a session, the agent's answers start to say “typically, the allocation layer would check weight slabs here” instead of naming WeightSlabValidator in allocation/slabs.py, which it found in the first hour. Two of its answers about assign_centre now disagree. What change most effectively fixes this for the rest of the exploration?
Delhivery appears in this chapter only to explain how Claude Code and Claude work. Delhivery has no connection with these tutorials, and the code, systems, numbers and events in this chapter were written for the lesson. They do not describe how Delhivery works, and Delhivery does not use this code.