Build a dry-run Markdown link checker with Claude Code

When a team has a folder of Markdown guides, a typo in one internal link can sit unnoticed until someone clicks it. A tiny checker can catch obvious misses, but it should start as a report, not an automatic cleanup job.

Advanced builder lesson. Evidence label: documentation-based guide with fictional inputs and illustrative output. This workflow was not executed here. The sample repository and expected report are illustrative.

What you will create

You will ask Claude Code to create a local Python script that scans Markdown files, checks relative links to files in the same sample repository, and prints a report. It must not edit files, follow external URLs, or read outside the project directory.

You need Claude Code on a terminal or another supported surface, a disposable folder, and Python 3. The official Claude Code documentation says the tool can read codebases, edit files, run commands, and work across terminal, IDE, desktop, and web surfaces. Keep this exercise away from a production repository.

1. Make the fictional repository

Create this folder structure:

link-check-demo/
  README.md
  guides/
    onboarding.md
    weekly-review.md
  scripts/

Put these contents in the files:

README.md

# Link check demo

Start with the [onboarding guide](guides/onboarding.md).
Read the [weekly review](guides/weekly-review.md).

guides/onboarding.md

# Onboarding

Return to the [project home](../README.md).
See the [weekly review](weekly-review.md).

guides/weekly-review.md

# Weekly review

Return to the [project home](../README.md).
See the [missing checklist](checklist.md).

The last link is deliberately broken. The checker should report it and leave every file unchanged.

2. Ask for a plan before edits

From the link-check-demo directory, start Claude Code and paste:

We are working in a disposable Markdown link-check demo.

First inspect the repository and propose a plan. Do not edit files or run commands yet.

Goal: create a local Python script under scripts/ that scans Markdown files under this repository, checks relative links to local files, and prints a report of missing targets.

Boundaries:
- Read only this repository.
- Do not follow http or https links.
- Do not edit Markdown files.
- Do not rename, delete, install, or modify dependencies.
- Do not report an illustrative result as an executed result.
- Use standard-library Python only.

Acceptance checks:
- the script finds the broken link in guides/weekly-review.md
- valid relative links are not reported as missing
- the script exits with a nonzero status when a missing target exists
- the script exits with zero status after the missing link is fixed
- add a small test or fixture that checks both outcomes
- show the proposed files and commands before making changes

Review the plan. Stop if it proposes network access, dependency installation, destructive commands, or edits outside scripts/ and a test fixture.

3. Generate the checker in a bounded pass

After reviewing the plan, ask Claude Code:

Implement only the approved plan.

Use pathlib and Python's standard library. Resolve each relative Markdown link against the file that contains it. Ignore URL links, fragment-only links, mailto links, code blocks, and image destinations. Do not follow symlinks outside the repository.

The report must include the source file, the original link target, and the resolved path for each missing local target. Use a dry-run default: never rewrite a file. Add a command-line option for the repository root and return exit code 1 when any target is missing.

Add tests or a fixture for one valid link and one missing link. Show the diff after writing files. Do not run commands outside this repository.

The exact implementation is Claude Code output and must be reviewed. Do not describe it as tested until you run the commands yourself.

4. Review and run the acceptance checks

Ask Claude Code to show the changed files and explain how each acceptance check is covered. Then run the proposed test command yourself from the repository root. Inspect the report. Fix the fictional broken link manually, run the checker again, and confirm that the exit status changes to zero.

The checkable artifact is a report shaped like this:

MISSING guides/weekly-review.md:5 -> checklist.md (guides/checklist.md)

This is an editor-defined expected shape, not captured output from a Claude Code run.

No-code alternative

If a script feels like too much setup, open the repository in an editor and use its Markdown link validation extension, or search for ](guides/ and inspect each target manually. That is slower, but it keeps the process within the tools your team already understands. You still need to confirm the links and avoid automatic rewrites until someone reviews the changes.

Troubleshooting

The checker reports links inside code examples: add a parser rule that skips fenced code blocks, then create a fixture proving the skip.
A valid link is reported as missing: print the source file, raw target, and resolved path. Check whether the link uses a fragment or a path relative to a different file.
Claude Code follows external links: treat that as a boundary failure. Keep URL destinations out of the local-file check.
Claude Code edits the guides: stop and inspect the diff. Restore the sample files, then repeat with the no-edit rule and a narrower allowed path.
The test passes without finding the broken link: make the test assert the expected path and nonzero exit status, not only that the process ran.

Limits and safe use

A local checker can find missing relative file targets. It cannot prove that an external website is live, that a page says what the link text claims, or that a generated document is factually correct. Review the diff before using the script on a real repository. Do not give an agent permission to rewrite links or run network requests as part of this first exercise.

The Claude Code common workflows documentation recommends planning before editing and shows recipes for testing and reviewing changes. The overview describes the supported surfaces and command access.

Try this only in a disposable repository first. Skip automatic fixes. Use the checker in a real project only after its fixtures, scope, and output pass human review.

Want one useful workflow each week? Join The Weekly Verdict.

Sources

Evidence label: Documentation-based advanced builder guide with fictional input and an illustrative report. No Claude Code execution or personal test is claimed.