Codex Practical Development Guidebook

Build my app.

Inspect this repository and propose a plan to implement user authentication.
Do not modify files yet.
After I approve the plan, implement it, add tests, and run verification commands.

Goal:
Implement email/password authentication.

Requirements:
- Users can sign up with email and password.
- Passwords must be securely hashed.
- Login returns a valid session.
- Invalid credentials return a clear error.

Constraints:
- Follow the existing project architecture.
- Do not introduce a new auth provider unless necessary.
- Do not change unrelated files.
- Add tests for signup, login, and invalid credentials.

Workflow:
1. Inspect the repository.
2. Explain the current relevant architecture.
3. Propose a file-level implementation plan.
4. Wait for approval before editing.
5. Implement with minimal diff.
6. Run tests, lint, typecheck, and build.
7. Summarize changes and risks.

Understand → Plan → Implement → Verify → Review

Inspect this repository and explain:
- project structure
- main framework
- build/test commands
- important modules
- current architecture
- risks before changing code

Do not modify files.

Create an implementation plan for [feature].

Include:
- files to modify
- files to create
- tests to add
- commands to run
- possible risks

Do not modify files yet.

Implement the approved plan.
Keep the diff minimal.
Follow existing conventions.
Do not refactor unrelated files.

Run the relevant verification commands:
- lint
- typecheck
- tests
- build

Fix failures caused by your changes.
If a failure is unrelated, explain it clearly.

Summarize:
- files changed
- behavior added or changed
- tests added or updated
- commands run
- known risks
- recommended follow-up tasks

project/
├── README.md
├── AGENTS.md
├── .codex/
│   └── config.toml
├── .env.example
├── package.json
├── src/
├── tests/
├── docs/
│   └── architecture.md
└── scripts/

README.md
AGENTS.md
.env.example
working dev/test/lint/build commands

# Project Name

## Purpose

Briefly explain what this app does.

## Tech Stack

- Frontend:
- Backend:
- Database:
- Auth:
- Deployment:

## Local Development

```bash
npm install
npm run dev
```

## Common Commands

```bash
npm run lint
npm run typecheck
npm run test
npm run build
```

## Folder Structure

```text
src/
├── app/
├── components/
├── lib/
├── services/
└── tests/
```

## Development Rules

- Keep changes small.
    
- Add tests for new business logic.
    
- Do not modify generated files manually.
    
- Do not commit secrets.
    

~/.codex/AGENTS.md          # global personal preferences
project/AGENTS.md           # project-specific instructions
project/subdir/AGENTS.md    # directory-specific instructions

# AGENTS.md

This file contains project-specific instructions for Codex.

## Project Overview

This is a [web app / mobile app / backend service] for [brief purpose].

Main stack:

- Language:
- Framework:
- Database:
- Auth:
- Deployment:

## Development Principles

- Prefer simple, maintainable solutions.
- Keep diffs small and focused.
- Follow existing project conventions.
- Do not introduce new dependencies unless necessary.
- Ask before making large architectural changes.
- Prioritize correctness, readability, and testability.

## Common Commands

Use these commands when relevant:

```bash
npm run dev
npm run lint
npm run typecheck
npm run test
npm run build
```

If a command fails, investigate and explain the root cause before making more changes.

## Project Structure

```text
src/
├── app/          # routes/pages
├── components/   # reusable UI components
├── lib/          # shared utilities
├── services/     # business logic / API clients
├── db/           # database schema and migrations
└── tests/        # tests
```

## Coding Style

- Use TypeScript.
    
- Prefer explicit types for public functions.
    
- Avoid `any` unless there is a strong reason.
    
- Keep functions small and focused.
    
- Prefer composition over inheritance.
    
- Avoid duplicated logic.
    
- Use meaningful names.
    

## UI Rules

- Reuse existing components before creating new ones.
    
- Keep styling consistent with the current design system.
    
- Avoid large visual redesigns unless explicitly requested.
    
- Make UI responsive by default.
    
- Include loading and error states where appropriate.
    

## Backend Rules

- Validate all external input.
    
- Do not expose secrets.
    
- Handle errors explicitly.
    
- Keep API responses consistent.
    
- Avoid changing public API contracts without approval.
    
- Add logging only when useful and safe.
    

## Database Rules

- Do not modify existing migrations unless explicitly asked.
    
- Create new migrations for schema changes.
    
- Explain migration risks before applying database changes.
    
- Never use production credentials.
    
- Prefer read-only inspection unless modification is explicitly required.
    

## Testing Rules

