AI Workflow

WORKFLOW OVERVIEW:

1. Plan first - Create PLAN.md and claude.md before writing any code
2. Manual foundation - Set up your project boilerplate yourself, not with AI
3. Incremental development - For each feature:
   - Break it down into small steps
   - Implement one step at a time with AI
   - Test it manually
   - Review and edit the code yourself
   - Write tests (when appropriate)
   - Commit
4. Never skip manual review - You're responsible for understanding every line
5. Commit frequently - After every working step, not at the end of the day

TIME BREAKDOWN:

Planning Phase (one-time per project):
- PLAN.md creation: 30-90 minutes
- Context setup: 15-30 minutes

Foundation Phase (one-time):
- Manual boilerplate: 15-30 minutes

Development Loop (per feature):
- Breaking down feature: 5-10 minutes
- Each implementation step: 10-30 minutes
- Code review per step: 5-10 minutes
- Testing per feature: 15-30 minutes
- Feature completion: 15-30 minutes

Total per feature: 2-4 hours including all steps

FEATURE BREAKDOWN PROCESS:

1. Select next feature from PLAN.md
2. Have AI read context files (claude.md, PLAN.md)
3. Ask AI to break down into specific steps
4. Review proposed steps carefully
5. Adjust or reorder as needed
6. Get alignment before proceeding

EXAMPLE PROMPT:
"Read PLAN.md and claude.md. For the 'User Authentication' feature,
break down the implementation into specific, testable steps.
Each step should be small enough to implement and test in under 30 minutes."

GOOD STEPS:
✅ Step 1: Install and configure NextAuth with credentials provider
✅ Step 2: Create user model in Prisma schema
✅ Step 3: Build signup form component and server action
✅ Step 4: Build login form component and server action
✅ Step 5: Add protected route middleware

BAD STEPS:
❌ Step 1: Build the entire authentication system (too big)
❌ Step 1: Add one line to the config file (too small)

IMPLEMENTATION PROCESS:

1. Give AI ONE specific step
2. Provide clear, detailed instructions
3. Let AI create/modify necessary files
4. Do NOT move to next step yet

EXAMPLE PROMPT:
"Implement Step 1: Install and configure NextAuth with credentials provider.

Tasks:
- Install next-auth package
- Create app/api/auth/[...nextauth]/route.ts
- Set up basic configuration with credentials provider
- Add required environment variables to .env.example

Follow the patterns in claude.md and use NextAuth v5."

BETTER PROMPTING TIPS:
- Reference specific files: "Add this to lib/auth.ts"
- Specify packages: "Use next-auth v5, not v4"
- Call out edge cases: "Handle the case where email already exists"
- Be explicit: "Use bcrypt for password hashing, 10 rounds"

TESTING CHECKLIST:

Run the application:
- npm run dev / rails server / etc.
- Check browser console for errors
- Check terminal for warnings

Verify functionality:
✅ Does it work in the happy path?
✅ Does it handle errors gracefully?
✅ Are there any console warnings?
✅ Does it work on mobile viewport?
✅ Is the UI accessible (keyboard navigation)?

Test edge cases:
- What happens with bad input?
- What happens with empty input?
- What happens when services fail?
- What happens with slow connections?

If broken:
- Have AI fix it before proceeding
- Don't accumulate broken code

CODE REVIEW CHECKLIST:

Open modified files and ask:
- Does this match my coding style?
- Are there security concerns?
- Could this be more performant?
- Is error handling adequate?
- Would I understand this in 6 months?

COMMON CHECKS:

Security:
- Are user inputs validated?
- SQL injection risks?
- XSS vulnerabilities?

Error Handling:
- What happens when things fail?
- Are errors logged appropriately?

Performance:
- Unnecessary database queries?
- N+1 query problems?

Type Safety:
- Are types specific enough?
- Any 'any' types sneaking in?

WHY THIS MATTERS:
AI gets you 80-90% there, but that last 10-20% needs a human touch.
You're the senior developer reviewing a junior's code.

TESTING STRATEGY:

When to write tests:
✅ Business logic functions
✅ API endpoints or server actions
✅ Database queries and transformations
✅ Authentication/authorization logic
✅ Complex algorithms or calculations
✅ Utility functions used across codebase

When to skip tests:
⏭️ Simple configuration files
⏭️ Basic UI components (mostly markup)
⏭️ One-off scripts or migrations
⏭️ Prototype/spike code you'll throw away

TEST TYPES:

Unit Tests — Individual functions in isolation
- Good for: utility functions, business logic
- Fast, focused, easy to maintain

Integration Tests — How parts work together
- Good for: API routes, server actions, database operations
- Most valuable for typical web apps

