Opus 4 Writing Guide - Technical Documentation Standards

Hrishi Olickel & Claude Opus 4·

Writing Guide for Claude Code Technical Deep Dive

Overall Principles

  1. Lead with Implementation Details - Start each section with the most interesting/novel technical detail, then provide context
  2. Code-First Explanations - Show actual or conceptual code snippets before explaining what they do
  3. Visual Information Hierarchy - Use tables, diagrams, and formatting to make scanning efficient
  4. Inference Transparency - Use phrases like "appears to", "likely implements", "suggests" when describing decompiled behavior
  5. Cross-Reference Liberally - Link between sections when concepts relate, building a web of understanding

Section-Specific Guidelines

1. Dependencies

Approach: Dependency graph visualization first, then drill into interesting clusters

  • Start with a dependency network diagram (mermaid) showing relationships between major subsystems
  • Group by architectural purpose, not just category
  • Highlight novel uses (e.g., yoga-layout-prebuilt for CLI layout)
  • Include version ranges where significant
  • Add "Why This Matters" callouts for non-obvious choices

Format Ideas:

Text
┌─ Core Loop ─────────────┐ │ ink + react → UI │ │ ↓ │ │ yoga-layout → Layout │ └────────────────────────┘

2. Data Structures

Approach: Show state transitions and data flow through structures

  • Begin with a state machine diagram showing message lifecycle
  • Use TypeScript interfaces with inline comments explaining design decisions
  • Include "mutation points" - where and why data changes
  • Add size/performance annotations where relevant
  • Merge in the bidirectional streaming details from Section 8

Format Ideas:

  • Side-by-side comparisons of internal vs API structures
  • Transformation pipeline diagrams
  • Memory layout visualizations for performance-critical structures

3. Control Flow

Approach: Interactive flow visualization with code annotations

  • Start with the most complex flow (parallel tool execution)
  • Use swimlane diagrams for concurrent operations
  • Inline the actual generator function signatures
  • Add timing annotations
  • Integrate the main loop (tt) structure details from Section 8

Format Ideas:

TSX
// Actual control flow annotation async function* tt(...) { // ┌─ PHASE 1: Context Assembly [~50ms] // ├─ PHASE 2: LLM Stream [~2-5s] // └─ PHASE 3: Tool Execution [varies] }

4. Tools

Approach: Implementation-first, then usage patterns

  • Start with the tool execution pipeline code
  • Show the actual Zod schema → JSON Schema conversion
  • Include performance characteristics table
  • Add decision tree for tool selection
  • Merge in the shell parser specifics from Section 8

Format Ideas:

  • Tool capability matrix (what each tool can/cannot do)
  • Execution timeline visualization
  • Side-by-side tool comparison for similar operations

5. Architecture

Approach: Build up from primitives to system

  • Start with the event loop and message pump
  • Show actual module boundaries and interfaces
  • Include memory/resource management strategies
  • Add scaling considerations
  • Integrate ANR detection mechanism from Section 8

Format Ideas:

  • Layered architecture diagram with data flow volumes
  • Module dependency graph with coupling metrics
  • Resource allocation visualization

6. Novel Components

Approach: Deep dive into implementation details

  • Start with the actual algorithm/code
  • Show performance comparisons with alternatives
  • Include edge case handling
  • Add extension points for customization
  • Merge in parallelMap coordination from Section 8

Format Ideas:

Text
Algorithm: Streaming JSON Parser ================================ Input: {"very": "lar█ (stream ends) State: Stack=[OBJ, STRING] Depth=2 Action: Auto-close with }"} Output: {"very": "lar"}

7. File Editing

Approach: Show the complete edit pipeline

  • Start with the most complex case (MultiEdit with conflicts)
  • Include validation flow diagram
  • Show actual diff generation code
  • Add rollback/recovery mechanisms
  • Include permission system integration

Format Ideas:

  • Edit conflict resolution flowchart
  • Before/after file state visualization
  • Validation pipeline diagram

Cross-Cutting Formatting Ideas

  1. Performance Annotations

    Text
    ┌─ ReadTool ─────────────┐ │ Latency: ~10ms │ │ Memory: O(file_size) │ │ Concurrent: Yes │ └────────────────────────┘

  2. Decision Points

    Text
    IF response.stop_reason == "tool_use" ├─ YES → Execute Tools (parallel/sequential) └─ NO → Return to User

  3. Implementation Notes

    TSX
    // IMPL NOTE: readFileState uses weak references // to allow GC of large file contents

  4. Inference Markers

    Text
    🔍 Based on function naming and structure, this appears to implement...

Section Integration Strategy

  • Move shell parser details into Tools section under BashTool
  • Integrate ANR detection into Architecture's monitoring subsection
  • Place streaming JSON parser in Novel Components
  • Distribute parallelMap details between Control Flow and Architecture
  • Embed guardrail configuration points throughout relevant sections

Quality Checklist for Each Section

  • Starts with implementation detail, not introduction
  • Includes actual or representative code
  • Has at least one visualization
  • Cross-references other sections
  • Marks inferred vs observed behavior
  • Provides actionable insights
  • Includes performance/resource implications
  • Has formatting variation and takes advantage of the tools available to markdown and mermaid