Can a long reading list on system design become a small site you can click through, built mostly by agents and checked by a script?

Hypothesis

The System Design Primer is one very long page. People learn faster when each topic is its own page, with links between topics and solutions. If a Wayfinder map holds the plan, an agent can write the site and a second agent can check it. A build script that fails on a broken link keeps the links true.

What we built

• A linked site. The primer is now a site with 24 topics, 14 solutions and 9 interactive diagrams. Topics link to the solutions that use them, and the other way round.
• One build script. It builds every page. It also runs a link check. If one link is broken, the build fails, so a broken link never goes live.
• The workflow. Wayfinder map #2 held the plan. Codex wrote the code. Claude read the result, ran the checks and sent fixes back.
• Live on GitHub Pages. The code is public, and the primer itself comes from donnemartin/system-design-primer.

Learnings

• A link check that fails the build is worth it. With 24 topics and 14 solutions, links break fast. A script catches them in seconds. A person does not.
• Headless Chrome cannot go below about 500px wide. Screenshots at phone width came out wider than asked. To test mobile, put the page in a 380px iframe and shoot that.
• One Codex run hung without a sound. It gave no error and no output. The sign was output that stopped growing. Watch the size of the log, and stop and restart a run that is stuck.
• Let one agent write and another check. Claude found problems that the writer did not see.

Log

• 2026-10-28: Entry written.
• 2026-10-27: Site live with 24 topics, 14 solutions and 9 diagrams.