Agent-Driven Development with Git Worktrees

I've been experimenting with AI coding assistants and found myself struggling with context management on complex features. The conversations would get muddy, mixing planning details with implementation, and important decisions would get lost in the scroll. So I developed a workflow that leverages git worktrees to create clean boundaries between planning and coding phases.

The Problem

Working with AI assistants on complex features presents unique challenges:

1. Context Overload: Planning discussions mixed with implementation details make it hard to maintain focus
2. Lost Decisions: Architectural choices get buried in long conversation threads
3. Parallel Work: Switching between features requires constant context switching
4. Environment State: Different features need different configurations or dependencies

The Solution: Agent-Driven Development with Worktrees

Git worktrees let you work on multiple branches simultaneously without stashing or switching. When combined with AI agents, they enable a powerful workflow:

project/
├── .bare/          # Bare git repository
├── main/           # Main branch worktree
├── feature-x/      # Feature branch with planning docs
├── feature-y/      # Another feature in progress
└── justfile        # Orchestrates the workflow

The Workflow

Phase 1: Planning

Start a planning session with a dedicated AI agent:

just plan user-analytics "I need to add user analytics tracking to the blog"

This command:

1. Creates a new worktree for the feature
2. Launches Claude Code with planning-specific context
3. Guides the agent to gather requirements and research the codebase
4. Results in a comprehensive requirements document

The planning agent focuses solely on understanding the problem, researching existing patterns, and documenting decisions.

Phase 2: Working the Plan

Once planning is complete, start the implementation phase:

just work user-analytics

This command:

1. Copies necessary environment files (.env, configs)
2. Creates implementation context for the new agent
3. Launches Claude Code with instructions to implement based on the requirements
4. The implementation agent has a clear specification to follow

Key Benefits

1. Clear Separation of Concerns

• Planning agents focus on research and documentation
• Implementation agents focus on coding
• Each phase has appropriate context and tools

2. Parallel Development

• Multiple features can be in different stages
• Each worktree maintains its own state
• No branch switching or stashing required

3. Knowledge Preservation

• Requirements documents capture all decisions
• Planning artifacts are archived after completion
• Clear handoff between AI sessions

4. Environment Isolation

• Each feature has its own working directory
• Environment files are automatically copied
• Dependencies remain isolated

Implementation Details

The workflow is orchestrated through a justfile at the repository root:

# Start planning session for a new feature
plan feature *args:
    # Create worktree if needed
    if [ ! -d "{{feature}}" ]; then
        just new "{{feature}}"
    fi

    # Start Claude Code with planning context
    cd "{{feature}}" && cat ../PLANNING.md | claude --prompt \
        "I need to plan '{{feature}}'. {{args}} Help me create requirements."

# Start implementation after planning
work feature:
    # Copy environment files
    for env_file in .env .env.local; do
        if [ -f "main/$env_file" ]; then
            cp "main/$env_file" "{{feature}}/"
        fi
    done

    # Start Claude Code with implementation context
    cd "{{feature}}" && cat IMPLEMENTATION.md | claude --prompt \
        "Implement {{feature}} based on the requirements document."

Planning Context (PLANNING.md)

The planning agent receives context about its role:

You are starting a planning session. Your goal is to:

1. Gather Requirements: Ask clarifying questions
2. Research: Explore the existing codebase
3. Document: Create a comprehensive requirements document
4. Plan: Outline clear implementation steps

Remember: You're planning, not implementing.

Implementation Context (IMPLEMENTATION.md)

The implementation agent receives different instructions:

You are implementing based on the planning phase.

Key Resources:

- Requirements: Read docs/planning/requirements.md first
- Codebase Context: Run `just context`
- Testing: Run `just check` before committing

Start by reading the requirements document.

Additional Commands

The workflow includes several utility commands:

# List all features and their status
just features

# Archive completed feature (saves docs, removes worktree)
just archive user-analytics

# Quick planning without creating a worktree
just quick-plan "refactor authentication system"

What I'm Learning

This is still an experiment. I'm testing this workflow on my own projects to see how well it handles real-world development scenarios. Early observations:

1. Complex Features: The separation really shines when breaking down large features
2. Documentation: Requirements docs become valuable project documentation
3. Onboarding: Planning docs could help new contributors understand feature decisions
4. Experimentation: Isolated worktrees make it safe to try different approaches

Getting Started

To implement this workflow in your project:

1. Set up git worktrees (see my post on supercharging your workflow with git worktrees)
2. Create the planning and implementation context files
3. Add the just commands to orchestrate the workflow
4. Start planning your next feature!

I'm actively using this workflow in my projects and will be publishing a template repository soon to make it easy for others to try.

Conclusion

Agent-driven development with git worktrees brings structure to AI-assisted coding. By separating planning from implementation and leveraging worktrees for isolation, we can build features more thoughtfully while maintaining clear documentation and context boundaries.

The key insight is that AI agents, like human developers, benefit from focused contexts and clear handoffs. This workflow provides exactly that, making both the AI and the developer more effective. I'll continue refining this approach as I use it on more projects - stay tuned for updates!