Product case study · October 30, 2026

Review Two Folders with Claude Code --add-dir

Use Claude Code --add-dir to compare a client with a sibling API contract, verify a planted mismatch, and check that the source files stayed unchanged.

Reading time
6 min
Checked
Oct 30, 2026
Two paper folders joined by a narrow bridge, with a magnifying lens comparing blue and ochre evidence shapes
Bring two sides of a contract into one review without moving their files.
Bottom line

Add only the sibling folder a review needs, then verify the finding against both files before authorizing a fix.

A client can look correct on its own and still read a field the API never returns. This exercise puts the client and contract in separate folders, adds the contract folder to a Claude Code session, and asks for a review with file evidence. You will finish with a finding you can check by hand and a record of whether the source files changed.

Sources checked October 30, 2026. We checked official documentation and the installed Claude Code 2.1.304 help, and ran the fixture setup and hash checks locally. We did not run an authenticated Claude review. The expected findings below are an authored answer key, not a reported model result.

You need Bash, Python 3, and an installed, authenticated Claude Code CLI. The first project-session lesson covers getting started. Use the fictional files below rather than private repositories for your first attempt.

Prepare two sides of a broken contract

Run this in Bash. Keep the terminal open so lab_root remains available:

lab_root=$(mktemp -d /tmp/claude-contract-lab.XXXXXX)
mkdir -p "$lab_root/client" "$lab_root/api" "$lab_root/evidence"
cat > "$lab_root/client/display.js" <<'JS'
export function displayName(profile) {
  return profile.name.toUpperCase();
}
JS
cat > "$lab_root/api/profile-contract.json" <<'JSON'
{
  "endpoint": "/profile",
  "required": ["display_name"],
  "example": {"display_name": "River"}
}
JSON
cat > "$lab_root/evidence/snapshot.py" <<'PY'
import hashlib
import json
from pathlib import Path

root = Path(__file__).resolve().parent.parent
paths = ["client/display.js", "api/profile-contract.json"]
print(json.dumps({
    path: hashlib.sha256((root / path).read_bytes()).hexdigest()
    for path in paths
}, indent=2, sort_keys=True))
PY
python3 "$lab_root/evidence/snapshot.py" > "$lab_root/evidence/before.json"
claude --version > "$lab_root/evidence/cli-version.txt"
cd "$lab_root/client"
printf 'Lab folder: %s\n' "$lab_root"

The JSON is a small human-readable fixture, not a complete OpenAPI schema. It says the example response contains display_name. The client reads name. No server, dependencies or installation step is needed to inspect that discrepancy.

The two folders stand in for separate repositories. They deliberately have no Git history or project configuration, so the exercise stays focused on the review. Keep the evidence folder alongside them for your own notes.

Start with the specific sibling directory

From the client directory, launch:

claude --permission-mode plan --add-dir ../api

The CLI reference documents --add-dir as accepting existing directories for additional file access. Here ../api resolves relative to the directory where you start Claude. It does not copy files or merge repositories. Check the startup directory and the displayed permission mode before sending a task.

Additional directories follow the session’s file permission rules; the flag itself does not make them read-only. Plan mode is the review setting for this exercise. Keep the session in that mode and decline a request to proceed with implementation. Do not add your entire home directory to resolve a missing path. See Anthropic’s permissions and working-directory guidance.

Paste this request:

Review display.js against ../api/profile-contract.json.
Read both files and report the exact paths you inspected.
Identify any field-name mismatch and cite the relevant line numbers.
Explain what the supplied example implies for displayName.
Propose the smallest correction and one test, but do not implement or run it.
Return the review in chat. Do not edit files, install packages, access the
network, or switch out of plan mode. If either file is unavailable, report
that limitation instead of inferring its contents.

Watch the file reads. A response that names both paths without reading both is incomplete evidence. Save the final answer manually to evidence/review.txt after exiting the session; use the full lab path printed earlier. Do not ask the agent to write this evidence file as part of the read-only review.

Grade the finding before accepting a fix

Use this answer key to evaluate the saved response:

CheckEvidence the response should contain
Client fieldclient/display.js, line 2, reads profile.name.
Contract fieldapi/profile-contract.json, lines 3–4, requires and demonstrates display_name.
ConsequenceFor the supplied example, profile.name is undefined, so calling its toUpperCase() would throw.
Minimal proposalRead profile.display_name if the supplied contract is authoritative.
Proposed testPass the example object and expect RIVER after the correction.
Evidence limitNo runtime test or real endpoint request has been performed in this review.

A proposal to rename the API field needs a compatibility discussion; this fixture provides no evidence that API consumers can tolerate that change. A proposal to silently return an empty string may hide the discrepancy. Ask the reviewer to justify either choice rather than treating every plausible patch as equivalent.

For a real pair of repositories, add a question this fixture cannot answer: which contract version is deployed? A file in a sibling checkout can be outdated. Record revisions and supply actual test output before drawing a release conclusion.

Verify the source files stayed unchanged

After closing Claude, return to the same shell and run:

python3 "$lab_root/evidence/snapshot.py" > "$lab_root/evidence/after.json"
cmp "$lab_root/evidence/before.json" "$lab_root/evidence/after.json"
find "$lab_root/client" "$lab_root/api" -type f -print

cmp should exit zero with no output when the two source files have identical bytes. The file listing lets you inspect additions too: expect display.js and profile-contract.json, and investigate anything else. These checks cover the practice folders, not every action on the machine.

Record the CLI version, launch command, inspected paths, answer-key misses, and hash result alongside the review. If a source changed, keep the evidence and inspect the difference. Create a fresh lab by rerunning the setup block rather than deleting or resetting an unrelated project.

Understand which instructions travel with access

File access and automatic instruction loading are separate controls. Anthropic’s memory guide says additional-directory CLAUDE.md files do not load by default. To opt in for a reviewed sibling project, its documented Bash form is:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 \
  claude --permission-mode plan --add-dir ../api

This is optional for a later exercise; the fixture has no CLAUDE.md. Inspect a real sibling’s instructions before enabling them. Instruction text guides the model and does not enforce correctness.

Do not assume adding a directory activates all its configuration. The permissions reference documents exceptions, including skills, commands and subagents from flag-added folders. That is another reason to inspect a real directory before granting access.

Recover from an incomplete review

SymptomNext action
Added directory does not existExit and check pwd and ls ../api; start again from the lab’s client folder.
One file was not readKeep the review marked incomplete. Inspect the tool error and active permissions before retrying.
Agent proposes a patch immediatelyKeep the session in plan mode and ask for the two cited field names first.
Sibling instructions seem absentCheck whether you intentionally enabled additional-directory memory loading.
Review claims a passing testAsk for the command and captured output; this exercise requests a proposal only.
Source hashes differInspect the changed file before doing more work; do not treat the review as unchanged-source evidence.

Finish by exiting the practice session. For a later unrelated job, start a fresh session in its intended directory without the added path; do not resume this lab by accident. Keep the disposable folder until you have reviewed your evidence.

Official source notes

Checked October 30, 2026:

Put this to work

Distinguish additional file access from instruction loading and edit permissions.

Try

Review a fictional client and API contract in two disposable folders.

Prove it worked

Match the response to the answer key and verify both source hashes remain unchanged.

Keep in view

  • Give one session access to a specific sibling directory.
  • Find a deliberately mismatched field using evidence from both files.
  • Check source hashes before approving any implementation.
Learn the workflow: Set up your first Claude Code project session