workshop-a2a-mcp: Instructions file for Claude Code

CLAUDE.md - Strict Implementation Rules

🚨 CRITICAL: How to Build This Notebook

Rule 1: NEVER Write Full Files

• WRONG: Creating entire notebook at once
• RIGHT: Build cell by cell, appending to notebook
• Use iterative approach: Plan → Build Cell → Next Cell

Rule 2: Cell-by-Cell Development Process

Follow this EXACT pattern for EVERY cell:

# Step 1: Count current cells
python3 -c "import json; nb = json.load(open('workshop_notebook.ipynb')); print(f'Current cells: {len(nb[\"cells\"])}')"

# Step 2: Calculate cell_id for next cell
# If you have N cells, use cell_id="cell-(N-1)" to append at position N

# Step 3: Add the cell using NotebookEdit
NotebookEdit(
    notebook_path="/path/to/notebook.ipynb",
    edit_mode="insert",
    cell_id="cell-X",  # X = current_cells - 1
    cell_type="markdown" or "code",
    new_source="content"
)

IMPORTANT PATTERN TO REMEMBER:

• First cell: Don't specify cell_id (notebook is empty)
• Second cell: Use cell_id="cell-0" (append after first cell)
• Third cell: Use cell_id="cell-1" (append after second cell)
• Fourth cell: Use cell_id="cell-2" (append after third cell)
• Pattern: For cell N, use cell_id="cell-(N-2)" to append at end

Rule 3: Narrative Structure

EVERY section must follow this narrative flow:

1. Hook - Why this matters
2. Explain - What we're building
3. Show - Visual or diagram
4. Build - Code implementation
5. Test - Verify it works
6. Reflect - Key takeaway

Rule 4: Progressive Complexity Mandate

Start ridiculously simple, add complexity gradually:

# Cell 1: Simplest possible
agent = ChatOpenAI()
response = agent.invoke("What is cardiac arrest?")

# Cell 5: Add a tool
agent_with_tool = create_agent(tools=[search_tool])

# Cell 10: Add MCP
agent_with_mcp = create_agent(tools=[mcp_tools])

# Cell 20: Multi-agent
system = create_multi_agent_system()

Rule 5: Documentation Requirements

ENFORCE 50/50 Rule:

• Every code cell MUST have preceding markdown cell
• Markdown must be ≥ 3 sentences
• Include WHY not just WHAT