The Types Landed, but Nothing Got Safer — Where I Delegated a JS→TS Migration to Claude Code, and Where I Didn't

What was genuinely faster to delegate

Now the line itself. Three kinds of work were clearly faster in Claude Code's hands.

Mechanical syntax replacement. module.exports to export, resolving require, lifting JSDoc into annotations. Almost no judgment involved, and reviewing means skimming a diff. I handed these over a directory at a time rather than file by file.

Types that are inferable from the implementation. Pure internal functions, constant objects, reducer return values. When reading the code pins the type down to exactly one answer, delegation was both faster and more accurate than my own typing.

Classifying the error wall. Paste the output of tsc --noEmit and ask for a grouping, and 300 lines collapse into eight root causes. This was the single most useful pattern for me. The hour normally spent staring at an error dump simply vanishes.

# Group errors by cause before touching anything
npx tsc --noEmit 2>&1 | tee /tmp/tsc-errors.txt
claude -p "$(cat /tmp/tsc-errors.txt)
 
Group these errors by root cause and order the groups by number of affected files.
For each group, judge whether the fix is purely a type change or requires an
implementation change. Do not write code yet." \
  --allowed-tools "Read,Grep" \
  --output-format text

Restricting --allowed-tools to reads keeps the investigation phase honest. If edits start while you're still classifying, the evidence moves underneath you. Separating survey from execution means you can walk back.

What I refused to delegate

Four decisions broke quietly when I handed them over. They are the origin story of that first crash.

Types at external boundaries. API responses, environment variables, file reads, user input. The type system cannot know what arrives at runtime, and as is where the lie enters. Claude Code will happily write the assertion — but only because I told it a lie was acceptable.

Deciding where any is allowed. "Just here is fine" weighs cost against risk. I kept that on the human side.

How to wrap untyped dependencies. Pass it through, write a thin wrapper, or drop the dependency entirely? That decision concerns the lifespan of the project, and it rarely matches the shortest path to silencing today's error.

Who suffers when it breaks. Anywhere a swallowed type error shows up as a billing amount, trading speed for care is worth it.

For boundaries, I replaced assertion with verification.

// src/lib/api-client.ts
import { z } from "zod";
 
const ApiResponseSchema = z.object({
  id: z.string(),
  title: z.string(),
  publishedAt: z.string().datetime(),
  tags: z.array(z.string()).default([]),
});
 
export type ApiResponse = z.infer<typeof ApiResponseSchema>;
 
export async function fetchArticle(id: string): Promise<ApiResponse> {
  const res = await fetch(`https://example.com/api/articles/${id}`);
  if (!res.ok) {
    throw new Error(`fetchArticle failed: ${res.status}`);
  }
  // parse, not as. The type is the *result* of a check, not a declaration.
  return ApiResponseSchema.parse(await res.json());
}

as ApiResponse says "let's pretend." parse says "stop if it isn't so." The typing effort is nearly identical; the failure mode is not. I had about 20 boundaries, and converting them took half a day. No crash of that shape has returned since.

I also like deriving the type from z.infer. Schema and type stay single-sourced, so there's no chance of fixing one and quietly diverging from the other.

Put a ratchet in CI so it can't slide back

A line you decide but don't enforce erodes. Mine did — mid-migration I let one as through because I was in a hurry.

So I made regression itself the thing CI blocks. Not "demand 100%," but "refuse to go down."

#!/usr/bin/env bash
# scripts/type-coverage-gate.sh — reject type-coverage regressions per PR
set -euo pipefail
 
BASELINE_FILE=".type-coverage-baseline"
TOLERANCE="0.10"   # percentage points of noise to absorb
 
CURRENT=$(npx type-coverage --strict 2>/dev/null \
  | grep -oE '[0-9]+\.[0-9]+%' | tr -d '%')
 
if [ ! -f "$BASELINE_FILE" ]; then
  echo "$CURRENT" > "$BASELINE_FILE"
  echo "baseline initialized at ${CURRENT}%"
  exit 0
fi
 
BASELINE=$(cat "$BASELINE_FILE")
 
# Regression check (tolerance allowed)
if awk -v c="$CURRENT" -v b="$BASELINE" -v t="$TOLERANCE" \
     'BEGIN { exit !(c < b - t) }'; then
  echo "Type coverage regressed: ${BASELINE}% -> ${CURRENT}%"
  echo "New any locations:"
  npx type-coverage --detail --strict 2>/dev/null | grep -E ':[0-9]+:[0-9]+' | head -20
  echo ""
  echo "If this is intentional, update .type-coverage-baseline with a reason."
  exit 1
fi
 
# Ratchet: lock in any improvement
if awk -v c="$CURRENT" -v b="$BASELINE" 'BEGIN { exit !(c > b) }'; then
  echo "$CURRENT" > "$BASELINE_FILE"
  echo "baseline raised: ${BASELINE}% -> ${CURRENT}%"
fi
 
echo "Type coverage: ${CURRENT}% (baseline ${BASELINE}%)"

The ratchet at the end is the whole point. Every gain locks itself in, so no one maintains a target number by hand, and the quiet weeks where migration stalls still hold the line.

On GitHub Actions:

# .github/workflows/type-coverage.yml
name: type-coverage
on: [pull_request]
 
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"
      - run: npm ci
      - run: bash scripts/type-coverage-gate.sh
      # Commit the baseline when it moves, so the change leaves a trace
      - name: commit baseline
        if: success()
        run: |
          if ! git diff --quiet .type-coverage-baseline; then
            git config user.name "github-actions"
            git config user.email "actions@github.com"
            git add .type-coverage-baseline
            git commit -m "chore: raise type-coverage baseline"
            git push
          fi

When I do grant an exception, the reason goes in the commit message that lowers the baseline. Six months later, git log explains it to me. A gate isn't a wall built to stop you — it's a device for recording why you went through.

Split the work along boundaries, not directories

Early on I asked for whole directories: "convert this to TypeScript." Some days it worked. Other days a pile of as came back. The results wouldn't settle.

The reason was plain enough. I was slicing by the implementation's convenience — the directory — instead of the type system's — the boundary.

So I re-cut it.

Once a human fixes the boundary schema up front, the delegated side has nowhere to put a lie. The type is already pinned upstream, so downstream can only infer. Placing the constraint first finished faster than granting freedom.

This generalizes beyond migrations. If you run work in parallel with worktrees, aligning the split with boundaries makes the eventual merge far less painful.

What was left three months later

Type coverage went from 94.5% to 99.2%. The remaining 0.8% lives inside wrappers around untyped dependencies, each marked with // type-coverage:ignore-next-line and a one-line reason.

The number matters less than the gate quietly running. On a rushed day, reaching for as stops CI, and I get one forced pause. The judgment no longer has to be made every time — it moved into the machinery.

My original mistake wasn't delegating too much to Claude Code. It was that I couldn't put into words what I was delegating. Move fast with a fuzzy boundary and you break fast.

If you're starting today, run npx type-coverage --detail --strict once. The codebases most confident they've finished migrating are the ones with the longest output. That number is the first material you have for redrawing the line.

Thanks for reading — I hope some of this proves useful in your own migration.