aosp-internal-book: Instructions file for Claude Code

AOSP Internals Book

67 chapters + 4 appendices, ~1,500 Mermaid diagrams.

Quick Start

docker compose build
docker compose up -d serve         # http://localhost:8000

Writing Rules

1. Chapters: NN-slug.md, titles: # Chapter N: Title — colon only, never -- or —
2. Section numbers: manual ## N.1, ### N.1.2 matching filename
3. No duplicate section numbers within a chapter (watch for this when inserting new sections)
4. Mermaid: quote labels with (), <br/>, |; no <br/> in participant lines; no parens in stateDiagram-v2 transition labels (State1 --> State2 : foo() breaks parsing — drop the parens)
5. Descriptive heading before each mermaid block
6. Source refs: real AOSP paths with line numbers
7. The body of every chapter ends with "Try It" then "Summary" — nothing else comes after Summary, except an optional final "Key Source Files Reference" (or similarly-titled key-file-paths) table, which may sit after Summary as a final reference. Appendices, extras, deep dives, etc. still must move above Try It / fold into a numbered section.
8. Do not add epigraph blockquotes at the top of chapters. No > *"quote"* / > -- Author blocks between the # Chapter N: Title line and the first ## N.1 section. The chapter goes straight into its introductory paragraph after the title. (We removed all of these in a cleanup pass; do not re-introduce them when editing or writing new chapters.)
9. Verify mermaid format parses after every edit. Run ./serve.sh png NN-slug.md on every chapter whose Mermaid blocks you touched and confirm the output reports errors=0. The CI properdocs build does NOT validate Mermaid (the live site renders it client-side in the browser), so a parse error reaches readers as a "No diagram type detected" / "Syntax error" banner with no build-time signal. Treat errors=0 as a hard precondition — do not declare the edit done, commit, or move to visual review until the format check is clean. If errors>0, fix the offending block (the script names which file/index failed) and re-run until clean.
10. Visually verify mermaid diagrams after writing or editing them. Parse-clean is not enough — diagrams can render with text overflowing rectangles, overlapping nodes, or unreadable arrows, and they can also be parse-clean but factually wrong about the architecture. After rule 9 passes, inspect each PNG under .mermaid-png/<slug>/. Check: (a) every label fits inside its shape with no overflow; (b) no nodes or edge labels overlap; (c) the boxes, arrows, and grouping match the architecture the prose describes (right components, right direction of arrows, no missing or invented relationships). Re-render after every mermaid edit.
11. Keep llms.txt in sync with chapter content. llms.txt (root of repo, symlinked into docs/) is the llmstxt.org-style index that AI tools fetch to learn what's in this book and where to find each subsystem. Update it when chapters are added, removed, renamed, or significantly retitled, and when a chapter's scope changes enough that its one-line description no longer fits. Each chapter entry has the form - [Chapter N: Title](https://aospbooks.github.io/aosp-internal-book/<slug>/): one-line description of what the chapter covers and the key components it walks through. Do not update llms.txt for routine edits inside a chapter (typo fixes, mermaid tweaks, prose rewrites that don't change the chapter's scope). When editing, also confirm every URL still resolves to a real <slug>.md in the repo root.
12. Never cite line-of-code counts. Do not write how many lines a file, class, crate, or subsystem contains — no (1,210 lines), no "at roughly 7,200 lines", no "Lines of Code" table column, no # 8234 lines comment in a source tree listing. These numbers go stale on every AOSP sync and are the first thing to rot in a chapter. Convey scale with prose the source can't invalidate ("one of the largest classes in the framework", "a small file of stubs") or, better, with a structural fact that is actually stable (how many files a package has, what the class is responsible for). This does not apply to source citations with line numbers (file.cpp:123, "lines 117-131"), which rule 6 requires, nor to qualitative scale statements with no specific count ("hundreds of millions of lines of code").
13. Update the top-level README.md when chapters are added, removed, renamed, or reordered. Hand-edit the chapter table under "What This Book Covers" (each row carries its Part), the chapter count in the surrounding prose, and the file counts under "Project Structure". llms.txt (rule 11) groups chapters by the same Parts, so keep the two in step.