Skip to content
Lesson 3 of 12

The AI-First Workflow

7 min read

The Traditional Workflow Is a Bottleneck

Every developer knows the traditional workflow: think about what you want to build, write the code, run it, find bugs, debug, write more code, repeat. This cycle has been the default for decades, and it has a fundamental problem -- you are both the architect and the construction worker. You make the high-level decisions and then spend most of your time on the low-level execution.

The traditional cycle:

Think -> Code -> Run -> Debug -> Code -> Test -> Code -> Commit
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         This part is 80% of your time

The AI-first workflow flips this ratio:

Think -> Describe -> Review -> Adjust -> Verify -> Commit
^^^^     ^^^^^^^     ^^^^^^
This part is 80% of your time (and it should be)

In the AI-first workflow, you spend most of your time on the parts that matter most: defining what you want, reviewing what was built, and making decisions about quality and direction. The mechanical work of writing code, managing imports, handling boilerplate, and fixing syntax errors is handled by AI.

The Five-Step AI-First Cycle

Here is the complete workflow that 5.7x developers use:

Step 1: Define the Outcome Clearly

Before touching any tool, get crystal clear on what you want. Not "add a feature" but "add user preferences with a settings page, API endpoint for GET/PUT, PostgreSQL storage, and a migration." The more precise your outcome definition, the less iteration you need.

Write it down. Seriously. Even a quick note forces clarity:

## Feature: User Preferences
- Settings page at /settings with toggle switches
- API endpoint at /api/preferences (GET, PUT)
- Store in PostgreSQL, new preferences table
- Fields: theme (light/dark), language (en/es), notifications (boolean)
- Migration with rollback support
- Integration tests for the API

Step 2: Let AI Propose the Approach

Instead of jumping into implementation, ask AI to plan first. This catches architectural issues before any code is written:

claude "/plan Add a user preferences system. Settings page at /settings,
       API at /api/preferences with GET/PUT, PostgreSQL storage with a
       new preferences table. Fields: theme, language, notifications.
       Include migration and tests."

Review the plan. Does the file structure make sense? Are the naming conventions consistent with your project? Is the approach to database access aligned with your existing patterns? This is where your expertise matters most -- not in writing the code, but in evaluating the architecture.

Step 3: Review and Adjust

After reviewing the plan, provide feedback before execution begins:

  • "Use the existing database connection pool, do not create a new one"
  • "Follow the same pattern as the /api/users endpoint"
  • "Add rate limiting to the PUT endpoint"
  • "Use zod for input validation, matching our existing schema patterns"

This adjustment step is critical. It is where your domain knowledge and project-specific context shape the implementation. AI can write excellent code, but it needs your guidance on project conventions and business requirements.

Step 4: Let AI Execute

Once the plan is approved and adjusted, let AI handle the full implementation. This is the step where most developers struggle -- they want to intervene, to write some of the code themselves, to maintain a sense of control. Resist this urge.

claude "Execute the plan. Create all files, run the migration, and verify
       the tests pass."

While AI executes, you can review the output as it streams. Watch for:

  • Files being created in the right locations
  • Import patterns matching your conventions
  • Test structure following your project standards

But do not interrupt unless something is clearly wrong at an architectural level. Small style issues can be fixed in the next iteration.

Step 5: Verify Results

After execution, verify the results:

# Run the tests AI created
npm test -- --filter preferences

# Check the migration
npx prisma migrate status

# Start the dev server and test manually
npm run dev

If everything works, commit. If adjustments are needed, describe them clearly and go back to Step 3. Each iteration gets closer to the final result without you writing a single line of code manually.

The "Describe, Don't Code" Principle

The core principle of AI-first development is deceptively simple: describe what you want instead of writing it yourself. But "describe" is doing a lot of work in that sentence. Good descriptions are:

Specific about outcomes:

Bad:  "Add dark mode"
Good: "Add dark/light mode with next-themes, Tailwind dark: variant,
       ThemeProvider wrapping root layout, toggle in navbar, slate-900
       dark backgrounds, localStorage persistence, system preference default"

Clear about constraints:

Bad:  "Make the API fast"
Good: "Add Redis caching to the /api/products endpoint with 5-minute TTL,
       cache invalidation on product updates, and fallback to database
       if Redis is unavailable"

Explicit about patterns to follow:

Bad:  "Create a new page"
Good: "Create a new page at /dashboard following the same layout pattern
       as /settings — server component, metadata export, breadcrumb
       navigation, and responsive grid"

The investment in writing a clear description pays for itself immediately. A 60-second description saves 60 minutes of implementation and iteration.

Real Example: Dark Mode in One Session

Here is how the AI-first workflow played out for a real dark mode implementation across a production site:

1. Define outcome: "Full dark/light mode across all 19 component files,
   with system preference detection and manual toggle"

2. Describe to AI: Full specification including next-themes, Tailwind
   dark: variant, color palette, persistence strategy

3. AI proposes: Plan touching 19 files — ThemeProvider, layout wrapper,
   toggle component, and dark: variants for every component

4. Review: Adjusted color choices for better contrast, requested
   slate-900 instead of gray-900

5. Execute: AI implements across all 19 files in one pass

6. Verify: Test in browser, check light/dark/system modes

7. Result: Complete dark mode implementation in 25 minutes.
   Manual approach estimate: 3-4 hours.

Real Example: Three Courses in One Session

Content creation follows the same workflow:

1. Define outcome: "3 new courses with full lesson content,
   bilingual EN/ES, proper frontmatter, and MDX formatting"

2. Describe: Course outlines, lesson topics, content depth,
   formatting requirements, translation approach

3. AI proposes: File structure, lesson ordering, tag taxonomy

4. Review: Adjusted lesson titles, reordered topics for
   better learning progression

5. Execute: AI creates 38 lesson files with full content

6. Verify: Check frontmatter, content quality, translations

7. Result: 3 complete courses in one session.
   Manual approach: 2-3 weeks.

Working in Natural Language First

A subtle but important shift: start thinking about your work in natural language before you think about code. When you get a new requirement, your first instinct should not be "which files do I need to change?" but rather "what is the outcome I need to describe?"

This changes how you approach problems:

  • Old approach: "I need to modify the User model, add a migration, update the API route handler, change the frontend form, and add validation."
  • New approach: "Users need to be able to set a display name. It should appear in the navbar and on their profile. Validate that it is 2-50 characters, alphanumeric with spaces."

The second description is shorter, clearer, and gives AI everything it needs to make the right implementation decisions. You are working at the level of user value, not implementation mechanics.

The Iteration Speed Advantage

The AI-first workflow is not just faster at initial implementation. It is dramatically faster at iteration. When you need to change something, you describe the change:

claude "The preferences page needs a reset button that restores all
       settings to their defaults. Add it below the save button,
       with a confirmation dialog before resetting."

AI makes the change across all relevant files in seconds. In a manual workflow, this "small" change might touch the UI component, the API endpoint, the database defaults, and the tests. Each file change requires context switching and careful coordination. In the AI-first workflow, it is one description and one execution cycle.

This iteration speed compounds. Over a day of development, the difference between 5-minute iterations and 45-minute iterations is the difference between 12 refinement cycles and 1 or 2. And more iterations means better final quality.