End-to-End Tests — Complete user flows
- Good for: critical user journeys only
- Slow but catch real-world issues

10 KEY PRINCIPLES:

1. NEVER SKIP PLANNING
   AI amplifies your plan. Vague plans produce vague results.

2. ALWAYS SET UP FOUNDATION MANUALLY
   You must understand the base of your application.
   Don't let AI create mystery infrastructure.

3. ONE STEP AT A TIME
   Small, incremental steps lead to better code and easier debugging.
   If something breaks, you know exactly what changed.

4. TEST BEFORE COMMITTING
   Every commit should represent a working state.

5. COMMIT FREQUENTLY
   Aim for 5-10 commits per day.
   Small commits = easy rollback + understandable history.

6. ALWAYS REVIEW AI CODE
   You are responsible. AI is your junior developer.

7. WRITE REAL TESTS
   Tests are not optional. They're your safety net.

8. KEEP CONTEXT UPDATED
   Update context files when you make architectural decisions.

9. MANUAL EDITING IS EXPECTED
   Good developers: 60% AI-generated, 40% manually refined
   Poor developers: 100% copy-paste without understanding

10. STAY IN CONTROL
    You are the lead developer. AI is your assistant.
    Red flag: 'I don't understand what the AI built, but it works!'

PITFALL: Starting Without A Plan
The mistake: Opening AI tool and starting with vague ideas
Why it fails: AI needs direction — inconsistent results, wasted time
The fix: Spend 30-60 minutes writing solid PLAN.md before code

PITFALL: Skipping Manual Setup
The mistake: Asking AI to 'create a Next.js app with all the boilerplate'
Why it fails: You don't understand your foundation
The fix: Always run framework CLI yourself (create-next-app, etc)

PITFALL: Letting Context Get Stale
The mistake: Writing plan on day 1, never updating as things change
Why it fails: AI gives bad suggestions based on outdated information
The fix: Update PLAN.md and claude.md with architectural decisions

PITFALL: Implementing Multiple Steps At Once
The mistake: 'Build entire authentication with login, signup, reset, email verification'
Why it fails: Too much code at once — when it breaks, you don't know why
The fix: Break it down. One feature at a time. One step at a time.

PITFALL: Trusting AI Output Blindly
The mistake: Copy-pasting AI code without reading or understanding
Why it fails: Building on foundation you don't understand — technical debt compounds
The fix: Read every line. Understand what it does. Edit what needs editing.

PITFALL: Rushing Through Steps
The mistake: Skipping manual review to 'move faster'
Why it fails: You ship bugs, accumulate debt, slow down over time
The fix: Manual review IS the speed. Quality code moves faster long-term.

PITFALL: Not Testing Before Committing
The mistake: Committing code because 'it looks right' without running it
Why it fails: Accumulating broken commits — git history becomes unreliable
The fix: Always run the app. Test the feature. Then commit.

PITFALL: Skipping Tests
The mistake: 'I'll add tests later when I have time'
Why it fails: Later never comes. As codebase grows, afraid to change anything.
The fix: Write tests as you build features. Make it part of workflow.

PITFALL: Not Committing Frequently Enough
The mistake: Working for 4 hours, building 3 features, one giant commit
Why it fails: Can't easily roll back — git history is useless
The fix: Commit after every working step. Small commits = easy rollbacks.

PROBLEM:
Every time you ask for a change, something else breaks.

DIAGNOSIS:
Your steps are too big. AI is changing too many things at once.

SOLUTION:
- Break requests into smaller steps
- One file at a time
- One feature at a time
- Verify each step before proceeding

PROBLEM:
AI keeps using patterns you explicitly said not to use.

DIAGNOSIS:
Your context file isn't clear enough, or AI isn't reading it.

SOLUTION:
- Make context more explicit: 'NEVER use X, ALWAYS use Y'
- Explicitly tell AI to read: 'Read claude.md and follow coding standards'
- Put most important rules at the top
- Use examples: 'Good: [example]  Bad: [example]'
- Reference context file in every major prompt

PROBLEM:
Looking at AI-generated code and you're confused.

DIAGNOSIS:
You skipped manual review, or AI's solution is overcomplicated.

SOLUTION:
- Stop. Don't move forward.
- Ask AI to explain what it did
- If too complex, ask for simpler solution
- Rewrite parts you don't understand in your own style

EXAMPLE PROMPT:
"I don't understand this code you generated in lib/auth.ts:
[paste confusing section]

Can you explain:
1. What this code does
2. Why it's necessary
3. What would happen if we removed it
4. If there's a simpler way to achieve the same thing"