How to Use Plan Mode Effectively with OpenAI Codex and AI Coding Agents
I was halfway through implementing JWT authentication when I realized my approach was completely wrong.
The AI agent had happily generated code for 30 minutes—installing packages, creating middleware, updating routes. But then I noticed it was adding JWT alongside my existing session-based auth, not replacing it. That wasn’t what I wanted. Worse, it had already modified 12 files and created 3 new ones.
Now I had a mess. I had to roll back changes, figure out which files were touched, and start over. All because I jumped straight to “write code” without properly planning the approach.
This is exactly when plan mode in AI coding agents saves you from yourself.
What Plan Mode Actually Does
Plan mode flips the workflow. Instead of: prompt → code → realize mistake → rework
You get: prompt → explore → question → plan → approve → code
The agent spends time understanding your codebase before writing anything. It finds existing patterns, identifies dependencies, spots potential conflicts, and asks clarifying questions about your requirements.
Here’s what this looks like in practice:
Direct Coding Approach: You: "Add JWT auth to my Express API" Agent: [immediately starts writing code] Agent: [modifies 12 files] You: "Wait, that's wrong..." Agent: [rolls back changes] Time lost: 45 minutes
Plan Mode Approach: You: "Add JWT auth to my Express API (use plan mode)" Agent: "Let me explore your codebase first..." Agent: "I found session-based auth in src/middleware/" Agent: "Should JWT replace sessions or coexist?" You: "Replace entirely" Agent: "What's your token expiration policy?" You: "15 minutes for access, 7 days for refresh" Agent: "Here's my proposed implementation plan..." You: [reviews and approves] Agent: [executes plan] Time saved: 40 minutesThe 5 minutes you spend answering questions during planning saves 40 minutes of rework during implementation.
When Plan Mode is Essential
I used to think plan mode was only for “big” features. I was wrong. The deciding factor isn’t feature size—it’s complexity and risk.
## Use Direct Coding when:- Adding a single function- Fixing a clear, isolated bug- Updating documentation- Making obvious refactoring changes- Task completes in under 10 lines of code
## Use Plan Mode when:- Adding a new feature with multiple components- Refactoring a module that others depend on- Changing database schema or API contracts- Implementing authentication or authorization- Creating a new page with multiple sections- Task involves 3+ files
## Use Plan Mode + Agent Review when:- You're unsure about the best approach- Multiple valid architectures exist- High-risk changes (security, data migration, breaking changes)The key insight: if you’d normally whiteboard something before coding it, use plan mode.
The Hidden Value: Agent Reviews You
Plan mode does something I didn’t expect—it lets the AI review YOUR thinking.
When I’m unsure about an architecture decision, I’ll describe my approach to the agent and ask: “What am I missing? What could go wrong?”
The agent will explore my codebase and point out things like:
- “Your proposed caching layer doesn’t account for the background jobs that also write to this data”
- “This migration approach will lock the users table for 30 seconds during peak hours”
- “Your new API endpoint doesn’t match the existing error handling pattern”
This reverse-review capability is incredibly valuable. The agent has context about your entire codebase—use it to sanity check your assumptions.
What Good Plan Mode Output Looks Like
A useful plan from the agent should have these components:
## Task: Add JWT authentication to Express API
### Phase 1: Understanding Context- Found auth-related files: src/middleware/, src/routes/auth.js- Current pattern: session-based auth in src/middleware/session.js- Dependencies: express-session, connect-redis (already installed)
### Phase 2: Questions for Developer1. Should JWT replace sessions entirely, or coexist?2. What's the token expiration policy?3. Do you need refresh tokens?4. Should existing sessions be migrated or invalidated?
### Phase 3: Proposed Implementation1. Install jsonwebtoken package2. Create src/middleware/jwt.js with verify logic3. Add /auth/login endpoint returning JWT4. Add /auth/refresh endpoint5. Create migration script for existing sessions6. Update protected routes to use JWT middleware7. Add tests for auth flows8. Update API documentation
### Phase 4: Risks and Mitigations- Risk: Breaking existing sessions Mitigation: Run both auth methods in parallel during transition- Risk: Token theft Mitigation: Short expiry + refresh tokens, store in httpOnly cookiesIf the agent skips any of these phases—especially the questions phase—that’s a red flag. Good plans demonstrate that the agent understands your existing codebase before proposing changes.
The PLANS.md Pattern
For longer workflows spanning multiple sessions, I’ve started using a PLANS.md file in my project root. This creates a persistent record of architectural decisions and implementation phases.
# Project: JWT Authentication Migration
## OverviewReplace session-based authentication with JWT tokens to supportmobile app clients and enable stateless API scaling.
## Architecture Decisions- Decision 1: JWT over sessions (eliminates Redis dependency for auth)- Decision 2: Access tokens expire in 15 minutes, refresh tokens in 7 days- Decision 3: Store tokens in httpOnly cookies (not localStorage, for security)
## Implementation Phases### Phase 1: Core JWT Infrastructure- Files to modify: src/middleware/jwt.js (new), package.json- Estimated complexity: Medium- Dependencies: None- Status: Complete
### Phase 2: Login and Refresh Endpoints- Files to modify: src/routes/auth.js, src/controllers/authController.js- Estimated complexity: Medium- Dependencies: Phase 1 complete- Status: In Progress
### Phase 3: Session Migration- Files to modify: src/middleware/session.js, src/scripts/migrateSessions.js- Estimated complexity: High- Dependencies: Phase 2 complete- Status: Pending
## Risks and Mitigations| Risk | Mitigation | Status ||------|------------|--------|| Breaking existing sessions | Run both auth methods in parallel | Active || Token theft | httpOnly cookies, short expiry | Implemented |
## Progress Log- 2026-03-28: Phase 1 complete- 2026-03-28: Started Phase 2, discovered missing refresh token rotation logicThe PLANS.md file serves as a contract between you and the agent. When you resume work in a new session, the agent reads this file and understands exactly where you are.
Common Mistakes I’ve Made
Skipping plan mode for “quick” features. I thought adding a simple search feature would take 10 minutes. Four hours later, I’d touched 8 files, broken two related features, and created a database index that locked my users table during peak traffic. A 5-minute planning session would have caught all of this.
Not answering agent questions thoroughly. When the agent asked about token expiration, I said “standard” instead of specifying “15 minutes for access, 7 days for refresh.” The agent implemented 1-hour access tokens. I had to redo the work.
Approving plans without reviewing them. Early on, I’d see “Plan ready” and immediately approve. Now I read every step, check the proposed file changes, and verify the risk mitigations make sense. This review has caught incorrect assumptions multiple times.
Starting implementation before plan is finalized. I’ve tried to “speed things up” by approving a partial plan and telling the agent to start coding while I finish reviewing. This always creates rework because the agent’s early implementation decisions don’t match my later clarifications.
Not updating plans when requirements change. Mid-implementation, I realized I needed to support both session and JWT auth simultaneously during a transition period. I updated the code but forgot to update PLANS.md. The next day, working with a fresh agent session, we wasted time rediscovering this requirement.
Why This Matters for AI Coding Workflow
The 8-step core practice sequence for AI coding starts with “clarify single task” and “plan complex tasks first”—before any coding happens. This isn’t bureaucracy; it’s economics.
Discovery during planning costs minutes. Discovery during implementation costs hours.
When you jump straight to code generation, the agent makes architectural decisions without full context. It can’t ask clarifying questions mid-implementation. It can’t surface dependencies it hasn’t explored yet. By the time a problem emerges, you’ve already invested significant time.
Plan mode shifts the cost curve. The agent explores first, questions second, plans third, and only then asks for your approval to proceed. This collaborative design phase prevents the most expensive mistakes.
The Collaborative Design Mindset
I now treat plan mode as a design partner, not an obstacle to coding speed. Here’s my mental model:
- Direct coding is for when I know exactly what I want and the change is small
- Plan mode is for when I know what I want but the change has complexity
- Plan mode + review is for when I’m uncertain about the best approach
The 10 minutes I spend in plan mode answering questions and reviewing proposals consistently saves 30-90 minutes of implementation rework. That’s a 3-9x return on time investment.
In this post, I shared my hard-won lessons about when and how to use plan mode in AI coding agents. The key insight: plan mode is collaborative design, not bureaucratic overhead. Use it for complex tasks, answer questions thoroughly, and treat the resulting plan as a contract. Your future self will thank you when you’re not rolling back 12 files worth of incorrect implementations.
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!
Related Posts:
Comments