Vibe Coding at Scale

Individual vibe coding is straightforward — you write prompts, you review, you ship. At team scale, new challenges emerge:

Challenge 1: Consistency Five developers using AI produce five different coding styles, patterns, and approaches — unless you have shared standards.

Challenge 2: Quality control How do you ensure AI-generated code meets team standards across all PRs?

Challenge 3: Knowledge sharing One developer discovers an effective prompting technique — how does the team benefit?

Challenge 4: Onboarding New team members need to learn both the codebase AND the AI workflow.

Challenge 5: Governance Who's responsible for AI-generated code? What's the review bar?

What team-scale AI looks like without coordination:

Developer A's PR:
  - Uses default exports (their AI's default)
  - Error handling with try/catch + console.error
  - Fetches with axios

Developer B's PR:  
  - Uses named exports
  - Error handling with Result type pattern
  - Fetches with native fetch()

Developer C's PR:
  - Mix of both export styles
  - No error handling (AI forgot)
  - Fetches with a custom wrapper that nobody else knows about

All three PRs "work" — but the codebase becomes inconsistent, harder to navigate, and more expensive to maintain.

What it looks like WITH coordination:

All developers' PRs:
  - Named exports (enforced by CLAUDE.md + linter)
  - AppError class for errors (documented in CLAUDE.md)
  - fetchApi() wrapper from src/lib/api (referenced in CLAUDE.md)
  - Consistent file structure, naming, patterns

The solutions build on familiar software engineering practices — just adapted for AI workflows.

The highest-leverage team investment: shared AI configuration committed to the repository.

A real team CLAUDE.md template:

# Project: Acme Dashboard

## Architecture
- Next.js 14 (app router) — NO pages router patterns
- PostgreSQL via Prisma 5.8 ORM
- Tailwind CSS + shadcn/ui components
- Vitest for testing
- pnpm as package manager

## Directory Structure
src/
  app/           → Pages and layouts (App Router)
  components/    → React components, grouped by feature
  lib/           → Utilities and shared logic
  services/      → Business logic and external API calls
  types/         → Shared TypeScript types
  test/          → Test helpers and fixtures

## Coding Conventions
- Named exports ONLY (no default exports)
- Functional components with hooks (no class components)
- Use our AppError class for all errors (src/lib/errors.ts)
- API responses ALWAYS use { data, error, meta } shape
- Use zod schemas for ALL input validation (src/schemas/)
- Prefer server actions for mutations over API routes

## Existing Utilities (DO NOT REINVENT)
- fetchApi() — src/lib/api.ts (handles auth, retries, errors)
- formatDate() — src/lib/dates.ts (handles timezone)
- validateEmail() — src/lib/validators.ts
- useToast() — src/hooks/useToast.ts (notifications)
- cn() — src/lib/utils.ts (className merging)

## Do NOT
- Add new dependencies without discussing in team channel
- Use default exports
- Use console.log (use our logger from src/lib/logger.ts)
- Generate mock data inline — use factories in src/test/factories/
- Skip error handling on any async operation

## Testing Requirements
- Every new function needs at least one test
- Test files: [name].test.ts next to source file
- Use factories for test data (src/test/factories/)
- Integration tests for all API routes

## PR Template
- Link to the spec/prompt that generated the code
- Confirm you've reviewed all generated code
- Confirm tests pass locally

This file ensures every AI session — regardless of who runs it — starts with the same context and constraints.

Code review doesn't change — but the focus shifts:

What reviewers should focus on for AI-generated code:

1. Does it solve the right problem? (AI may solve a slightly different thing)
2. Does it match our patterns? (AI may generate valid but inconsistent code)
3. Is the API usage correct? (hallucinated APIs are common)
4. Are edge cases handled? (AI often misses boundaries)
5. Does it need this much code? (AI can over-engineer simple tasks)

What reviewers can spend less time on:

• Syntax and formatting (AI rarely makes these errors)
• Typos and naming (usually consistent)
• Standard patterns (AI implements these well)

A team review checklist for AI-generated PRs:

## AI Code Review Checklist

### Correctness
- [ ] Solves the stated problem (not a slightly different one)
- [ ] All API calls use real endpoints (not hallucinated)
- [ ] Version-appropriate patterns (React 18, not 19)
- [ ] Edge cases: null, empty, boundary values handled

### Consistency
- [ ] Uses existing utilities (not reinventing)
- [ ] Matches project naming conventions
- [ ] Error handling uses AppError pattern
- [ ] Imports from correct locations

### Security
- [ ] Authentication checked on protected routes
- [ ] Input validated before processing
- [ ] No secrets or credentials in code
- [ ] SQL injection / XSS prevention present

### Testing
- [ ] Tests exist for new functions
- [ ] Tests cover failure cases, not just happy path
- [ ] No flaky tests (timeouts, race conditions)

Team policy suggestions:

• AI-generated PRs get the same review bar as human PRs
• The PR author is responsible for the code, regardless of what generated it
• Large AI-generated changes should be broken into reviewable chunks
• If a reviewer can't understand a section, it should be simplified

When bringing team members into AI-assisted workflows:

Phase 1: Foundations (Week 1)

• Install the tools
• Show basic usage (ask questions, generate code)
• Walk through the shared rules file
• Pair on a small task together

Phase 2: Guided practice (Weeks 2-3)

• Work on real tasks with AI
• Review each other's AI-generated PRs
• Share effective prompts in team channel
• Identify which tasks each person delegates to AI

Phase 3: Independent (Weeks 4+)

• Full autonomy with AI tools
• Contributing to shared rules file
• Mentoring others on effective patterns
• Reporting issues and improvements

An onboarding checklist you can adapt:

## AI Workflow Onboarding

### Day 1: Setup
- [ ] Install Claude Code / Cursor (team's chosen tool)
- [ ] Read the project CLAUDE.md thoroughly
- [ ] Generate a simple change to verify setup works
- [ ] Review the last 3 AI-generated PRs to see team patterns

### Week 1: Observe & Learn
- [ ] Pair with experienced team member on 2 AI-assisted tasks
- [ ] Practice the prompt-first workflow on a low-risk task
- [ ] Submit first AI-assisted PR (small scope)
- [ ] Get feedback on your prompting approach

### Week 2: Practice
- [ ] Complete 3 tasks using AI independently
- [ ] Practice the "explain then build" pattern
- [ ] Review 2 other team members' AI-generated PRs
- [ ] Share one effective prompt in team channel

### Week 3+: Independent
- [ ] Working at full speed with AI assistance
- [ ] Comfortable deciding when to use AI vs write manually
- [ ] Contributing improvements to CLAUDE.md
- [ ] Helping onboard the next person

Common onboarding mistakes:

• Expecting immediate productivity gains (there's a 1-2 week learning curve)
• Not providing examples of good AI interactions
• Letting people struggle alone (pair prompting is a real thing)
• Forgetting to update shared rules as patterns evolve

How to know if vibe coding is actually helping your team:

Metrics that matter:

Metrics that mislead:

• Lines of code per day (more AI code does not equal better)
• Number of commits (frequency can change without meaning)
• Pure speed without quality context
• "AI usage percentage" (using AI more isn't inherently better)

What a before/after comparison looks like — an illustrative shape, not measured data:

Metric                  Before        After (Month 3)
─────────────────────────────────────────────────────
Avg cycle time          baseline      lower
PRs per developer/week  baseline      higher
Bug tickets per sprint  baseline      roughly flat
Developer satisfaction  baseline      higher
PR size (avg files)     baseline      higher
Code review time        baseline      lower

The shape to look for: developers ship more scope per unit time while the defect rate stays roughly flat. If your defect rate climbs with your throughput, you have not got faster — you have moved the work downstream. Satisfaction tends to rise when tedious work falls, but it is the metric most easily confounded by everything else happening that quarter, so treat it as a signal, not a result.

Measuring approach:

1. Baseline: track metrics for 2-4 weeks before AI adoption
2. Adoption: introduce tools with training (expect a brief dip as people learn)
3. Compare: same metrics 4-6 weeks after adoption
4. Adjust: identify what's working, what isn't, iterate on process