How to Set Up an Effective AI Coding Workflow with Codex

Mar 27, 2026

The Problem

I kept explaining my project to Codex. Every. Single. Session.

Me: "This is a Node.js project with Express, Prisma, Redis..."
Codex: "Got it, I understand your architecture."
[Next day, new session]
Me: "This is a Node.js project with Express, Prisma, Redis..."
Codex: "Got it, I understand your architecture."
[Next week, new session]
Me: "This is a Node.js project..."

This is context amnesia. Each session starts from zero. The AI has no memory of previous conversations, no understanding of project conventions, no awareness of decisions made weeks ago.

The result? Inconsistent code suggestions. Repeated explanations. Wasted time.

Why This Happens

AI coding assistants are stateless. They don’t remember:

Your coding conventions
Architecture decisions you made
APIs you already defined
Modules you refactored last week
Why you chose PostgreSQL over MongoDB

Every session, you start from scratch. It’s like hiring a new developer every day who needs the same onboarding.

The Solution: Documentation-Driven Workflow

The fix is simple: create a persistent knowledge base that the AI can read at the start of every session.

Here’s the workflow I now use:

┌─────────────────────────────────────────────────────┐
│                 Project Root                         │
├─────────────────────────────────────────────────────┤
│  docs/                                               │
│  ├── architecture.md    ← System design             │
│  ├── conventions.md     ← Coding standards          │
│  ├── api-contracts.md   ← API specs                 │
│  ├── feature-log.md     ← Chronological changes     │
│  └── setup-guide.md     ← Environment setup          │
└─────────────────────────────────────────────────────┘

At the start of each Codex session, I say:

Read and understand all documentation in the docs/ folder before we begin.
This provides project context including architecture and conventions.

This takes 10 seconds. But it saves me from repeating the same explanations every time.

How I Set It Up

Step 1: Create the Documentation Structure

I created a docs/ folder at my project root:

mkdir -p docs
touch docs/architecture.md
touch docs/conventions.md
touch docs/api-contracts.md
touch docs/feature-log.md
touch docs/setup-guide.md

Step 2: Document the Architecture

The most important file is architecture.md. This tells Codex what your project is:

# System Overview

This is a Node.js/TypeScript application using:
- Express.js for API server
- PostgreSQL database with Prisma ORM
- Redis for caching
- JWT authentication

## Key Architecture Decisions

### ADR-001: Use Repository Pattern for Data Access
- **Status**: Accepted
- **Context**: Need abstraction layer for database operations
- **Decision**: Implement repository pattern with interface definitions
- **Consequences**: Easier testing, database-agnostic code

### ADR-002: Event-Driven Communication
- **Status**: Accepted
- **Context**: Services need to communicate without tight coupling
- **Decision**: Use event bus pattern with Redis pub/sub
- **Consequences**: Async processing, eventual consistency

Notice the ADR format (Architecture Decision Records). This captures why decisions were made, not just what was decided. This helps Codex understand context when suggesting changes.

Step 3: Document Coding Conventions

I created conventions.md to define coding standards:

# Coding Conventions

## File Organization
- Maximum 400 lines per file
- Extract utilities from large components
- Organize by feature, not by type

## Error Handling
- Always wrap async operations in try-catch
- Log errors with context
- Throw descriptive errors with user-friendly messages

## Naming
- camelCase for variables and functions
- PascalCase for classes and types
- UPPER_SNAKE_CASE for constants

## Testing
- Minimum 80% code coverage
- Use test-driven development for new features
- Write integration tests for API endpoints

Now when I ask Codex to implement a feature, it follows my conventions automatically.

Step 4: Track Features Chronologically

The feature-log.md file is crucial for context continuity:

# Feature Log

