AnthropicClaude Certified Architect – Foundations2026-102.5 Select and apply built-in tools (Read, Write, Edit, Bash, Grep, Glob) effectively
Match file operations to their effects
Completed by the knowledge check
Learning objective
Select Read, Write, Edit, or Bash by operation and side effects, preferring dedicated file tools where applicable.
Core idea
A code generation agent should choose the operation that expresses the intended change directly. Inspect a file with Read, create or replace complete content with Write, and change a specific exact passage with Edit. Use Bash when the job is executing a command, such as running the project’s tests or inspecting a Git diff.
The deciding property is the operation’s effect, not which tool can be persuaded to do it. A shell script can rewrite a source file, but a targeted Edit makes the old and replacement text explicit. A Write can change one line, but it also replaces every other line. The choice determines how much existing content you must preserve and what evidence you need before acting.
How it works
Read the content you need
Read accepts an absolute file_path and returns file contents with line numbers. The documented text inputs include offset, the starting line, and limit, the number of lines. These let you inspect the relevant section without loading unrelated content. It reads files rather than directories; directory listing belongs to a shell command such as ls through Bash.
Do not equate one Read call with a complete file. The default per-call output limit is 25,000 tokens, configurable through CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, and an ordinary whole-file read refuses a file over 256 KB. A file exceeding the token limit can return a first page with a PARTIAL view notice. Follow that notice and use offset and limit to obtain the remaining content when the operation requires the whole file.
Claude Code v2.1.296 or later supports allow_large: true for a whole text file or long line range when needed. That read is sized against remaining context capacity instead of the default limits. It is not a reason to read an entire repository: the question still determines which file or range matters. See 2.5.4 for incremental exploration.
Choose targeted or complete mutation
Edit takes file_path, old_string, new_string, and optionally replace_all. It performs exact string replacement, without regex or fuzzy matching. For one intended occurrence, the anchor must match exactly and uniquely. A small change to an existing function therefore fits Edit when the observed text identifies the intended location. Recovery from an ambiguous anchor belongs to 2.5.3.
Write takes file_path and content. It creates a file or overwrites the existing file with all supplied content; it does not append or merge. Use it for a new file or a deliberate complete replacement. Before overwriting, you must be able to account for every section that should survive. Leaving an import, comment, or neighboring function out of content removes it rather than preserving it implicitly.
Reading before mutation is good evidence gathering, but the runtime’s enforced read prerequisite is not identical for every model and file. The tools reference documents relaxed handling of unread files under defined conditions. A partial read does not establish the complete content needed for a safe replacement. Prefer observed source over a reconstructed version even when the runtime permits an unread write.
Execute commands with Bash
Bash executes a shell command. Running the repository’s test command and inspecting git diff are command operations; Read cannot execute a test runner, and Edit cannot report Git’s comparison of working-tree changes.
Each command runs in a separate process. Environment variables exported in one command do not persist into the next. In the main session, a cd inside the project or an additional working directory can carry over, while subagent sessions do not carry over directory changes. For a command whose target depends on location, make that location explicit rather than assuming all shell state persists together.
A command can have effects beyond its visible output. A test command might write snapshots or generated artifacts, and a deployment command might contact an external system. Those are properties of the command you choose, not guarantees provided by the Bash name. Inspect the repository’s command definition before using its result as evidence that only a check ran.
For an ordinary partial source change, choose Edit rather than constructing shell redirection or a text-replacement script. For a complete file creation, choose Write. Bash remains appropriate when the required operation genuinely depends on an executable, including an encoding-preserving transformation that the text tools cannot perform safely.
File-path permissions use Edit(path) and Read(path) rules: Edit rules cover built-in file-editing tools, and a Read deny rule also blocks Edit and Write on that path from Claude Code v2.1.208 and v2.1.228 respectively. In Bash, these deny rules cover recognized file commands such as cat, head, tail, sed, and tee, and redirection targets, but not arbitrary subprocesses such as Python or Node scripts that open files indirectly. A Python or Node rewrite therefore does not inherit the dedicated tool’s path-policy coverage; choosing Edit keeps a targeted change subject to that check.
Key distinctions and trade-offs
The practical dividing lines are:
| Required operation | Tool | Preservation or side-effect question |
|---|---|---|
| Inspect a file or line range | Read | Is this a full view or a partial one? |
| Change an exact passage | Edit | Does the anchor identify the intended occurrence? |
| Create or replace complete content | Write | Is every required part present in content? |
| Execute a program or shell command | Bash | What does the selected command modify or contact? |
Read-only effect versus permission: Read does not modify the file, but file-access tools can still prompt for paths outside working directories. The tools reference’s permission table describes Manual mode for paths inside the working directory; it is not a universal authorization rule. See 0.6 for tool availability and approval.
Text replacement versus encoding preservation: Edit refuses invalid UTF-8 files except for its documented little-endian UTF-16 byte-order-mark case. Write saves replacement content as UTF-8, losing the original encoding. A shell transformation that preserves encoding can be the appropriate operation when maintaining that encoding is part of the requirement.
Architecture / decision scenario
A Claude Code agent must add refund logging, create a test fixture, and verify the patch. It uses Read on the implementation and relevant imports. If the file returns a PARTIAL view, it reads the required ranges before deciding what the change touches.
For one logging statement, the agent selects Edit with an exact unique old_string and a new_string containing the additional field. For the new fixture, it selects Write with the fixture’s complete content. It does not rewrite the implementation to add one field or use shell redirection merely to create the fixture.
The agent then uses Bash for the project’s documented test command and git diff. It checks whether the test command updates snapshots and examines the resulting patch for unrelated changes. If a legacy fixture has an encoding the text tools cannot preserve, it investigates an encoding-preserving command instead of treating a UTF-8 overwrite as harmless. Each selection follows the required effect and produces evidence appropriate to that effect.
Common exam traps
- Using
Writefor a small change while assuming omitted content survives. - Using
Readto list a directory or execute tests. - Treating
Edit.old_stringas a regex pattern. - Assuming every
Readresponse contains the entire file. - Assuming every shell environment change persists between commands.
- Calling a command read-only because its name sounds like a check.
Where the exam guide differs
The exam guide summarizes Read/Write as “full file operations.” Write supplies complete replacement content, but Read also supports line ranges and can return a partial view. Use the guide’s wording to distinguish whole-file replacement from targeted Edit, not to infer that every read is complete.
The product also qualifies read-before-mutation enforcement. Claude Code v2.1.208 or later permits unread edits under documented conditions, and v2.1.228 or later permits analogous unread overwrites for eligible models. Reading must not need a permission prompt, and Read must be available. The tools reference names models that still require prior reads; notebooks and files with a PARTIAL view require a read before overwrite on every model. In an exam recovery item, Read followed by Write remains the whole-file fallback, not an unconditional runtime rule for every mutation.
What to remember
Choose Read for inspection, Edit for exact targeted replacement, Write for complete content, and Bash for command execution. The required effect determines the tool. Full-file replacement requires complete evidence and preservation; successful command execution requires checking what the command actually did.
Knowledge check
A Claude Code agent must add a reasonCode field to one logging statement in a 600-line module. The statement occurs once in the file. The reviewer wants every other line left as it is and the old and new text stated explicitly in the tool call. Which operation fits?
Write with the module’s full content, including the extended statementEdit with the exact statement as old_string and the extended one as new_stringBash running sed -i with a regular expression that matches the statementEdit with a regular expression as old_string that tolerates any spacing differencesEdit performs an exact, unique string replacement, so the call itself names the old and new text and touches nothing else. Write replaces the whole file and makes the agent responsible for reproducing all 600 lines. Edit does not interpret regular expressions, and a sed substitution expresses the change as a pattern rather than the observed text.An agent plans to replace a large generated file with a reformatted version using Write. Its Read of the file returned the first page with a PARTIAL view notice. What should it do before calling Write?
Read call again, expecting the full file on the second tryGrep in content mode to collect the lines it has not seen yetoffset and limit until it holds the whole fileWrite replaces the entire file with the supplied content , so anything missing from it is deleted. A PARTIAL view means the read stopped at the per-call limit; the notice says how to fetch the rest with offset and limit . Repeating the call returns the same page, and Grep returns matching lines, not a complete copy of the file.An agent runs export DATABASE_URL=postgres://localhost/test_db in one Bash call and npm test in the next. The tests connect to the default database instead. What should it change?
Bash callexport call immediately before the call that runs the testscd into the project directory in the call before the exportRead on the project’s .env file before the call that runs the testsBash command runs in a separate process, so a variable exported in one call is gone in the next, however often it is repeated. A cd within the project can carry over in the main session, but that does not make environment variables persist. Reading a file puts it in context; it does not set anything in the shell that runs the tests.A team keeps Claude Code away from production configuration with a deny rule Edit(./config/prod/**). A reviewer asks which agent operation could still modify a file under that path. Which one?
Edit call that changes one key in config/prod/app.yaml in placeWrite call that replaces config/prod/app.yaml with new contentBash call running a Node script that rewrites config/prod/app.yamlBash call running sed -i to rewrite config/prod/app.yamlEdit rules cover every built-in file-editing tool, and Claude Code applies them to file commands it recognises in Bash , such as sed and tee , and to redirection targets. A script that opens files itself is an arbitrary subprocess the rule cannot see. That is one reason to make a targeted change with Edit : it stays under the path policy.References
- Anthropic, Tools reference
- Anthropic, Agent SDK Python reference
- Anthropic, Configure permissions
- Anthropic, Claude Certified Architect – Foundations Exam Guide