🌐 한국어로 읽기

Appendix — How this book was made

This book was written by an AI (Anthropic's Claude) at the direction of a human who wanted to learn from MicroHs's history — and who, reasonably, did not want to trust an AI's unchecked account of someone else's work. This appendix describes the production process, because the process is itself a reusable technique: point it at any repository with a rich history and it produces a verified teaching book. The design spec and implementation plan for this instance are preserved in this repository's docs/superpowers/ directory.

The shape of the process

1. Scope from milestones. Survey git log --reverse and find the natural arc: here, "First version" (two files, one evening) → "Make a real compiler" → self-hosting → "Now bootstraps with type checking." Chapters are thematic phases of that arc — not one commit per chapter, and not one subsystem per chapter, because chronology is where the working style lives, and the style was the point.

2. Spec, then plan, then fresh eyes per chapter. A short design spec fixed the reader (Haskell-literate, compiler-newcomer), the chapter map, and the rules. A plan turned that into fourteen tasks. Each chapter was then written by a fresh AI agent that saw only its own brief: the commit range, the commits requiring depth, the global constraints verbatim, and the facts established by earlier chapters. Fresh eyes cannot lean on context they do not have — everything they claim, they must pull from the history itself.

3. Adversarial review, every chapter. A different agent reviewed each chapter against its brief, explicitly instructed to treat the writer's report as unverified claims, and given a short list of named risks to check by re-deriving them from the diffs — never by re-reading the writer's account. Findings needed file:line evidence. The writer fixed; the reviewer re-reviewed the fix. Ten of fourteen tasks needed at least one fix round.

4. A final whole-book review (on the strongest available model) checked what per-chapter gates cannot: continuity between chapters, the uhs→mhs naming timeline, the hard boundary (nothing narrated past a38c64ce), and fresh fact samples across chapters.

The rules that mattered

Most quality machinery is obvious in hindsight — quote code byte-for-byte, run what you claim. The rules below are the ones that were learned, each from a review actually catching a failure in this book's drafts:

• Quotes are byte-exact, or they are marked. An early draft of the overview quoted git show --stat output with the columns re-padded after dropping two rows. Byte-comparison caught it. The rule became: quote the real bytes, mark every elision with an explicit ..., cite commit:file with the path as it exists at that commit (a later chapter cited eval.c at a commit where the file had already moved to src/runtime/eval.c — the citation didn't resolve).

• Never state an unverified mechanism as fact. One draft asserted which operand C evaluates first in x + y. C doesn't say, and no transcript showed it; the passage was rewritten to hold in either order. Another draft described a bug fix with a plausible mechanism — right commit, wrong file, wrong kind of bug — that only fell apart when the reviewer re-derived it from the diff. Plausible-and-wrong survives checklists; it does not survive re-derivation.

• The printed text is the test artifact. Every "Try it" block was executed before publication — and that was not enough. One chapter's exercises each worked individually, but the printed sequence omitted a rebuild between them, so a reader following the text in order would diff a stale artifact. Another placed a worktree cleanup block before the exercises that still needed the worktree. The fix: a reviewer paper-walks the exercises exactly as printed, as a naive reader.

• Commit titles under-describe; audit the diffs. A commit titled as a pure file move quietly introduced an entire new module (an early experiment in native evaluation) — with an unterminated string literal, no less. The narrative initially repeated the title's story. The rule: for every narrated commit, read the whole diff and disclose what the title doesn't say. The book's own chapters now practice this on Augustsson's history, and the reviews practiced it on the book.

• Say what doesn't reproduce. A documented 2023 stack-overflow crash refused to fire under a modern system's default limits. The chapter says so, and shows what was observed instead. A book about honest engineering cannot smooth over its own environment's differences.

• Verify the negative claims too. Chapter 08 checks whether the profiling flag feeds the combinator frequency ordering — the diffs show no connection, and the chapter says exactly that, having looked.

Numbers, for calibration

Roughly: 28 commits of book production; 10 of 14 tasks required a fix round; review findings ranged from byte-level (a re-padded stat column) to structural (a missing rebuild step that invalidated an exercise's premise). Every fix was itself re-reviewed. The final whole-book review found eight further issues — commands that assumed a convention two aux docs had drifted from, one range mischaracterization — and its fix was reviewed again. None of this guarantees correctness; it does mean every claim you can check has already survived one adversary checking it.

Reusing the process

The condensed, executable form of this process — the chapter-brief and reviewer-dispatch templates, and the failure-derived rules above — ships with this book as an agent skill file: skills/writing-teaching-books-from-git-history/. It is plain markdown; that directory's README explains what a skill file is and how to install it, and nothing in the method is AI-specific. The spec and plan in docs/superpowers/ show the concrete instance that produced this book.

To apply it elsewhere: find a repository whose history you want to learn from, fix an endpoint, and hold every chapter to the same bargain this book makes with you — everything quoted is real, everything claimed was run, and everything else is labeled.