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

PLAN.MD STRUCTURE:

# Project: [Your Project Name]

## Goals
- Primary objective
- Secondary objectives
- Success criteria

## Tech Stack
- Framework: [chosen framework and version]
- Database: [database choice]
- Authentication: [auth solution]
- Styling: [CSS framework/solution]
- Deployment: [hosting platform]

## Features
1. Feature Name
   - Step 1: [specific, testable step]
   - Step 2: [specific, testable step]
   - Step 3: [specific, testable step]

2. Next Feature
   - Step 1: ...

## Technical Constraints
- Performance requirements
- Budget limitations
- Browser/device support

## Open Questions
- Decisions still to be made
- Areas needing research

CONTEXT FILE STRUCTURE:

Small Projects (< 20 files):
- Single claude.md file with everything

Large Projects:
- .claude/ai-interaction.md - Communication preferences
- .claude/development-workflow.md - Team standards
- .claude/coding-standards.md - Code style and patterns
- .claude/project-plan.md - Current roadmap
- .claude/current-sprint.md - Active work

CLAUDE.MD TEMPLATE:

# AI Context for [Project Name]

## Project Structure
- /app - Main application code
- /components - Reusable components
- /lib - Utility functions
- /prisma - Database schema

## Coding Standards
- Use TypeScript strict mode - no 'any' types
- Prefer server components unless interactivity needed
- Follow [specific framework] patterns
- Keep components under 200 lines

## Preferences
- Explicit over clever - readable code wins
- Always include error handling
- Descriptive variable names, not abbreviations

## External Documentation
- [Link to framework docs]
- [Link to library docs]
- [Link to API docs]

## What NOT to do
- Don't use client components unless necessary
- Don't install packages without asking
- Don't skip error handling

MANUAL SETUP STEPS:

1. Run framework initialization
   - npx create-next-app@latest
   - npm create vite@latest
   - rails new app_name
   - django-admin startproject

2. Install core dependencies manually
   - npm install prisma @prisma/client
   - Add essential packages you know you need

3. Set up basic folder structure
   - Create organizational folders
   - Establish naming conventions

4. Configure tools
   - TypeScript/ESLint configuration
   - Environment variables (.env.example)
   - Git setup (init, .gitignore)

5. Initial commit
   - git init
   - git add .
   - git commit -m "Initial project setup"

WHY MANUAL?
You need to understand your foundation. AI should build on solid ground that you control and comprehend. If something breaks later, you need to know how your project was set up.

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
- Add types for the session

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?
- Are there code smells?
- Does it follow best practices?
- 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?

Code Quality:
- Clear variable/function names?
- Repeated code to extract?

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

TESTING PRINCIPLES:
- Test behavior, not implementation
- Focus on integration tests for most features
- Write unit tests for complex business logic
- Write E2E tests for critical flows only
- Don't chase code coverage metrics

COMMIT WORKFLOW:

Once step works AND tests pass:
1. Stage changes: git add .
2. Write descriptive message
3. Commit: git commit -m "feat: implement NextAuth credentials provider"

COMMIT MESSAGE FORMAT (Conventional Commits):
- feat: add user authentication
- fix: resolve login redirect issue
- test: add unit tests for auth flow
- refactor: simplify error handling
- docs: update README with setup instructions
- style: format code with prettier
- chore: update dependencies

When to commit:
✅ After each implementation step (if it works)
✅ After fixing a bug
✅ After refactoring
✅ Before switching to different feature
✅ At end of work session

When NOT to commit:
❌ When code doesn't run
❌ When tests are failing
❌ Just to "save progress" on broken code (use git stash instead)

PRO TIP:
If halfway through something and need to switch:
git stash save "WIP: halfway through login form"
# Work on something else
git stash pop  # Come back to it later

COMPREHENSIVE TESTING:

Once all steps complete:
- Test complete feature flow start to finish
- Test integration with other existing features
- Test on different browsers
- Test on mobile viewport/devices
- Test edge cases missed during individual steps
- Test error scenarios and recovery
- Verify nothing else broke
- Have someone else test (fresh eyes catch bugs)

