AI Coding Workflow: 5-Phase Process for Clean Sessions and Quality Output
I kept getting confused in long AI coding sessions. The AI would forget what we discussed earlier, suggest approaches we already rejected, or make changes that conflicted with previous decisions. I thought I just needed a smarter AI. Then I realized: my workflow was the problem.
The Problem: One Long Polluted Session
I used to do everything in one continuous conversation:
- Discuss requirements with the AI
- Plan the architecture
- Write the code
- Debug issues
- Review everything
By step 3, the context was already polluted with abandoned ideas, rejected approaches, and tangential discussions. By step 5, the AI had “forgotten” key constraints from step 1.
The solution isn’t a better AI model—it’s a better workflow.
The 5-Phase Workflow
┌─────────────────────────────────────────────────────────────────┐│ AI CODING WORKFLOW │├─────────────────────────────────────────────────────────────────┤│ ││ Phase A: Requirements → Task Brief ││ ┌──────────────────┐ ││ │ Main Session │ → Output: tasks/TASK-xxx.md ││ │ (Discuss only) │ Goal, Scope, Acceptance Criteria ││ └──────────────────┘ ││ │ ││ ▼ ││ Phase B: Planning → Plan File ││ ┌──────────────────┐ ││ │ NEW SESSION │ → Output: Plan with affected files ││ │ (Read-only) │ Steps, Risks, Verification ││ └──────────────────┘ ││ │ ││ ▼ ││ Phase C: Implementation ││ ┌──────────────────┐ ││ │ FRESH SESSION │ → Execute plan, run tests, iterate ││ │ (For large tasks) │ Minimal diff, no scope creep ││ └──────────────────┘ ││ │ ││ ▼ ││ Phase D: Monitor Decay ││ ┌──────────────────┐ ││ │ Watch for: │ → When detected: write handoff ││ │ - Repetition │ Restart fresh session ││ │ - Amnesia │ ││ │ - Scope creep │ ││ └──────────────────┘ ││ │ ││ ▼ ││ Phase E: Self-Review ││ ┌──────────────────┐ ││ │ Current session │ → Check scope, tests, architecture ││ │ (No restart) │ must-fix / should-fix / defer ││ └──────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘Phase A: Requirements → Task Brief
Purpose: Understand what to build, not how to build it.
I used to jump straight into discussing implementation details. Now I force myself to write a task brief first—a markdown file that captures the goal, scope, and acceptance criteria.
## GoalAdd email/password authentication for new users
## Scope- POST /auth/register endpoint- POST /auth/login endpoint- Password hashing with bcrypt- JWT token generation
## Constraints- Use existing MongoDB connection- No changes to existing user schema- Preserve current rate limiting
## Non-goals- NO migration of existing users- NO social login (future task)- NO 2FA implementation
## Acceptance Criteria- Users can register with email/password- Users can login and receive JWT- Passwords are hashed, not stored plain- Rate limiting applies to auth endpoints
## Verification- `npm test` - all tests pass- `npm run typecheck` - no type errors- Manual: register, login, verify token
## Risks- Existing user collection may have unhashed passwords (unlikely)- JWT secret must be added to environment
## Unknowns- Should we send confirmation emails? (out of scope for now)Exit condition: Task brief is complete. No code has been written yet.
I tried skipping this step once. The AI and I spent 30 minutes discussing whether to use bcrypt or argon2, only to realize later that the project already had bcrypt as a dependency. The task brief would have captured that constraint upfront.
Phase B: Planning (New Session)
Purpose: Determine how to build it. Still no implementation.
This is crucial: start a new session for planning. Why? Because the requirements discussion context is now “polluted” with back-and-forth that’s no longer relevant. Planning needs a clean slate focused on architecture and files.
In this phase, I ask the AI to:
- Read the task brief
- Read the architecture docs
- Identify affected files
- List risks
- Create a minimal plan
Do NOT implement yet. This is read-only analysis.
# Phase B Output: Implementation Plan
## Affected Files- src/routes/auth.ts (new) - auth endpoints- src/middleware/auth.ts (modify) - add JWT verification- src/services/auth.service.ts (new) - auth logic
## Risks- JWT verification might conflict with existing middleware
## Minimal Plan1. Create src/services/auth.service.ts with register/login logic2. Create src/routes/auth.ts with POST endpoints3. Modify src/middleware/auth.ts to verify JWT4. Add tests for auth.service and routes5. Run npm test, fix failures
## Verification Steps- npm test- npm run typecheck- curl test: register, login, access protected routeI tried doing planning and implementation in the same session. The AI kept wanting to refactor related code it found, even though the task brief explicitly said “minimal diff, no unrelated changes.” A fresh session with just the plan file kept it focused.
Phase C: Implementation (Fresh Session for Large Tasks)
Purpose: Execute the plan.
For large projects, I start yet another fresh session. Here’s why:
Planning context ≠ Implementation context
- Planning needs breadth: exploring many files, considering multiple approaches
- Implementation needs depth: focused changes, running tests, viewing error messages
When the AI has both contexts, it gets confused. It tries to apply planning-time analysis to implementation-time debugging, which doesn’t work.
# Fresh session for implementation# Input: Only the plan file (and any docs it references)
# The AI reads the plan, then:# 1. Opens the first file to modify# 2. Makes the change# 3. Runs tests# 4. Iterates on failuresThe key constraint: minimal diff, no scope creep. The plan already decided what to do. Now it’s just execution.
Phase D: Monitor Decay
Throughout implementation, I watch for decay signals:
| Signal | Example |
|---|---|
| Repetition | ”As I mentioned earlier…” (but it’s the 3rd time) |
| Amnesia | Suggesting an approach already rejected |
| Verbosity | Over-explaining simple concepts |
| Scope creep | ”While we’re here, we could also…” |
| Fix loops | Fixing one thing, breaking another, fixing that, breaking the first |
When I see these signals, I stop immediately and write a handoff file:
# Handoff File (Phase D)
## Current Status- Task: Add authentication- Progress: 80% - endpoints work, tests failing
## Files Changed- src/routes/auth.ts - new file, POST /register and /login- src/middleware/auth.ts - added JWT verify function- src/services/auth.service.ts - register/login logic
## Commands Run- npm test → 2 failures in auth middleware tests- npm run typecheck → passed
## Passing Checks- TypeScript compilation- Auth service tests- Manual curl tests
## Failing Checks- middleware/auth.test.ts - JWT verify mock not working
## Unresolved Issues- Test mock for JWT verification fails on line 47
## Exact Next StepFix JWT mock in middleware test - see test file comments
## What NOT to Revisit- Already tried reinstalling dependencies- Don't change JWT library- Don't refactor auth service (it works)Then I start a fresh session with this handoff file. The new session doesn’t need to know about the requirements discussion or the architecture analysis—it just needs to fix one specific test issue.
I learned this the hard way. I once pushed through decay signals and spent an hour watching the AI make progressively worse suggestions. The handoff file would have saved me 50 minutes.
Phase E: Self-Review
Before finishing any session, I ask the AI to review its own work:
- Scope creep: Did it make changes beyond the plan?
- Unintended changes: Did it modify unrelated files?
- Missing tests: Are there new functions without tests?
- Architecture violations: Did it break patterns?
The review happens in the current session, not a fresh one. The context of what was changed is valuable here.
┌─────────────────────────────────────────────────────────────┐│ SELF-REVIEW CHECKLIST │├─────────────────────────────────────────────────────────────┤│ ││ [ ] No scope creep - changes match plan ││ [ ] No unintended file modifications ││ [ ] All new code has tests ││ [ ] Architecture patterns preserved ││ [ ] No console.log or debug code left ││ [ ] No hardcoded secrets or values ││ ││ Output: ││ - MUST FIX: [critical issues] ││ - SHOULD FIX: [important issues] ││ - SAFE TO DEFER: [minor issues] ││ │└─────────────────────────────────────────────────────────────┘Common Mistakes I Made
-
Everything in one session: Requirements, planning, implementation all together. By implementation time, context was garbage.
-
No task brief: Relying on conversation memory. The AI forgot half the constraints by the time it wrote code.
-
Implementing during planning: The plan became half-baked because the AI got distracted by implementation details.
-
Pushing through decay: Continuing when the AI was clearly confused. Wasted hours on fix loops.
-
Restarting before review: Starting fresh for review and losing the implementation context. The AI couldn’t remember what it just did.
Why This Works
Separation of concerns: Requirements, planning, and implementation are fundamentally different activities. They shouldn’t share context.
Written artifacts: Task briefs, plan files, and handoff files persist. Conversation memory doesn’t.
Fresh starts: Each phase gets a clean context focused on just that phase’s needs.
Decay detection: Stopping early prevents cascading errors.
I used to think “better AI” meant smarter models. Now I know better AI means better workflows. The 5-phase approach has cut my debugging time in half and nearly eliminated “why did you do it that way?” moments.
Related Knowledge
- Context window management: Understanding how AI uses context helps explain why session boundaries matter
- Task decomposition: Breaking work into phases is a standard software engineering practice
- Documentation-first: Writing before coding forces clarity
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments