Claude Code Playbook

A living playbook for using Claude Code effectively, maintained through systematic community-driven curation.

The Playbook

claude-code-tips.md — A senior-level guide to Claude Code workflows, context management, and multi-agent patterns.

About This Project

This project serves two purposes:

1. Learning & sharing — A way for me to deepen my own Claude Code expertise while sharing crowdsourced tips with others

2. An experiment in agentic PKM — Exploring how AI agents can assist with learning and personal knowledge management, specifically: can an agent systematically curate community knowledge into a living document while keeping a human in the loop?

This README describes the meta-process: how the playbook is maintained and evolved. Rather than relying solely on personal experience, the playbook synthesizes high-signal insights from the Claude Code community through a systematic curation workflow.

Key principle: Human-reviewed, Claude-proposed. All changes go through a proposal stage before merging.

Curation Workflow

flowchart LR
    subgraph Input["Input Sources"]
        A1[("Digest<br/>(external)")]
        A2[("URL<br/>(article/post)")]
        A3[("File<br/>(local md/txt)")]
    end

    subgraph Process["Process"]
        B["Process Source<br/><code>/update-playbook-*</code>"]
    end

    subgraph Review["Review"]
        C["Review Proposals<br/><code>/review-proposals</code>"]
        C2["Summary<br/><code>/review-proposals-summary</code>"]
    end

    subgraph Apply["Apply"]
        D["Apply Changes<br/><code>/apply-proposals</code>"]
    end

    subgraph Publish["Publish"]
        E["Publish to Git<br/><code>/publish</code>"]
    end

    A1 --> B
    A2 --> B
    A3 --> B
    B --> |"claude-code-tips<br/>.proposed.md"| C
    C2 -.-> C
    C --> |"Enhanced<br/>proposals"| D
    D --> |"claude-code-tips.md"| E
    E --> |"git commit"| F[("Repository")]

Loading

Step 1: Generate Digest (External)

Use curated-post-digest to scan Reddit (r/ClaudeCode) and produce structured digests:

# In curated-post-digest repo
python -m curated_post_digest --subreddit ClaudeCode --days 30

Copy the output to output/digests/YYYY-MM-DD/.

Step 2: Process Source

Process content from any of three input types:

/update-playbook-digest [YYYY-MM-DD]   # Process a digest
/update-playbook-url <url>              # Process a URL (article, post, docs)
/update-playbook-file <path>            # Process a local file

Invokes the playbook-curator agent to:

• Read and analyze the source content
• Identify high-signal patterns worth adding
• Write proposals to claude-code-tips.proposed.md
• Log processing status (for digests: to output/processed.log)

Step 3: Review Proposals

/review-proposals-summary    # Quick read-only overview
/review-proposals            # Interactive review

Summary shows a grouped overview (high-impact, medium-impact, housekeeping) for quick status checks.

Interactive review allows you to:

• View signal strength (upvotes, ratio) for each
• Enhance sections with more detail from source posts
• Drop low-value proposals
• Keep proposals as-is

Step 4: Apply Changes

/apply-proposals

Merges reviewed proposals into the canonical playbook:

• Strips HTML comments (rationale markers)
• Overwrites claude-code-tips.md
• Regenerates table of contents
• Handles cleanup of proposed file (delete, clear, or keep)

Step 5: Publish to Git

/publish

Commits changes with structured changelog notes:

• Generates changelog based on sections modified
• Includes source attribution (digest date, post count)
• Creates commit with proper formatting

Commands Reference

Command	Description
/update-playbook-digest [date]	Process a digest and generate proposals
/update-playbook-url <url>	Process a single URL (article, post, docs)
/update-playbook-file <path>	Process a local markdown/text file
/digest-status	Show available digests and processing status
/review-proposals-summary	Quick read-only summary of pending proposals
/review-proposals	Interactive review/enhance/drop proposals
/apply-proposals	Merge proposals into canonical playbook
/publish	Commit changes with structured changelog notes

Agent Reference

playbook-curator

Location: .claude/agents/playbook-curator.md

Purpose: Evolves the playbook using community insights. Reads digests, identifies patterns, proposes changes.

Key behaviors:

• Proposal-only — never modifies canonical playbook directly
• Prioritizes processed_posts.json over raw_posts.json (context budget)
• Maintains senior-level, opinionated tone
• Prefers fewer high-impact edits over many small ones

Editorial bar:

• Target audience: Senior engineers, heavy Claude Code users
• Avoid: Tutorials, onboarding material, Reddit commentary

Directory Structure

├── claude-code-tips.md              # Canonical playbook (human-owned)
├── claude-code-tips.proposed.md     # Claude-generated proposals (reviewable)
├── CLAUDE.md                        # Claude Code instructions
├── README.md                        # This file
│
├── sources/                         # Local files for processing
│   └── *.md                         # Markdown/text files to process
│
├── output/
│   ├── processed.log                # Tracks processed digest dates
│   └── digests/
│       └── YYYY-MM-DD/
│           ├── report.md            # Summary report
│           ├── processed_posts.json # Ranked/filtered posts
│           └── raw_posts.json       # Full post data
│
└── .claude/
    ├── agents/
    │   └── playbook-curator.md      # Curation agent
    └── commands/
        ├── update-playbook-digest.md      # Process digest
        ├── update-playbook-url.md         # Process URL
        ├── update-playbook-file.md        # Process local file
        ├── digest-status.md               # Status check
        ├── review-proposals-summary.md    # Quick summary
        ├── review-proposals.md            # Interactive review
        ├── apply-proposals.md             # Apply changes
        └── publish.md                     # Git commit with changelog

Files

File	Owner	Purpose
claude-code-tips.md	Human	Canonical playbook — the source of truth
claude-code-tips.proposed.md	Claude	Staging area for proposed changes
sources/*	Human	Local files to process for insights
output/processed.log	System	Tracks which digests have been processed
output/digests/*	External	Immutable snapshots from curated-post-digest

Design Principles

1. Human-in-the-loop: Claude proposes, humans approve
2. Signal over noise: High-upvote, high-ratio posts carry more weight
3. Senior-level focus: No beginner tutorials or generic AI advice
4. Immutable inputs: Digests are read-only snapshots
5. Traceable rationale: HTML comments in proposals explain why each change was made
6. Context-aware: Agent prioritizes smaller files to stay within token limits

Related Projects

• curated-post-digest — Generates the input digests
• cconami — Referenced in the playbook for agent/command examples