Skip to content
Back to AI Coding

AI-First Development Workflow

Restructure your dev loop around AI: spec, prompt, review, ship, with humans as reviewers.

WorkflowIntermediate

Why

GitHub's 2024 enterprise survey of 2,000 developers found 97% have used AI coding tools at work, and Stack Overflow's 2024 survey found 76% of developers use or plan AI tools (up from 70%). AI-first inverts the traditional loop: AI writes the bulk of the code and humans review diffs instead of writing from scratch.

This 5-10x's throughput on well-specified work, but only if specs are precise, reviews are rigorous, and you catch drift early with types and tests. Without that discipline you ship hallucinated code faster than ever.

When

Adopt AI-first when starting new modules or features with clear acceptance criteria, when your team has review capacity and a strong type system, and the work is in a language AI knows well (TS/Python/Go). Avoid it for security-critical crypto, novel algorithms with no reference implementations, or when reviewers cannot meaningfully evaluate the output.

How

1. Write a spec first (acceptance criteria + constraints). One sentence is not enough. Example: "Add POST /api/books that validates {title, author} via zod, persists to Books table, returns 201 with the created row. Reject empty title. Log failures." 2. Prompt the AI with the spec plus relevant file references: Cursor: @file src/api/router.ts @file src/data/books.ts "implement the spec above" Claude Code: "implement POST /api/books per this spec; follow existing route patterns in src/api/" 3. Review the diff like a PR, not a suggestion. Check: - Does it satisfy every acceptance criterion? - Are there imports that do not resolve? (hallucinated packages) - Does it touch files outside scope? (git diff --stat) 4. Run the gate immediately: npm run check && npm test && npm run build Red means reject and re-prompt with the specific error. Do not hand-fix AI errors. 5. Commit only after green. Use conventional commits so the AI can read history: git commit -m "feat(api): add POST /api/books with zod validation" 6. Loop on failures: paste the exact tsc/test error back to the AI and ask for a fix. Keep the loop tight. Three failed attempts means your spec is ambiguous, rewrite it.

Example

Spec-driven loop in Claude Code: $ claude > Implement a rate limiter middleware per this spec: - Token bucket: 100 req/min per IP, burst of 20 - Store in Redis (key: ratelimit:{ip}) - Return 429 with Retry-After header when exceeded - Follow existing middleware pattern in src/middleware/auth.ts Commit after each step. Claude produces 3 commits: feat(middleware): add token-bucket rate limiter feat(redis): wire rate limiter to redis client test(middleware): add rate limiter unit tests Gate: npm run check && npm test -> green. Ship.

Common Problems

  • ⚠Error: Cannot find module 'xxx' → run `npm install xxx` (or `pnpm add xxx`); verify it is in package.json dependencies.
  • ⚠Error: "Command not found: claude" or "cursor" → ensure the binary is on PATH: `which claude` / `which cursor`; reinstall globally if missing.
  • ⚠TypeError: Cannot read properties of undefined (reading 'x') → add a null guard or optional chaining `obj?.x`; trace the undefined source via the stack.
  • ⚠Hand-fixing AI errors breaks the loop. Always re-prompt with the error so the AI learns the codebase's real constraints.

Best Practices

  • ✓Write specs as acceptance criteria (Given/When/Then), testable by both humans and AI.
  • ✓Keep the AI loop tight: spec, generate, gate, commit. Never hand-edit inside the loop.
  • ✓Maintain a .cursorrules or CLAUDE.md so AI inherits project conventions without re-explaining.
  • ✓Review AI diffs in a real diff viewer with tests green, never in the chat pane.
  • ✓Track AI-authored commit ratio. Above 80% without review pushback means reviews are rubber-stamping.

FAQ

What does 'AI-first development' actually mean?

It means AI generates the bulk of the code from a spec and humans review diffs, rather than humans writing from scratch and AI assisting. The loop is spec, prompt, review, gate, ship — with humans as reviewers, not typists.

When should I NOT use an AI-first workflow?

Avoid it for security-critical crypto, novel algorithms with no reference implementations, or when reviewers can't meaningfully evaluate the output. It shines on well-specified, typed, testable work where the gate catches AI errors.

How do I write a spec the AI can follow?

Write acceptance criteria (Given/When/Then) plus hard constraints (no new deps, named exports, follow pattern in X.ts). One sentence is not enough. The spec is the highest-leverage input — vague specs produce vague code.

Should I hand-fix AI errors during the loop?

No. Paste the exact tsc/test error back to the AI and let it fix. Hand-fixing breaks the loop and hides the codebase's real constraints from the AI. Three failed attempts means the spec is ambiguous — rewrite it.

How do I measure if AI-first is working?

Track AI-authored commit ratio and review pushback rate. If over 80% of commits are AI-authored with zero review pushback, reviews are rubber-stamping. Healthy adoption shows a high gate-pass rate with meaningful human corrections per PR.