Agent-Driven Development: How AI Tools Built This Blog

November 11, 2025•9 min read

productivitydevopswebdevwriting

Introduction: What Is Agent-Driven Development?

Agent-driven development represents a fundamental shift in how we build software. Instead of writing every line of code manually or relying on simple autocomplete, we orchestrate specialized AI agents that understand context, maintain consistency, and execute complex workflows autonomously.

This blog itself was built entirely using this approach—from the initial architecture planning to the implementation of every feature. In fact, this very blog post is being written as part of the /ship-feature workflow for Linear ticket M3L-55, using three parallel senior-software-engineer agents working on three posts simultaneously.

Agent-driven development isn't about replacing developers; it's about amplifying our capabilities. We still design systems, make architectural decisions, and ensure quality—but we delegate implementation details to specialized agents that excel at their specific domains.

The Tool Stack: Claude Code, Serena MCP, and Linear

Our agent-driven workflow relies on three core tools working in harmony:

Claude Code serves as the orchestration layer—a CLI that connects Claude's language model to your local development environment. It provides agents with the ability to read files, write code, execute commands, and manage complex workflows.

Serena MCP (Model Context Protocol) transforms how agents understand codebases. Instead of treating code as text, Serena provides semantic operations—finding symbols, understanding relationships, and refactoring at the AST level. This is the difference between "search for the string 'useState'" and "find all React hooks in components."

Linear MCP integrates project management directly into the development flow. Agents can read requirements from tickets, update issue states as they progress, and comment with implementation details—creating a complete audit trail of automated work.

Together, these tools create a development environment where agents aren't just writing code—they're participating in the full software development lifecycle.

Agent Specialization: Dividing Responsibilities

Just as human teams benefit from specialization, our AI agents each have distinct roles and capabilities:

senior-software-engineer handles implementation—creating components, refactoring code, optimizing performance. This agent understands architectural patterns, follows coding standards, and makes pragmatic trade-offs.

code-reviewer ensures quality through comprehensive testing and analysis. It plans test coverage, writes Playwright tests, audits bundle sizes, and verifies accessibility compliance.

product-manager breaks down features and clarifies requirements. When faced with ambiguous specifications, this agent creates actionable tickets and prioritizes work based on the project roadmap.

ux-designer maintains design system consistency. From color palettes to responsive layouts, this agent ensures every component follows established patterns while meeting accessibility standards.

Each agent operates with specific guidelines defined in .claude/CLAUDE.md. Here's how we specify when to use each agent:

### When to Use Which Agent
 
#### senior-software-engineer
**Use proactively for**:
- Implementing server-first components
- Creating client islands with lazy loading
- Building MDX processing pipeline
- Performance optimizations
- Refactoring to reduce bundle size
 
#### code-reviewer
**Use proactively for**:
- Planning test coverage for new features
- Writing Playwright tests
- Reviewing bundle size impact
- Ensuring accessibility compliance
- Performance audits

Workflows We Built: From Migration to Feature Implementation

Migration Workflow

Our most complex workflow handled the migration from Next.js 16 to Next.js 15 with React 19. This wasn't a simple version change—it required coordinating multiple agents across 8 phases:

Planning Phase: product-manager analyzed breaking changes and created a migration roadmap
Test Planning: code-reviewer designed comprehensive test coverage (29 tests for version validation alone)
Implementation: senior-software-engineer executed the migration in careful sequence
Validation: Automated test runs after each phase
Documentation: Updates to CLAUDE.md with lessons learned

The entire migration (M3L-26 through M3L-30) was completed in under 48 hours with zero production incidents.

Feature Implementation Workflow

For new features, we developed the /ship-feature command that orchestrates multiple agents in parallel. Here's the actual workflow configuration:

## Workflow Steps
 
### Step 1: Requirements Gathering
1. Read Linear ticket details using mcp__linear-personal__get_issue
2. Parse acceptance criteria and requirements
3. Identify phase (NOW/NEXT/LATER) from project roadmap
 
### Step 2: Planning & Design
1. Create implementation plan with milestones
2. Design component structure following design system
3. Plan test coverage (with/without JavaScript)
 
### Step 3: Parallel Implementation
Launch three senior-software-engineer agents simultaneously:
- Agent 1: Core feature implementation
- Agent 2: Test infrastructure
- Agent 3: Documentation/blog post
 
### Step 4: Integration & Testing
1. Merge parallel work
2. Run comprehensive test suite
3. Verify bundle size budgets
4. Update Linear ticket with results

Real Examples: Print CSS and Test Infrastructure

Print CSS Implementation (M3L-33)

The print CSS feature demonstrates the power of agent-driven development. Starting with high-level requirements ("perfect PDF output for archival"), the workflow produced a comprehensive 595-line stylesheet with sophisticated transformations:

/* Agent-generated print stylesheet excerpt */
@media print {
  /* Page configuration with white background */
  @page {
    margin: 1in;
    size: letter;
    background: #FFFFFF; /* Fixes black margins */
  }
 
  /* Aggressive Tailwind overrides */
  .bg-background-primary,
  .bg-background-secondary,
  [class*="bg-background"] {
    background-color: #FFFFFF !important;
  }
 
  /* Link expansion for archival */
  a[href]:after {
    content: " (" attr(href) ")";
    font-size: 0.85em;
    color: #666;
  }
}

