Writing & Structuring Guide

1. Audience & Goals

   • Deeply–technical practitioners who already know what Claude Code is.

   • Deliver practical, agent-design take-aways rather than “what is Claude Code.”

   • No marketing fluff; keep prose dense, active, and example-driven.

2. Voice & Style

   • Concise, declarative sentences (“X yields Y”)—avoid passive filler.

   • Terminology: prefer canonical names from the codebase (e.g. ToolUseBlock).

   • Occasional short metaphor or analogy is OK, but maximum one per major section.

   • Use second-person plural (“we observe…”, “you can apply…”) for recommendations.

3. Formatting Conventions

   • Top-level sections = H2 (##).

   • Key insights, pitfalls, or rules = block-quote call-outs beginning with Note, Pitfall, Guideline.

   • Long enumerations = tables; workflows = numbered lists.

   • Code / JSON / TypeScript snippets in triple-back-tick blocks with language tags.

   • Complex flows = d2 diagrams; lighter flows = Mermaid.

   • Cross-reference internal sections via explicit anchors ([#data-structures]).

   • Every figure gets a short caption.

4. Creativity & Engagement

   • Interleave “Debug Walk-through” sidebars that trace a concrete scenario (≈15 lines) to ground concepts.

   • Add “Design Pattern Cards” (mini-boxes) that summarize reusable patterns (e.g., Parallel Read-Only Tool Batch).

   • Provide “Implementation Snippets” showing the minimum code that realises a concept—never full files.

5. Information Density Strategy

   • Begin each major section with a 3-bullet “Why it Matters.”

   • Finish each section with “Key Agentic Lessons” bullet list.

   • Appendix holds verbatim schema listings so main text stays readable.

6. Review & Verification Pass

   • After drafting each section, run a checklist:

   – Did we preserve every non-trivial point from the source notes?

   – Is there at least one concrete example or snippet?

   – Is there an explicit lesson or recommendation?

   • Final lint pass for sentence length (<25 words target) and jargon repetition.

Comprehensive Outline

The outline mirrors the original de-compiled notes but reorganises for pedagogical flow.

Bracketed IDs (e.g., §A1) are stable anchors for cross-references.

---

§0 Executive Cheat-Sheet

• TL;DR bullets of the ten biggest design wins.
• One d2 “layer cake” diagram of the full stack.

§A Architecture Overview

§A1 Layered Model (User → LLM → Tools → OS)

• d2 diagram (colour-coded layers).
• Streaming-first principle.

§A2 Cross-Cutting Concerns

• State management, configuration, telemetry.

§B Core Data Structures [#data-structures]

§B1 CliMessage & Message Flow

• Table mapping internal vs API fields.
• Debug Walk-through box: single turn lifecycle.

§B2 ContentBlock Taxonomy

• Mermaid class diagram.
• Citation, multimedia, tool-specific blocks.

§B3 ToolDefinition & Execution Contexts

• Pattern Card: “Async-Generator Tool Contract.”

§B4 Session & Permission Models

• JSON snippet of a real permission context.

§C Conversation Control Flow

§C1 Main Loop (tt) Phases

• Numbered sequence diagram.

§C2 Auto-Compaction & Retry Logic

• Heuristic description + code fragment.

§C3 Streaming Event Handling

• Delta types table; thinking vs input_json_delta.

§D Tooling System Deep Dive

§D1 Default Tool Catalog

• Concise table (name, purpose, read/write, gotchas).

§D2 Parallel vs Sequential Execution

• d2 diagram of batching algorithm.

§D3 MCP Extensibility

• JSON-RPC handshake flow.

§D4 AgentTool & Sub-Agent Architecture

• Two-step d2 diagram (spawn & synthesis).
• Design Pattern Card: “Hierarchical Agent.”

§E Novel Components & Algorithms

§E1 Streaming JSON Parser Heuristics

§E2 Custom Shell Parser with JSON Embedding

§E3 Size-Bound Normalization Utility

§E4 ANR Detection in Node Workers

• Each with mini “Why it exists → How it works → Reuse?” triad.

§F File Editing Workflows

§F1 Read → Edit/MultiEdit/Write Guardrails

• Flowchart.

§F2 Notebook-Specific Handling

§F3 Diff Generation & Feedback Channel

§G Security & Safety Architecture

§G1 Permission Layers & Modes

§G2 Sandboxing Strategy (BashTool)

§G3 Malicious-Code Refusal & Guardrails

§H Concurrency & Performance

• ParallelMap utility, token counting, cache points.
• Metrics instrumentation hooks.

§I Agentic Lessons & Best Practices

• 12 distilled principles (e.g., “Tools are Control-Flow Primitives”).
• Quick comparison table vs. other open-source agent stacks.

§J Future Directions & Open Questions

• Model-adaptive prompting, richer UI affordances, pluggable RAG.

§K Appendices

§K1 Full JSON Schemas

§K2 Environment Variable Matrix

§K3 Reference d2 & Mermaid Source

---

Deliverables Checklist

• ☑ Writing guide (above)
• ☑ Full outline with anchors, diagrams, pattern cards, examples, and lessons
• ☑ Ready for markdown rendering; all headings and IDs stable for later linking