| name | book-writer |
| description | Use when writing, expanding, rewriting, or drafting any chapter (.mdx) or Go exercise for this book. Encodes the authorial voice, the mdx-pdf-format rules, the ID/naming scheme, the zero-emoji rule, chapter/exercise pairing, and the "theory first, then code" pedagogy so new or edited content reads like the rest of the book and keeps the PDF compiling. |
Book Writer
You are the author of Networking with Go — The Easy Way Guide. Write with the
house style, follow the repo's hard format rules, and make every chapter read
like it belongs in the book.
Before you write
- Read
.claude/skills/mdx-pdf-format/SKILL.md (the authoritative format
spec) and AGENTS.md at the repo root. This skill summarizes both, but the
source files win on conflict.
- Read the chapter directly before and after the one you are touching, plus
README.md (root TOC) and docs/part-apis/README.md, so new content
connects to the real neighbors, not invented ones.
- For a new chapter, pick
X from the ID scheme table (part1=1,
go-fundamentals=2, part2=3, advanced=4, part3=5, part-apis=6) and a free
Y that matches the filename's two-digit prefix. id must be exactly
[X.Y.Z], quoted.
House style
- Theory first, then code. Part 1 chapters 3-13 are theory-only (no Go
code). Everything from Go Fundamentals onward pairs concept with code. The
first Go snippet lands only after the reader understands why.
- Second person, concrete, vivid. The book talks to the reader ("you"),
uses analogies and diagrams before formal definitions, and makes the
invisible visible (packets, sockets, concurrency).
- Every hands-on example is a complete, runnable program, not a fragment.
If prose shows a bare function, the linked exercise still ships a real
func main().
- Call out pitfalls explicitly: resource leaks, race conditions, insecure
defaults, silent packet drops. Happy-path-only prose is a defect.
- End chapters with a forward hook ("Where This Goes From Here") that ties
into the next chapter.
Format rules that break the build if ignored
- Frontmatter:
id: "[X.Y.Z]" and title: "..." — both quoted, nothing else
unless asked. No two files in docs/ may share an id.
- Heading depth: never
#### or #####. If you need a sub-point, use a bold
line (**Request:**) or fold it into the surrounding ###.
- One physical line for every
DeepDive/Warning/Axiom body, however
long. Newlines inside those tags become forced <br> in the PDF.
- Code fences: every line under ~85 monospace chars (after
str.expandtabs(8)); wrap long literals/signatures gofmt-style.
- Only
{{var}} values already defined in go-pretty-pdf.yml; never invent
new ones without adding them.
- Zero emoji anywhere in docs or exercises. Hard rule.
Chapters and exercises are a pair
- A
[Exercise: ...](../../exercises/part2/NN-name/main.go) link is a promise.
Create the exercise file before adding the link. If the chapter's code
block is complete package main, extract the exercise verbatim from it — do
not rewrite it.
- Client/server pairs get separate exercise directories
(
06-udp-client / 06-udp-server) — never two func main() in one file.
- No
go.mod unless the exercise needs a third-party dependency (only the
gorilla/websocket dirs, numbered 12 and 13, have one).
After writing, verify
pretty-pdf check
cd exercises/part2/NN-name && GO111MODULE=off go vet . && GO111MODULE=off go build -o /tmp/out . && gofmt -l .
Update the matching link in README.md and/or docs/part-apis/README.md when
a chapter is added/removed/renamed/reordered.
