Skip to content

Instantly share code, notes, and snippets.

@bedwards

bedwards/a.md

Last active January 19, 2026 20:57
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save bedwards/8edb817c52fe96e118f920671b1e71d1 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save bedwards/8edb817c52fe96e118f920671b1e71d1 to your computer and use it in GitHub Desktop.
Download ZIP
a
Raw
a.md

Claude Agent SDK Lessons Learned (War Stories)

Real-world lessons from building with the Claude Agent SDK:

Process Discipline

  1. Manager vs Worker Separation - The conversational Claude should NEVER write implementation code. Create issues, let worker agents implement. This prevents scope creep and ensures all work is tracked.

  2. Don't Remove Functionality - When adding features, expand existing code rather than replacing it. Easy to accidentally break things during "simplification."

  3. Maintain Broad Perspective - Easy to get tunnel vision on one feature. Keep the whole system in mind.

Technical Lessons

  1. Git Worktrees for Isolation - Workers operate in worktrees so failures don't affect main branch. Essential for autonomous operation.

  2. Frequent Commits - Worker should commit after each significant change. Enables recovery and visibility.

  3. Local Validation First - Run lint/typecheck/tests locally before pushing. Faster feedback than CI.

  4. Handle API Rate Limits - GitHub API has rate limits. Worker needs backoff logic.

Claude Agent SDK Specifics

  1. Tool Results Are Rich - Tool results can include system reminders and context. Parse carefully.

  2. Context Windows Fill Up - Long conversations get compacted. Maintain external state (todo lists, issue descriptions) rather than relying on conversation memory.

  3. Parallel Tool Calls - Use parallel tool calls when operations are independent. Significant speedup.

  4. Subagent Spawning - Task tool spawns subagents for complex work. Each subagent is fresh context.

What Works Well

  • GitHub Issues as source of truth for requirements
  • Worker agent handling full PR lifecycle
  • Claude GitHub integration for automated review
  • Structured logging for debugging autonomous workers

What's Tricky

  • Error recovery when worker hits unexpected states
  • Balancing autonomy with user oversight
  • Managing context across long conversations
  • Testing async/autonomous behaviors
Raw
b.md

Analysis: Why We're Struggling

  1. Parallel work on conflicting files
  • Launched 5 workers simultaneously on issues that ALL modified main.ts
  • Result: 4 PRs with merge conflicts, had to close and redo
  1. Missing deployment automation
  • Worker code merged but never deployed to Cloudflare
  • User discovered broken app in production
  1. Incomplete requirements capture
  • Original issue #40 was broad ("AI-generated branches")
  • Didn't specify: home page, URL routing, multi-story, saved games
  • Discovered requirements incrementally during implementation
  1. No end-to-end verification
  • Workers ran tests, CI passed, but nobody tested the actual deployed app
  • Broken user experience shipped

Recommendations:

  1. Sequential work on shared files - Don't parallelize issues that touch the same core files
  2. Deployment in CI - Just added via PR#56
  3. Upfront requirements - Spend more time specifying before creating issues
  4. Smoke tests - Add automated E2E tests or manual verification step
  5. Smaller, focused issues - Break down by file/component, not by feature

Should I create issues to address these process improvements?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment