Real-World AI Coding Workflows

Workflow 1: Feature Development (Test-Driven)

The complete flow from idea to merged PR.

Setup: The Feature Skill

.claude/skills/new-feature/SKILL.md:

---
title: "New Feature"
description: "Build a new feature end-to-end with TDD"
---

# New Feature: $ARGUMENTS

## Phase 1 — Explore (do NOT edit yet)
Read these before writing any code:
- Find existing similar features in `src/` to understand patterns
- Read relevant test files in `tests/`
- Read CLAUDE.md for conventions

## Phase 2 — Plan
Describe what you'll build and which files you'll create/modify.
Wait for user approval before proceeding.

## Phase 3 — Test first
Write failing tests in `tests/` before implementing.
Run them to confirm they fail as expected.

## Phase 4 — Implement
Write code to make the tests pass.
Run: `npm test` after each logical step.

## Phase 5 — Polish
- Run: `npm run lint` — fix all issues
- Run: `npm test` — all tests must pass
- Check for missing edge cases

## Phase 6 — Commit
- `git add -A`
- `git commit -m "feat: $ARGUMENTS"`

Usage

claude
> /new-feature add-stripe-subscription-webhook

Claude explores, presents a plan, you approve, then it implements.

---

Workflow 2: Bug Fix

Fast Path (you know the file)

claude -p "There's a bug in src/services/payment.ts — charge is applied twice
when the user retries. Fix it and add a regression test."

Investigative Path (you don’t know where)

claude
> Users are getting duplicate charge emails. Find the bug and fix it.

Claude will:

1. Search for email-sending code
2. Read payment processing logic
3. Check for missing idempotency guards
4. Fix and add a regression test

The Hotfix Skill

.claude/skills/hotfix/SKILL.md:

---
title: "Hotfix"
description: "Emergency production fix — bypasses normal workflow"
require-approval: true
---

# Hotfix: $ARGUMENTS

1. Confirm on main: `git branch --show-current`
2. Pull latest: `git pull origin main`
3. Create branch: `git checkout -b hotfix/$ARGUMENTS`
4. Investigate and fix: $ARGUMENTS
5. Run critical tests: `npm run test:critical`
6. Commit: `git commit -m "hotfix: $ARGUMENTS"`
7. Push and open urgent PR: `gh pr create --label urgent --title "hotfix: $ARGUMENTS"`

---

Workflow 3: Code Review

Review your own changes

git diff main | claude -p "review for bugs and security issues"

Or use the built-in skill:

/code-review --effort high

Review a PR

/review 247          # review PR #247 on GitHub

Or with the GitHub MCP server:

claude mcp add --transport http github https://api.github.com/mcp
/mcp    # authenticate
> Review PR #247, focus on security and edge cases

Automated Review in CI

.github/workflows/claude-review.yml:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash

      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git diff origin/main...HEAD | claude -p \
            "Review these changes for bugs and security issues.
             Post findings as a GitHub PR comment using gh pr comment." \
            --permissions acceptEdits \
            --output-format md

---

Workflow 4: Refactoring

Step 1: Explore in plan mode first

claude --permissions plan
> Analyze src/api/ — identify all places where error handling is inconsistent.
> Don't change anything yet, just map out the problem.

Step 2: Approve the plan, then execute

> Now apply a consistent AppError pattern across all the files you identified.
> Do it one file at a time and run tests after each file.

Step 3: Verify

npm test
git diff | claude -p "verify the refactor is consistent and nothing was missed"

Refactor Skill Example

.claude/skills/refactor/SKILL.md:

---
title: "Refactor"
description: "Safely refactor code with test-verified steps"
---

# Refactor: $ARGUMENTS

## Rules
- Never break existing tests
- Never change behavior — only structure
- Commit after each logical unit of change
- Run tests between each commit

## Steps
1. Explore the code to be refactored (read-only first)
2. Identify all call sites that will be affected
3. Write tests for any untested code before refactoring it
4. Apply the refactor in small, testable chunks:
   - Change one thing
   - Run: `npm test`
   - Commit if green
5. Final check: `git diff main -- . | grep -c "^+"` (count added lines — should be minimal)

---

Workflow 5: Writing Tests for Existing Code

Use the test-writer agent or do it directly:

claude -p "Write comprehensive tests for src/services/billing.ts.
Cover happy paths, edge cases, and error scenarios.
Use the same test style as tests/services/user.test.ts."

Or use the dedicated agent:

@test-writer write tests for src/services/billing.ts

---

Workflow 6: Documentation

# Generate inline JSDoc
claude -p "Add JSDoc comments to all exported functions in src/utils/.
Match the existing style in src/utils/format.ts."

# Generate a README section
claude -p "Write a Getting Started section for README.md.
Cover: installation, running locally, running tests, deploying to staging."

# Generate API docs
claude -p "Read all route handlers in src/handlers/ and generate
an OpenAPI 3.0 spec in docs/openapi.yaml."

---

Workflow 7: Dependency Upgrades

claude
> Check for outdated dependencies: `npm outdated`
> Upgrade each one individually, running tests after each upgrade.
> Skip major version bumps unless there's a clear benefit.
> Document any breaking changes you encounter.

---

Workflow 8: Debugging Production Issues

# Paste the error and ask for analysis
cat error.log | claude -p "
This error appeared in production.
Find the root cause and fix it.
The stack trace mentions stripe-service — start there."

# Or investigate live
claude
> Production is throwing 500 errors on /api/payments/confirm
> Error: 'Cannot read property stripe_id of undefined'
> Find and fix the bug

---

Workflow 9: Database Migration

claude
> Add a `subscription_tier` column (enum: free, pro, enterprise, default: free)
> to the users table.
> Follow the migration rules in .claude/rules/migrations.md.
> Update the Prisma schema, generate the migration, and update any affected queries.

---

Workflow 10: CI/CD Setup

claude -p "Set up GitHub Actions CI for this project.
Create a workflow that:
1. Runs on every push and PR
2. Installs dependencies
3. Runs lint
4. Runs tests with coverage
5. Fails if coverage drops below 80%
Use the Node.js version from .nvmrc."

---

Chaining Workflows Together

For bigger releases:

claude
> I need to ship the new billing feature.
> Here's what's already been implemented in the billing-feature branch.
>
> Please:
> 1. Review all changes vs main for bugs and security issues
> 2. Fill in any missing tests (coverage must be >80%)
> 3. Update CHANGELOG.md with the new features
> 4. Open a PR with a complete description

Claude will coordinate the review, test-writing, docs, and PR automatically — using your configured agents and skills.

🧠 Quick Recall

• Trick: every workflow is the same GAV loop wearing different clothes.

👨‍🏫 Teach It

• Show: pick the 2 workflows closest to your team’s daily work; run them live.
• They’ll trip on: memorizing all 10 — teach the pattern, not the list.

---

Learning path: ⬅ 10-plan-mode-and-thinking.md · Index · ➡ 12-settings-system.md