A Repeatable Workflow for AI-Agent-Driven Development

Why Most AI Coding Sessions Are Improvised (And Why That's a Problem)

Most developers use AI coding agents reactively: they hit a problem, ask the agent, try the suggestion, course-correct, repeat. This ad-hoc approach works for simple tasks but breaks down for complex features — the agent loses the thread, architectural drift accumulates, and the session ends with code that works but doesn't fit the codebase.

A repeatable workflow changes this. By structuring how you engage with AI agents — from task decomposition through verification and context capture — you get consistent quality output that fits your architecture, session after session.

This guide walks through a proven 5-phase workflow that works for Claude Code, Cursor, and Cline.

Phase 1: Session Start — Brief the Agent (5 minutes)

Every productive AI coding session starts with an explicit briefing, not just a task description.

Step 1.1: Ensure CLAUDE.md is current

Before starting, confirm your CLAUDE.md reflects the current state of the project. A 30-second check: when did you last update it? If it's been more than a week during active development, it may be stale.

Step 1.2: Load context explicitly

Start with a structured opening message — don't assume the agent has the right context even with CLAUDE.md in place:

Read CLAUDE.md.

Today's session context:
- We completed the Auth0 integration last session (auth.ts, middleware.ts — committed)
- Currently: implementing the user profile API endpoint
- Today's task: GET /api/user/profile — returns current user's data + subscription status

Constraints:
- Must use getSession() from @auth0/nextjs-auth0
- Use prisma from @/lib/prisma
- Return format: { data: UserProfile } or { error: string } with HTTP status
- Need tests: happy path + unauthenticated case

Verify you understand before starting.

The "Verify you understand before starting" prompt catches context gaps before they become implementation mistakes.

Step 1.3: Confirm the agent's understanding

If the agent's summary is wrong or incomplete, correct it before any code is written. This is the cheapest point to fix misunderstandings.

Phase 2: Task Decomposition (10 minutes)

Large tasks fail more often than small tasks. The agent loses context partway through, makes inconsistent decisions, or implements parts that don't fit together.

The principle: decompose before implementing. Break the feature into tasks small enough that each can be verified in isolation.

Good task decomposition example — User Profile Endpoint:

1. Define the TypeScript types for UserProfile
2. Write the Prisma query to fetch user + subscription data
3. Implement the route handler with auth check
4. Write tests: happy path + unauthenticated case
5. Add the endpoint to API documentation

Bad task decomposition (too large): "Implement the user profile endpoint with auth, database query, and tests."

Smaller tasks produce better code because:

• Each task fits cleanly in the context window
• Errors are caught at each step rather than discovered after everything is built
• The agent can focus its full reasoning on one thing at a time

Ask the agent to propose a decomposition before implementing: "Break this feature into 5–7 concrete tasks. List them before starting."

Phase 3: Implementation — One Task at a Time with Verification

Implement tasks sequentially, verifying after each one. Never let the agent move to the next task until the current one is confirmed correct.

The verification step: After each task, run:

1. Type check: npm run typecheck (or tsc --noEmit)
2. Tests: npm run test (at least the tests related to the task)
3. Manual check: does the code look right? Does it follow your patterns?

If verification fails, correct before proceeding. Don't let errors accumulate across tasks.

Handling errors effectively:

When something breaks, give the agent the full error context:

Running the test gave this error:

[paste full error output]

The test expects:
[paste test code]

The implementation is:
[paste implementation code]

What's wrong and how do we fix it?

The agent debugs much more effectively with the full error, test, and implementation context than with a description of the problem.

Pattern: implement, verify, commit

After each verified task, commit. This creates a clean history that makes rolling back easy if later tasks go wrong:

git add apps/api/src/user/types.ts
git commit -m "feat: add UserProfile type definition"

Small commits are underrated in AI-assisted development. They turn a complex multi-hour session into a series of safe steps.

Phase 4: Testing — Write Tests Alongside Code

AI agents are excellent at writing tests when given clear specifications. The workflow:

4.1: Write the test file first (or ask the agent to)

For each new function or endpoint, create the test file before or alongside the implementation:

Write the test file for the GET /api/user/profile endpoint.

Test cases to cover:
1. Authenticated user with active subscription — returns UserProfile with subscription
2. Authenticated user with no subscription — returns UserProfile with null subscription
3. Unauthenticated request — returns 401

Use Vitest. Mock: getSession (from @auth0/nextjs-auth0), prisma.user.findUnique.

4.2: Confirm tests actually pass

Run npm run test after the agent writes tests. Don't assume tests are correct just because they compile. Watch for:

• Tests that test the mock, not the implementation
• Assertions that are too loose (checking that a field exists but not its value)
• Missing edge cases

4.3: Check test coverage

For critical paths: npm run test:coverage. Aim for 80%+ coverage on new code — AI agents sometimes miss error branches.

Phase 5: Session End — Capture and Close

The most commonly skipped phase — and the one that determines the quality of your next session.

5.1: Capture decisions made this session

Ask the agent to summarize decisions before closing:

Before we close: list all architectural decisions or patterns we established in this session.
Format as: "Decided to X because Y. Rejected Z."

Review the list. Add any decisions not mentioned. These go into CLAUDE.md.

5.2: Update CLAUDE.md

Add new decisions to CLAUDE.md. Remove or update anything that was superseded. Commit:

git add CLAUDE.md
git commit -m "docs: update CLAUDE.md with user profile API decisions"

5.3: Write a state brief for the next session

One paragraph, for yourself and the agent:

Completed: GET /api/user/profile (committed as 3 commits — see git log).
In progress: nothing.
Next: POST /api/user/profile/update — update display name and preferences.
Blockers: none.

Paste this at the start of the next session alongside "Read CLAUDE.md."

Adapting the Workflow to Session Length

Short session (30–60 minutes): Skip the formal decomposition. Still brief the agent and capture decisions at the end. For one-task sessions, the overhead is mainly the opening and closing structure.

Long session (4+ hours): Use /compact after 2 hours to compress conversation history and reset the attention baseline. Use /clear between major features. Run a mini-capture at the end of each major feature rather than waiting for session close.

Multi-session feature: At the start of sessions 2+, the state brief from the previous session is the first message. The agent recovers context in seconds rather than minutes.

Common Mistakes in AI Coding Workflows

Mistake 1: Giving the agent a vague task. "Make the user profile work" → the agent invents requirements. "Implement GET /api/user/profile returning UserProfile type with auth check" → agent builds exactly what you need.

Mistake 2: Not verifying after each task. Errors in step 2 become much harder to find when you're in step 6. Type check and test after every task, not at the end.

Mistake 3: Skipping the session close. The 10 minutes spent updating CLAUDE.md and writing a state brief saves 20 minutes at the start of the next session. The math is clear; the habit is hard.

Mistake 4: Letting the agent choose the implementation approach. For decisions that matter architecturally — error handling, data access patterns, auth approach — specify them explicitly. Don't let the agent default to whatever's common in its training data.

Key Takeaways

• Brief → Decompose → Implement (one task with verification) → Test → Capture: the 5-phase workflow
• Start every session with an explicit briefing message that loads context and specifies constraints
• Decompose features into 5–7 small tasks before implementing any of them
• Verify after every task: typecheck + relevant tests + visual review
• Give the agent full error context when debugging: full error, test code, implementation code
• Commit after each verified task — creates rollback points and a clean history
• Close every session with decision capture and a state brief for next time

Related: What Is Vibe Coding (and How to Do It Well) · Spec-Driven Development with AI Agents · How to Persist Architectural Decisions Across AI Sessions