For new features:

- Add or update tests.
    
- Cover happy path and important failure cases.
    
- Run the relevant test command.
    
- If tests cannot be run, explain why.
    

## Git Rules

- Do not commit changes unless explicitly asked.
    
- Before suggesting a commit, summarize the diff.
    
- Use clear commit messages.
    
- Do not rewrite Git history unless explicitly asked.
    

## Security Rules

Never read, print, modify, or commit:

- `.env`
    
- `.env.*`
    
- secret files
    
- private keys
    
- production credentials
    

Use `.env.example` for documenting required environment variables.

## Task Workflow

For non-trivial tasks:

1. Inspect the relevant files.
    
2. Explain the current behavior.
    
3. Propose a plan.
    
4. Wait for approval if the change is large.
    
5. Implement with minimal diff.
    
6. Run verification commands.
    
7. Summarize the result.
    

## Definition of Done

A task is done when:

- The requested behavior is implemented.
    
- Relevant tests are added or updated.
    
- Lint/typecheck/test/build pass, or failures are explained.
    
- The final response includes:
    
    - changed files
        
    - verification result
        
    - risks or follow-up tasks
        

~/.codex/AGENTS.md

# Global Codex Instructions

## Personal Preferences

- Prefer concise explanations.
- Use practical engineering reasoning.
- Keep changes minimal.
- Do not over-engineer.
- Ask before large architecture changes.
- Prefer TypeScript for JavaScript projects.
- Prefer explicit validation and clear error handling.

## Default Workflow

For non-trivial tasks:

1. Inspect first.
2. Plan before editing.
3. Implement in small steps.
4. Run verification commands.
5. Summarize changes and risks.

## Safety

- Never access secrets unless explicitly allowed.
- Never modify `.env` files.
- Never run destructive commands without confirmation.

~/.codex/config.toml
project/.codex/config.toml

.codex/config.toml

# .codex/config.toml
# Project-level Codex configuration

# Keep project config small and explicit.
# Put personal preferences in ~/.codex/AGENTS.md.
# Put project rules in AGENTS.md.

# Example profile for normal development
[profiles.dev]
approval_policy = "on-request"

# Example profile for safer review-only work
[profiles.review]
approval_policy = "on-request"

# Example profile for more autonomous local work
# Use only when you trust the repo and commands.
[profiles.autonomous]
approval_policy = "on-failure"

# Optional: project-specific environment variables can be referenced
# by tools or MCP servers, but do not hardcode secrets here.

AGENTS.md
README.md
basic commands

npm run lint
npm run typecheck
npm run test
npm run build
git status
git diff

rm -rf
sudo
chmod 777
curl | sh
database migration commands
deployment commands
production scripts

Does Codex repeatedly need information that is not in the repo?

# ~/.codex/config.toml or .codex/config.toml

[mcp_servers.example_docs]
command = "npx"
args = ["-y", "example-docs-mcp-server"]

[mcp_servers.example_docs.env]
EXAMPLE_API_KEY = "${EXAMPLE_API_KEY}"

API_KEY = "real-secret-key"

API_KEY = "${API_KEY}"

1. Use Codex manually
2. Add AGENTS.md
3. Add project config
4. Add MCP
5. Add Skills
6. Build custom agents with SDK

Inspect this repository and explain it to me as if I just joined the project.

Include:
- tech stack
- folder structure
- main data flow
- build/test commands
- important risks
- where I should start reading

Do not modify files.

I want to implement [feature].

Requirements:
- [requirement 1]
- [requirement 2]
- [requirement 3]

Constraints:
- Follow existing architecture.
- Keep the diff small.
- Add tests.
- Do not introduce new dependencies unless necessary.
- Do not modify unrelated files.

First inspect the repo and propose a file-level plan.
Do not modify files until I approve.

There is a bug:

[describe bug or paste error]

Please:
1. Reproduce or locate the issue.
2. Explain the root cause.
3. Propose a minimal fix.
4. Implement the fix.
5. Add or update tests.
6. Run verification commands.

Refactor [module/file] to improve maintainability.

Constraints:
- Do not change external behavior.
- Do not change public API.
- Keep the diff focused.
- Do not refactor unrelated files.
- Add tests only if current coverage is insufficient.

Before editing, explain the refactor plan.

Review the current diff.

Focus on:
- correctness
- edge cases
- security
- test coverage
- maintainability
- unnecessary complexity

Do not modify files.
Give prioritized feedback.

Add tests for [feature/module].

Cover:
- normal case
- edge cases
- invalid input
- error handling