The agent didn't just write CSS—it discovered and fixed browser-specific bugs (black margin issue), implemented smart page breaks, and ensured all 735 existing tests continued passing.

Test Infrastructure (M3L-39)

Building comprehensive test coverage showcased how agents excel at systematic work. The code-reviewer agent analyzed the entire codebase and generated test plans covering:

Migration validation (29 tests)
Frontmatter schema validation (706 tests)
Performance baselines
Accessibility compliance
Progressive enhancement

The resulting test suite runs in under 7 seconds while providing confidence across browsers and devices.

Serena MCP Deep Dive: Semantic Over Text-Based Operations

Traditional code search treats files as text. Serena MCP understands code semantically, enabling operations that would be error-prone with regex:

Finding Symbols Semantically

Instead of searching for text patterns, Serena finds symbols by their role in the code:

# Traditional text search (error-prone)
grep -r "class.*Button" --include="*.tsx"
 
# Serena MCP semantic search
{
  "tool": "mcp__serena-global__find_symbol",
  "name_path": "Button",
  "include_kinds": [5],  # Class symbols only
  "relative_path": "src/components"
}

Refactoring with Confidence

Serena's replace_symbol_body operates at the AST level, ensuring changes don't break syntax:

# Replace entire function implementation
{
  "tool": "mcp__serena-global__replace_symbol_body",
  "name_path": "calculateMetrics",
  "relative_path": "src/utils/analytics.ts",
  "body": "export function calculateMetrics(data: MetricData[]): Metrics {\n  // New optimized implementation\n  return data.reduce((acc, metric) => {\n    // ...\n  }, defaultMetrics);\n}"
}

Understanding Code Relationships

The find_referencing_symbols tool reveals how code connects across files:

# Find all components using a custom hook
{
  "tool": "mcp__serena-global__find_referencing_symbols",
  "name_path": "useTheme",
  "relative_path": "src/hooks/useTheme.ts"
}

This semantic understanding prevents the cascade of errors that plague text-based refactoring.

Benefits and Trade-offs

Benefits We've Experienced

Velocity: Complex migrations that would take weeks were completed in days. The Next.js 15 migration touched every file but was done in 48 hours.

Consistency: Agents never forget coding standards, always follow patterns, and maintain uniform style across thousands of lines.

Comprehensive Testing: Agents excel at systematic work like writing test variations. Our frontmatter validation has 706 tests—thorough beyond what humans would manually write.

Documentation: Every change is documented, every decision recorded. The CLAUDE.md file grows with institutional knowledge automatically.

Trade-offs We've Accepted

Context Management: Agents can lose track in very long conversations. We restart threads for major new features.

Over-Engineering Risk: Agents might create sophisticated solutions where simple ones suffice. Human oversight keeps complexity in check.

Debugging Challenges: When agents make errors, understanding their reasoning requires reading through verbose outputs.

Tool Limitations: MCP tools have quotas and rate limits. Large refactoring must be batched carefully.

Best Practices We've Developed

1. Define Clear Agent Guidelines

Our .claude/CLAUDE.md file is 1,500+ lines of specific instructions. This investment pays dividends in consistency:

## Operating Principles
- autonomy first; deepen only when signals warrant it
- adopt > adapt > invent
- milestones, not timelines
- keep changes reversible
- design for observability from the start

2. Use Semantic Tools First

Always prefer Serena's semantic operations over text manipulation:

find_symbol before grep
replace_symbol_body before sed
get_symbols_overview before cat

3. Parallel Execution for Speed

Launch multiple agents simultaneously for independent work:

# Three agents working on different aspects
Agent 1: Implement core feature
Agent 2: Write comprehensive tests
Agent 3: Update documentation
# Merge results after completion

4. Maintain Human Oversight

Agents excel at execution but need human judgment for:

Architectural decisions
User experience trade-offs
Business priority calls
Aesthetic choices

5. Document Everything

Every agent interaction teaches something. Capture learnings in project documentation for future agents to reference.

Lessons Learned Building This Blog

Migrations Are Perfect for Agents: Systematic changes across many files play to agent strengths. Our five-phase migration had zero regressions.

Tests Enable Fearless Changes: With comprehensive tests, agents can refactor aggressively. Our 735 tests catch issues instantly.

Explicit Instructions Prevent Drift: Vague requirements lead to creative interpretations. Specific acceptance criteria in Linear tickets ensure precise implementation.

Semantic Understanding Matters: Serena MCP's semantic operations prevented countless errors that regex-based tools would have introduced.

Parallel Work Requires Planning: Coordinating multiple agents requires clear boundaries. Overlapping work areas cause conflicts.

Conclusion

Agent-driven development has fundamentally changed how we build software. This blog—built entirely through agent workflows—proves that complex, production-ready applications can emerge from well-orchestrated AI collaboration.

The key isn't replacing developers but amplifying them. We still architect systems, make design decisions, and ensure quality. But we've delegated implementation details to specialized agents that excel in their domains.

As these tools mature, the boundary between human creativity and AI execution will continue to blur. The developers who thrive will be those who learn to conduct this orchestra of artificial intelligence, turning high-level vision into deployed reality through sophisticated agent workflows.

The future of development isn't human or AI—it's human and AI, working together in ways we're only beginning to explore.