Product case study · November 13, 2026

Repair a Broken Markdown Link with Claude Code

Give Claude Code a small documentation repair, verify paths relative to the source file, and reject fixes that delete the link or invent a destination.

Reading time
6 min
Checked
Nov 13, 2026
A charcoal paper chain joins two document cards while an ochre magnifying lens examines the connection
Repair the path, then prove it reaches the intended document.
Bottom line

A link repair is complete when the intended destination exists and the diff preserves the reader's route to it. A green file check alone cannot prove intent.

A documentation file moves into a subfolder. Its incoming link still looks reasonable, but readers now land on a missing page. This is a useful first repair for a coding agent: the change is small, and you can verify it without trusting the agent’s summary.

The trap is asking only for “no broken links.” Deleting the link would satisfy that request. Creating an empty file at the old path could satisfy a file-existence check. Neither helps the reader reach the guide that already exists.

This lab gives Claude Code one broken link and a precise acceptance check. You need Bash and Python 3; the agent step also needs an installed, authenticated Claude Code. Sources checked November 13, 2026. The fixture and checker were tested locally. The Claude conversation below is an authored exercise, not a reported authenticated agent run.

Make a small documentation folder

Run these commands in one Bash terminal. Keep the printed folder path if you need to return later. The lab uses a fresh temporary directory and no network requests.

link_lab=$(mktemp -d /tmp/markdown-link-lab.XXXXXX)
cd "$link_lab"
mkdir -p docs/guides
cat > docs/index.md <<'MD'
# Project help

Read the [setup guide](setup.md) before your first run.
MD
cat > docs/guides/setup.md <<'MD'
# Setup guide

Create a practice folder, then put your project brief inside it.
MD
cp docs/index.md index.before.md
printf 'Practice folder: %s\n' "$link_lab"

The source is docs/index.md. The real guide is docs/guides/setup.md. GitHub’s relative-link documentation explains that the target is relative to the current file. Here, setup.md points to docs/setup.md, which does not exist. The correct relative target is guides/setup.md.

This is a repository Markdown exercise. A static-site framework may transform source paths into different public routes; its rendered-link checks would be a separate requirement.

Establish the failure before asking for edits

Save this narrow checker in the practice folder:

cat > check_link.py <<'PY'
from pathlib import Path
import re
import sys

source = Path("docs/index.md")
text = source.read_text(encoding="utf-8")
links = re.findall(r"\[setup guide\]\(([^\s()]+)\)", text)
if len(links) != 1:
    print("FAIL: expected exactly one setup guide link")
    sys.exit(1)

target = links[0]
expected = Path("docs/guides/setup.md").resolve()
resolved = (source.parent / target).resolve()
if target != "guides/setup.md" or resolved != expected or not resolved.is_file():
    print(f"FAIL: {source} -> {target}; expected guides/setup.md and an existing file")
    sys.exit(1)

print("PASS: docs/index.md -> guides/setup.md reaches the existing guide")
PY
python3 check_link.py
printf 'Checker exit: %s\n' "$?"

Expect FAIL and exit 1. Do not run this deliberate failure under a shell setting that stops the whole exercise on any nonzero exit.

Python’s pathlib reference documents joining paths, resolving them and checking for regular files. The checker combines those operations with a requirement specific to this fixture: there must still be exactly one setup-guide link, using the intended relative path.

This regular expression is deliberately not a general Markdown parser. It only recognizes this lab’s simple inline link. Reference links, escaped brackets, titles, spaces, code fences, images, URL encoding and heading fragments need parser-aware handling in a real audit. Do not reuse it as a site-wide link validator.

Give Claude a repair contract

Start claude from the practice folder; Anthropic documents this interactive command in its CLI reference. Paste:

Repair the setup-guide link in docs/index.md.
First read docs/index.md, docs/guides/setup.md and check_link.py.
Explain how the existing target resolves relative to the source file.
Then change only the link destination in docs/index.md so it points
at the existing setup guide. Preserve the label and surrounding prose.
Do not create, move, delete or rewrite any other file.
Do not change the checker or use an absolute filesystem path.
Run python3 check_link.py and report its actual output and exit status.
If the intended destination is ambiguous, stop and explain the ambiguity.

Review tool requests before approving them. These instructions define the task; they do not create a filesystem sandbox. Anthropic’s common workflows provides patterns for investigating bugs and checking fixes. Here the investigation has a concrete question: which existing file contains the instructions the label promises?

An acceptable patch changes (setup.md) to (guides/setup.md) and leaves everything else alone. If Claude suggests creating docs/setup.md, point it back to the existing guide. If you are practicing without an authenticated session, make that one replacement yourself; that demonstrates the local check, not Claude’s performance.

Verify the repair yourself

Exit Claude and run:

python3 check_link.py
printf 'Checker exit: %s\n' "$?"
diff -u index.before.md docs/index.md
cat docs/guides/setup.md

Expect the checker to print PASS and exit 0. The diff should contain only the changed link destination. diff normally exits 1 when it finds differences, so that status is expected here.

Read the destination too. A file can exist while containing the wrong instructions. In this fixture, the guide should still tell the reader to create a practice folder and add a project brief. Confirm the checker itself was not edited; a passing result from a weakened check is not the same evidence.

Recover when a fix looks right but fails

ObservationNext step
The agent uses docs/guides/setup.md as the linkResolve it from docs/; that mistakenly adds another docs/ level.
The link disappearsRestore the original sentence from index.before.md, then change only its target.
A new empty docs/setup.md appearsInspect that unexpected file and reject this repair; the existing guide is the target.
The check passes but the guide text changedReview the extra edit; file existence cannot verify preserved content.
Python cannot find docs/index.mdReturn to the printed practice directory before running the checker.

For a real repository, start with one reported link and inspect the diff before widening the task. When several destinations seem plausible, ask the agent to list them with supporting content instead of choosing by filename alone. The useful handoff is small: the source file, the intended reader destination, the patch and the check you can rerun.

Sources

Checked November 13, 2026:

Put this to work

Separate a valid filesystem path from a useful documentation link.

Try

Ask Claude Code to repair one inline Markdown link without creating a replacement document.

Prove it worked

Keep a failing check, a passing check and the one-line repair diff.

Keep in view

  • Reproduce a broken link in a disposable documentation folder.
  • Resolve the target from the linking file's directory.
  • Check both file existence and the meaning of the destination.
Learn the workflow: Set up your first Claude Code project session