Use the existing test style.
Run the relevant test command after adding tests.

Review the current architecture for [area].

Tell me:
- what is good
- what is risky
- where complexity may grow
- what should be refactored now
- what can wait

Do not modify files.

The CI failed with this output:

[paste CI log]

Please:
1. Identify the failing step.
2. Explain the likely root cause.
3. Inspect relevant files.
4. Propose a minimal fix.
5. Implement the fix.
6. Run the same command locally if possible.
7. Summarize the result.

Upgrade [dependency] from [old version] to [new version].

Requirements:
- Check breaking changes.
- Update code if needed.
- Keep the diff minimal.
- Run tests and build.
- Summarize any behavior changes.

README.md
AGENTS.md
.codex/config.toml
.env.example

Inspect this project and suggest improvements to make it more maintainable.
Do not modify files.

Implement the landing page.

Implement user signup.

Implement login.

Implement user profile editing.

Implement dashboard data loading.

Run lint, typecheck, tests, and build.
Fix failures caused by your changes.

app navigation
screen structure
state management
API client
local storage
environment config
build commands

## Mobile App Rules

- Follow the existing navigation pattern.
- Keep screens thin.
- Put business logic in services/hooks.
- Keep reusable UI in components.
- Avoid platform-specific code unless necessary.
- Test both iOS and Android assumptions when possible.
- Do not change app permissions without approval.
- Do not introduce native modules unless necessary.

Implement [screen name].

Requirements:
- [UI behavior]
- [API behavior]
- [loading state]
- [error state]

Constraints:
- Follow existing navigation.
- Reuse existing components.
- Keep business logic outside the screen component.
- Do not add native dependencies unless necessary.

First propose a plan.

Analyze the codebase. Do not modify files.

Propose a plan before editing.

Build the whole app.

Implement the login form UI only.

Implement the login form UI using existing components.
Do not connect the API yet.

npm run lint
npm run typecheck
npm run test
npm run build

Summarize:
- files changed
- behavior added
- tests added
- commands run
- known risks

Make this app better.

Review the dashboard page for maintainability and suggest 5 concrete improvements.
Do not modify files.

Keep the diff minimal.
Do not refactor unrelated files.

AGENTS.md
config.toml
README.md
.mcp files
source code

git diff

Review your own diff for bugs, security issues, and unnecessary changes.

README.md
AGENTS.md
.env.example
.codex/config.toml

# AGENTS.md

## Project Overview

This is a personal software project.

## Rules

- Keep changes small and focused.
- Follow existing code style.
- Do not introduce dependencies unless necessary.
- Do not read or modify `.env` files.
- Add tests for new logic.
- Run lint/test/build when relevant.
- Explain risks before major architecture changes.

## Commands

```bash
npm run lint
npm run test
npm run build
```

## Workflow

For non-trivial tasks:

1. Inspect files.
    
2. Propose a plan.
    
3. Implement.
    
4. Verify.
    
5. Summarize.
    

I want to work on [task].

Please follow this workflow:
1. Inspect the relevant files.
2. Explain the current implementation.
3. Propose a concise plan.
4. Ask for approval before large changes.
5. Implement with minimal diff.
6. Run relevant verification commands.
7. Summarize changed files, tests, and risks.

Constraints:
- Follow existing architecture.
- Do not modify unrelated files.
- Do not introduce new dependencies unless necessary.
- Do not access secrets.

Implement [task] end-to-end.

Requirements:
- [requirement 1]
- [requirement 2]

Constraints:
- Keep the diff focused.
- Follow existing patterns.
- Add tests.
- Do not change public APIs unless necessary.
- Do not modify unrelated files.

Verification:
- Run lint.
- Run typecheck.
- Run tests.
- Run build.

Final response:
- summarize changed files
- summarize tests
- list commands run
- list risks

Explain how this feature works in this codebase.

Please cover:
- entry points
- important files
- data flow
- external dependencies
- possible failure points
- how I should safely modify it

Do not modify files.

I am building [product].

Current goal:
[goal]

User flow:
[user flow]

Technical constraints:
[constraints]

Please inspect the project and suggest a practical implementation plan.

Focus on:
- smallest useful MVP
- maintainable architecture
- testable implementation
- avoiding over-engineering

Do not modify files yet.

Good README
Good AGENTS.md
Small tasks
Clear constraints
Verification commands
Manual diff review

.codex/config.toml
MCP
Skills
SDK automation

Clear goal
+ project context
+ small task scope
+ test/build verification
= effective Codex usage