Skip to content

CLAUDE.md

Latest commit

 

History

History
53 lines (39 loc) · 2.4 KB

CLAUDE.md

File metadata and controls

53 lines (39 loc) · 2.4 KB

CLAUDE.md

Project

tutorial-gen — a LangGraph supervisor-subagent pipeline that generates tutorials from Claude Code's CHANGELOG.

Commands

# Run tests
PYTHONPATH=src .venv/bin/python -m pytest tests/ -v

# Install for development
pip install -e ".[dev]"

# CLI
tutgen run [--dry-run] [--limit N]
tutgen status
tutgen list

Architecture

  • Pattern: Supervisor-subagent with feature loop (LangGraph StateGraph)
  • State: PipelineState TypedDict in src/tutorial_gen/state.py — uses Annotated reducers for messages, processed_features, errors
  • Graph: Built in src/tutorial_gen/graph.py via build_graph() — supports skip_fetch=True for CLI --limit mode
  • Agents: In src/tutorial_gen/agents/ — each is an async function returning a state dict
  • Nodes: In src/tutorial_gen/nodes/ — fetch, diff, save (non-LLM)
  • DB: SQLite via src/tutorial_gen/db.py — tracks processed features

Conventions

  • All agent/node functions take PipelineState and return dict with state updates
  • LLM agents use langchain-anthropic (ChatAnthropic) — mock with patch("...ChatAnthropic") in tests
  • Shared utilities go in src/tutorial_gen/agents/__init__.py (e.g. extract_script)
  • Prompt templates live in src/tutorial_gen/prompts/ — one file per agent
  • Tests use pytest-asyncio with asyncio_mode = "auto"
  • The validator uses an allowlist-based env (PATH, HOME, USER, SHELL, TERM, LANG only) — sensitive keys like ANTHROPIC_API_KEY are never passed to generated scripts

Script Generation Patterns

Prompts enforce realistic Claude Code usage in generated tutorials and demo scripts:

  • Session chaining is the primary pattern — --output-format json to capture session_id, then --resume for follow-ups
  • Slash commands (/simplify, /batch, /cost) are interactive — prompts require they be shown inside sessions via --resume, never as standalone CLI args
  • claude -p one-shots are reserved for simple standalone demos only
  • No fake output — scripts must not use echo to simulate Claude responses

Key Files

  • src/tutorial_gen/state.py — State schema (modify here when adding new state fields, always add reducer annotations for list fields)
  • src/tutorial_gen/graph.py — Graph assembly (add new nodes/edges here)
  • src/tutorial_gen/cli.py — CLI entry point
  • pyproject.toml — Dependencies and project config