EXAMPLE FOR AUTHENTICATION FEATURE:
✅ Can new user sign up?
✅ Can user log in?
✅ Can user log out?
✅ Are protected routes actually protected?
✅ What happens with wrong password?
✅ What happens with duplicate email?
✅ Does "remember me" work?
✅ Can user reset password?

QUALITY REVIEW CHECKLIST:

Look for:
- Duplicated code across files
- Inconsistent patterns
- Opportunities to refactor
- Security best practices
- Performance bottlenecks
- Consistent error handling
- Accessibility standards
- Unused imports or dead code

REFACTORING PROMPT EXAMPLE:
"Review these three files:
- app/actions/create-workout.ts
- app/actions/update-workout.ts
- app/actions/delete-workout.ts

I see duplicated error handling and database connection logic.

Suggest refactorings to DRY this up, but don't implement yet.
Consider:
1. Should we extract a workout service?
2. Can error handling be standardized?
3. Are there security checks we should centralize?"

Then review AI's suggestions and decide what's worth doing.

DOCUMENTATION UPDATES:

Update README.md:
- How to set up new features
- Required environment variables
- How to run the app
- New dependencies or requirements

Update API documentation:
- New endpoints or changes to existing
- Request/response formats
- Authentication requirements

Update PLAN.md:
- Mark feature as complete
- Document decisions made
- Note any deviations from original plan

Update claude.md:
- New architectural patterns
- New coding standards adopted
- Libraries or approaches to use/avoid

Add code comments:
- Only for complex logic
- Explain WHY, not WHAT
- Keep them concise

FINAL COMMIT PROCESS:

1. Run all tests: npm test
2. Run linter: npm run lint
3. Check TypeScript: npm run type-check
4. If all pass, commit final changes

COMPREHENSIVE COMMIT MESSAGE:
git add .
git commit -m "feat: complete user authentication feature

- NextAuth v5 with credentials provider
- Email/password signup and login
- Protected routes middleware
- Password reset flow
- Comprehensive test coverage"

# Optional milestone tag
git tag v0.1.0-auth

THEN:
- Take a short break (seriously, step away)
- Review PLAN.md for next feature
- Update claude.md with learnings
- Go back to feature breakdown step
- Repeat the entire process

10 KEY PRINCIPLES:

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

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.
Never commit broken code (except with [WIP] prefix).

5. COMMIT FREQUENTLY
Small, focused commits make it easy to:
- Understand what changed
- Roll back if needed
- Review code history
- Collaborate with others
Aim for 5-10 commits per day.

6. ALWAYS REVIEW AI CODE
Don't blindly trust AI output. You are responsible.
You're the senior developer. AI is your junior developer.

7. WRITE REAL TESTS
Tests are not optional. They're your safety net.
Focus on integration tests and critical E2E paths.

8. KEEP CONTEXT UPDATED
Update context files when you make architectural decisions.
3 days from now, you'll forget why you made that choice.

9. MANUAL EDITING IS EXPECTED
AI is a tool, not a replacement for your skills.
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.
Never let AI drive architectural decisions without approval.
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, rails new, 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: Copying Code You Don't Understand
The mistake: AI generates complex code - you don't understand - you use anyway
Why it fails: You can't debug, extend, or maintain it
The fix: If you don't understand it, ask AI to explain or rewrite more simply

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:
You've been working on PLAN.md for 2 hours and haven't written code.

DIAGNOSIS:
You're overthinking it. Planning doesn't need to be perfect.

SOLUTION:
- Start with what you know
- Get to 80% completeness, then start coding
- Update the plan as you learn more
- Remember: PLAN.md is a living document
- It's okay to revise as you go

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]"
- Be more specific in prompts: "Following the patterns in claude.md, implement..."

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

DIAGNOSIS:
You skipped manual review step, 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
- This is a sign you need to slow down

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"

PROBLEM:
Writing tests is slowing you down significantly.

DIAGNOSIS:
You might be writing wrong kinds of tests, or too many tests.

SOLUTION:
- Focus on integration tests first (API routes, server actions)
- Skip unit tests for simple functions
- Use E2E tests only for critical user journeys
- Let AI generate test scaffolding, you verify coverage
- Remember: Some code doesn't need tests
- Don't chase code coverage metrics

TEST PRIORITY:
1. Integration tests for core features
2. Unit tests for complex business logic
3. E2E tests for critical paths only