AI INTERMEDIATEAI Workflow
A comprehensive workflow for building software with AI assistance, emphasizing planning, incremental development, testing, and maintaining control over your codebase
15 min read
aiworkflowdevelopmentplanningtestinggitbest-practices
Table of Contents
Quick Start Summary
The essence of the AI-assisted development workflow
The Core Workflow
Essential steps for AI-assisted development
📄 Codetext
💡 Planning saves time and produces better results
⚡ Small steps make debugging easier when things break
📌 Manual review is where your expertise matters most
🎯 Frequent commits create safe rollback points
workflowoverview
Typical Time Investment
Expected time commitment for each phase
📄 Codetext
💡 Front-loading planning pays dividends throughout development
⚡ Small steps (10-30 min) keep you focused and productive
📌 Manual review time is non-negotiable for quality
🎯 These timeframes assume AI assistance - would be 2-3x longer manually
planningtime-management
Planning & Context Setup
Establish a solid foundation before writing code
Create Your PLAN.md
Document project goals, features, and technical decisions
📄 Codemarkdown
💡 Break features into specific, testable steps from the start
⚡ This is a living document - update as you learn
📌 Clear goals prevent scope creep and wasted effort
🎯 Tech stack decisions upfront avoid costly rewrites
planningdocumentation
Create Context Files
Provide AI with project-specific guidelines and references
📄 Codemarkdown
💡 Context files guide AI to match your style and preferences
⚡ Include links to docs - AI can fetch and apply them
📌 "What NOT to do" section prevents common mistakes
🎯 Update context when you make architectural decisions
contextdocumentationai-setup
Manual Foundation
Set up the initial boilerplate yourself
Manual Boilerplate Setup
Why and how to set up your project foundation manually
📄 Codebash
💡 Manual setup gives you deep understanding of your foundation
⚡ Framework CLIs are designed for this - use them directly
📌 Mystery foundations lead to mystery bugs later
🎯 This one-time investment pays off throughout the project
setupboilerplatefoundation
AI-Assisted Development Loop
The iterative process for building features with AI
Break Down Features
Decompose features into small, achievable steps
📄 Codetext
💡 Steps should take 20-30 minutes to implement and test
⚡ Small steps make debugging infinitely easier
📌 Review AI-proposed steps - it might miss important details
🎯 Good breakdown is 70% of successful implementation
planningfeature-development
Implement One Step
Work on a single step with clear, detailed instructions
📄 Codetext
💡 Specificity in prompts leads to better code quality
⚡ Reference context files to maintain consistency
📌 One step at a time prevents cascading failures
🎯 Clear constraints guide AI to better solutions
implementationprompting
Test & Verify
Manually test each implementation step
📄 Codetext
💡 Manual testing catches issues AI testing might miss
⚡ Test immediately while the context is fresh
📌 Edge case testing prevents production surprises
🎯 Fix issues now - they compound if left alone
testingquality-assurance
Manual Code Review
Review and improve AI-generated code
📄 Codetext
💡 This step separates quality code from technical debt
⚡ Make manual edits - don't just accept AI output
📌 Security and performance need human judgment
🎯 Your expertise matters most during review
code-reviewquality
Write Tests (When Appropriate)
Add test coverage for features that need it
📄 Codetext
💡 Not every step needs tests, but every feature should have appropriate coverage
⚡ AI can generate test scaffolding - you verify quality
📌 Integration tests provide best ROI for most projects
🎯 Tests are your safety net as the codebase grows
testingquality-assurance
Commit Your Work
Create checkpoints with meaningful commits
📄 Codebash
💡 Small, focused commits make debugging and rollback easy
⚡ Commit after every working step - creates safe checkpoints
📌 Good commit messages are documentation for your future self
🎯 Aim for 5-10 commits per day of active development
gitversion-control
Feature Completion & Review
Final steps when a feature is fully implemented
End-to-End Feature Testing
Test the complete feature flow comprehensively
📄 Codetext
💡 End-to-end testing catches integration issues
⚡ Test on actual devices, not just responsive mode
📌 Error scenarios are just as important as happy paths
🎯 Fresh eyes find bugs you've become blind to
testingquality-assurance
Code Quality Review
Review all code generated for the feature
📄 Codetext
💡 Refactoring improves maintainability for future features
⚡ Look for patterns across multiple files
📌 Ask AI for suggestions, but you make final decisions
🎯 Not every suggestion needs implementation - prioritize
code-reviewrefactoring
Update Documentation
Keep documentation current with changes
📄 Codemarkdown
💡 Update docs while context is fresh in your mind
⚡ Good docs save time for future you and teammates
📌 Document architectural decisions and reasoning
🎯 Comments should explain why, code explains what
documentation
Final Feature Commit
Create a comprehensive commit for the completed feature
📄 Codebash
💡 Comprehensive commit message documents the complete feature
⚡ Tags create clear milestones in your git history
📌 Taking breaks prevents burnout and maintains quality
🎯 Each feature teaches you something - capture those learnings
gitworkflow
Key Principles
Core tenets of effective AI-assisted development
Fundamental Principles
The non-negotiable rules for quality AI-assisted development
📄 Codetext
💡 These principles prevent technical debt accumulation
⚡ Following them makes you faster long-term, not slower
📌 Quality code with AI requires MORE discipline, not less
🎯 You own every line of code in your project
principlesbest-practices
Common Pitfalls to Avoid
Mistakes developers make with AI assistance
Planning & Setup Mistakes
Errors made before coding begins
📄 Codetext
❌ AI without planning is like building without blueprints
❌ Mystery foundations lead to mystery bugs
❌ Stale context wastes time with wrong suggestions
✅ Front-load planning - it pays dividends throughout
pitfallsplanning
Implementation Mistakes
Errors during the development process
📄 Codetext
❌ Large steps → hard debugging → wasted time
❌ Blind trust → technical debt → maintenance nightmares
❌ Code you don't understand is a ticking time bomb
✅ Slow down to speed up - quality compounds
pitfallsimplementation
Testing & Quality Mistakes
Shortcuts that hurt long-term quality
📄 Codetext
❌ Untested commits break build history
❌ No tests → fear of changes → stagnant codebase
❌ Giant commits → impossible to debug or rollback
✅ Test, commit, repeat - creates safety net
pitfallstestinggit
Troubleshooting Common Issues
Solutions to problems you might encounter
AI Keeps Breaking Things
Every change breaks something else
📄 Codetext
💡 Smaller steps = fewer variables when debugging
⚡ Request changes to specific files, not broad features
📌 Verify each change works before asking for next
🎯 "Change just the auth logic in this file"
troubleshooting
Spending Too Much Time Planning
Hours on PLAN.md, no code written
📄 Codetext
💡 Perfect plan doesn't exist - start with good enough
⚡ 30-60 minutes of planning is usually sufficient
📌 You'll learn things during implementation
🎯 Planning and implementing inform each other
troubleshootingplanning
AI Not Following Context
AI keeps using patterns you said not to use
📄 Codetext
💡 AI responds better to explicit "NEVER" and "ALWAYS"
⚡ Provide examples of what you want and don't want
📌 Reference context file in every major prompt
🎯 "Read claude.md" ensures AI loads your preferences
troubleshootingcontext
Don't Understand AI's Code
Looking at generated code and confused
📄 Codetext
💡 Never proceed with code you don't understand
⚡ Ask AI to explain - it's good at that
📌 Request simpler solutions if explanation still unclear
🎯 Understanding the code is not optional
troubleshootingcode-review
Tests Taking Forever
Writing tests is slowing you down significantly
📄 Codetext
💡 Integration tests provide best ROI for most projects
⚡ AI-generated test scaffolding saves time
📌 Not everything needs tests - be pragmatic
🎯 100% coverage is not the goal - confidence is
troubleshootingtesting