## 2026-03-20: User Authentication
- **Problem**: Need secure login system
- **Solution**: JWT-based auth with refresh tokens
- **Files**: src/auth/*, src/middleware/auth.ts
- **Notes**: Token expires in 15 minutes, refresh in 7 days

## 2026-03-22: Rate Limiting
- **Problem**: API abuse from single IP
- **Solution**: Redis-based rate limiter
- **Files**: src/middleware/rateLimiter.ts
- **Notes**: 100 requests per minute per IP

## 2026-03-27: User Profile Service
- **Problem**: Profile data scattered across tables
- **Solution**: Denormalized profile view
- **Files**: src/services/profile.ts
- **Notes**: Cache for 5 minutes in Redis

After each feature, I ask Codex: “Document this feature in docs/feature-log.md with the problem, solution, and affected files.”

The Session Protocol

Here’s my workflow for each coding session:

1. Context Loading (10 seconds)

Read docs/architecture.md and docs/conventions.md.
Summarize your understanding of this project.

This ensures Codex has the right context before we start.

2. Scope Definition

Today we're working on [feature/task].
Based on the documentation, what files and modules will be affected?

Codex now knows which parts of the codebase to examine.

3. Implementation

Implement [feature]. Follow the conventions in docs/conventions.md.
After completion, update docs/feature-log.md with this change.

The workflow is now self-documenting.

Model Selection: Pick the Right Tool

Not all tasks need the same reasoning power. I match model to task complexity:

┌────────────────────┬────────────────┬─────────────────────────┐
│ Task Type          │ Model           │ Why                     │
├────────────────────┼────────────────┼─────────────────────────┤
│ Boilerplate code   │ Codex Mini     │ Fast, cheap for patterns│
│ Bug fixes          │ Codex Standard │ Sufficient reasoning    │
│ New features       │ Codex Extended │ Deep reasoning needed   │
│ Architecture       │ Codex Max      │ Critical decisions      │
└────────────────────┴────────────────┴─────────────────────────┘

Using Codex Mini for boilerplate saves cost and is faster. Using Codex Max for simple tasks wastes resources.

Error-Driven Debugging

With good logging and documentation, debugging becomes streamlined:

Before: The Old Way

Me: "There's an error, let me paste the stack trace..."
Codex: "I need more context. What files are involved?"
Me: [pastes more code]
Codex: "What's your project structure?"
Me: [pastes folder structure]
...10 minutes of context-setting...

After: The New Way

Me: "I see an error with UserService.findById. The docs/ folder has context."
Codex: [Reads docs/architecture.md]
       [Reads docs/feature-log.md]
       [Examines src/services/user.ts]
       "Found it. Line 45 accesses 'id' property without null check.
        User not found returns null, causing the error.
        Adding guard clause..."

The key is having comprehensive logging in your application:

export const logger = {
  error: (message: string, context: object) => {
    console.error(`[ERROR] ${message}`, JSON.stringify(context, null, 2));
  },
  info: (message: string, context: object) => {
    console.log(`[INFO] ${message}`, JSON.stringify(context, null, 2));
  }
};

When errors occur, Codex has both the error message and the logged context to diagnose quickly.

Common Mistakes I Made

Mistake 1: Forgetting to Update Documentation

After implementing a feature, I’d skip updating feature-log.md. Next session, Codex had no idea the feature existed.

Fix: Make documentation part of the prompt: “After completing this task, update docs/feature-log.md.”

Mistake 2: Using Wrong Model for Task

I used Codex Max for generating boilerplate CRUD endpoints. Overkill. Wasted tokens and time.

Fix: Check task complexity before choosing model.

Mistake 3: Sparse Architecture Documentation

My initial architecture.md was two lines: “Node.js app with Express.”

Codex still asked clarifying questions every session.

Fix: Document architecture decisions, not just technology stack. Include ADRs for major decisions.

Mistake 4: Not Documenting Conventions

I assumed Codex would “figure out” my coding style. It didn’t. Inconsistent suggestions.

Fix: Explicit conventions in conventions.md. Now Codex follows my style automatically.

The Result

After implementing this workflow:

Context loading: 10 seconds per session
Inconsistent suggestions: Nearly eliminated
Debugging time: Cut by 60%+
Onboarding new features: Much smoother

One developer in a Reddit discussion put it well:

“I don’t even change anything myself anymore. It’s all chat, giving orders. Now I’m at work just moving things into an agentic workflow, and whenever there’s an issue, I just open Codex and it’s done in like 30 seconds.”

That’s the goal: from explaining your project repeatedly to just giving orders.

Getting Started

If you want to try this workflow:

Create docs/ folder at project root
Write architecture.md with technology stack and key decisions
Write conventions.md with your coding standards
Start each Codex session by asking it to read docs/
After each feature, update feature-log.md

The initial documentation takes 30-60 minutes. But you’ll earn that back in the first week from not repeating explanations.

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:

👨‍💻 OpenAI Codex CLI Documentation
👨‍💻 Reddit: AI Coding Workflow Discussion
👨‍💻 Documentation-Driven Development

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!