Chapter 5: Building a Harness in Codex — AGENTS.md, Config, Directory Structure

5.1 The Question: Start Fresh, or Take Over?

When people hear "build a harness in Codex," they usually think of filenames: AGENTS.md, ~/.codex/config.toml, .codex/agents/, .codex/skills/. But filenames are not where users actually get stuck. The practical questions are:

"In an empty project, what do I say to Codex so the first harness appears?"

"In an existing Claude Code repository, what do I keep, and what do I move into Codex?"

Those are different starting points. In an empty project, you create the rules together from scratch. In a Claude Code repository, you interpret existing CLAUDE.md, .claude/agents/, hooks, skills, and slash commands, then extract only the tool-neutral knowledge into a form Codex can read.

This chapter is not about copying example files. It is about giving the prompts that produce good files, then knowing what to review before accepting them.

5.2 The Two Paths

Start with the summary.

The empty-project sequence is simple.

1. Explain the project goal and quality bar.
2. Ask Codex to draft AGENTS.md.
3. Set conservative global config defaults.
4. Add skills or subagents only after repeated workflows appear.

The existing Claude Code sequence is more cautious.

1. Read CLAUDE.md and .claude/ in Read Only mode.
2. Compress current state into HANDOFF.md.
3. Copy only universal rules from CLAUDE.md into AGENTS.md.
4. Leave Claude-specific agents, skills, and hooks in place.
5. Rebuild repeated workflows as Codex skills, subagents, or wrapper scripts.

5.3 Empty Project: Create the First AGENTS.md with a Prompt

The AGENTS.md philosophy is simple: write what a new agent needs to know when it enters this codebase for the first time. Not one-time context, but persistent project rules.

The AGENTS.md standard has been adopted by 60,000+ open-source projects ^[2]. More precisely, that does not mean 60,000+ projects use the exact structure below. What has been widely adopted is the convention and discovery rule of keeping agent instructions in a repository file named AGENTS.md. The structure below is a practical starting template.

First prompt for an empty project:

This repository is a new project. Draft an AGENTS.md based on the goal below.

Project goal:
- <what this project builds, in 2-3 sentences>

Tech stack:
- <language/framework/database/test tools; write "undecided" if not decided>

My quality bar:
- <for example: small diffs, test-first, deployment safety, citation accuracy>

Output constraints:
- Propose only one AGENTS.md file
- Keep it under 100 lines
- Mark unverified commands as TODO instead of guessing
- Do not create subagents or skills yet
- Keep Common Mistakes to at most three items based on what is known now

The key is not saying "make it standard." The standard mostly concerns the filename and discovery behavior. The useful content comes from the project goal, stack, and constraints. If you only say "write a standard AGENTS.md," you will get generic guidance. Always include the project goal and constraints.

A first AGENTS.md is easiest to maintain at 60-120 lines. Once it grows past 150-200 lines, agents may miss the important parts and stale rules are more likely to diverge from the code. At that point, split the guidance into directory-specific AGENTS.md files, skills, HANDOFF.md, or TASKS.md.

A good first structure is enough ^[8].

# Project Rules

## Overview
<2-3 sentences on what this project does>

## Stack & Architecture
<Core tech stack, major directory roles>

## Code Standards
<Linter, formatter, naming, function size, typing rules>

## Testing
<Test commands, required checks, TODO if not available yet>

## Git Workflow
<Branch/commit/PR rules. Omit if not relevant>

## Common Mistakes to Avoid
<Things agents are likely to get wrong. Update as experience accumulates>

5.4 config.toml Is a Profile Choice, Not a Snippet to Copy

~/.codex/config.toml is user-level configuration, not a project file. Before copying an example, decide what default behavior you want. Start conservative.

First config for an empty project:

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
project_doc_max_bytes = 65536

Add the temporary bridge only when you also work with existing Claude Code repositories.

project_doc_fallback_filenames = ["CLAUDE.md"]

This does not mean deleting CLAUDE.md or renaming it to AGENTS.md. Codex discovers instructions by checking AGENTS.override.md, then AGENTS.md, then configured fallback filenames ^[14]. This line simply lets Codex refer to CLAUDE.md in repositories that do not yet have AGENTS.md.

Prompt Codex for a config draft like this:

Propose a Codex global config.toml draft for me.
The goal is safe local development.

Constraints:
- Use workspace-write as the default sandbox
- Use on-request for interactive approval
- Explain separately whether I should add a Claude Code fallback
- Do not edit files yet; show the TOML block and explain each line first

Config sets defaults; it is not an absolute law for every command and product surface. Specific commands can override config. For safety-related settings such as approval_policy and sandbox_mode, verify the active session with /status ^[14].

For stronger migration work, add two more layers before trusting automation. First, use permission profiles to express the filesystem and network boundary: read-only for inspection, workspace-write for normal edits, and broader access only for narrowly justified tasks. Second, use .rules to encode command policy. Let npm test, pytest, or make verify run with less friction; prompt or forbid npm publish, deploy commands, database migrations, and destructive shell operations ^[14].

5.5 Existing Claude Code Repo: Interpret Before Converting

A mature Claude Code repository contains more than code. It contains CLAUDE.md, .claude/agents/, hooks, skills, slash commands, memory rules, and repeated workflows. The dangerous first move is trying to convert all of that into Codex formats immediately.

The first prompt should ask for interpretation, not conversion.

This repository already uses a Claude Code harness.
Do not delete or rename CLAUDE.md, .claude/, hooks, skills, or subagents.

In Read Only mode, analyze:
- Tool-neutral rules in CLAUDE.md
- Claude-specific rules
- Roles in .claude/agents
- Workflows solved by hooks, skills, and slash commands

Output:
- Items to move into AGENTS.md
- Current state to record in HANDOFF.md
- Candidates for Codex skills
- Candidates for Codex subagents
- Items that should remain Claude Code-specific

Do not edit files yet.

The result should look like a classification table.

Only then ask for one small file.

Based on the classification table, execute only step 1.
Add only an AGENTS.md draft.
Do not modify CLAUDE.md or anything under .claude/.
Put only tool-neutral rules in AGENTS.md; leave Claude-specific guidance out.
Summarize the diff after the change.

5.6 When to Add Agents and Skills

Do not fill .codex/agents/ and .codex/skills/ on day one. AGENTS.md is enough for most first tasks. Add agents and skills when repeated patterns appear.

Use this distinction.

Prompt for converting a Claude Code agent into a Codex subagent:

Read .claude/agents/reviewer.md and propose a Codex subagent draft.

Constraints:
- Move only the purpose and review criteria
- Remove Claude Code-specific invocation style or tool names
- Propose .codex/agents/reviewer.toml
- Use only name, description, and developer_instructions
- Do not edit files yet; show the draft first

Expected Codex subagent shape:

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness, security, and maintainability"
developer_instructions = """
When called, review the current diff only.
Prioritize correctness, security, data loss, and missing tests.
Report findings with file:line references.
Do not comment on style unless it affects behavior.
"""

Prompt for converting a Claude Code skill or slash command into a Codex skill:

Read .claude/skills/test-gen or the related slash command and propose a Codex skill draft.

Constraints:
- Put only repeatable task guidance in SKILL.md
- Do not put shell execution, file moves, or publish steps in the skill
- Split those operational steps into wrapper-script candidates
- Propose .codex/skills/test-gen/SKILL.md
- Include trigger phrases and a usage example
- Do not edit files yet; show the draft first

Skills are reusable task instruction sets ^[14]. Do not port Claude Code slash commands literally. Keep "how the model should work" in the skill, and keep execution in bin/* wrappers or make commands.

5.7 Official Import Still Needs Human Review

The Codex app includes an "Import other agent setup" flow. From Settings -> General, Codex can detect user-level and project-level setup, import the pieces it can map directly, then offer a follow-up Codex thread for remaining migration work ^[14].

The June 2026 onboarding flow matters because many Claude Code repositories now contain real operational knowledge: hooks, skills, slash commands, MCP config, recent sessions, and subagents. The import output should be treated as a risk register. Anything the importer cannot map cleanly is usually the part that needs the most human review.

Official import covers these mappings ^[14].

Do not read this as "import and you are done." Import is a draft generator. For hooks, slash commands, and subagents, intent matters more than format. For example, /post is safer as two layers.

codex-native skill: .codex/skills/post/SKILL.md
stable wrapper:     bin/post <url>

The wrapper locks operational policy in code: argument handling, draft by default, no publish without approval, and HANDOFF.md updates. The skill stores model guidance for turning a source into a good post. This lets Codex reproduce the workflow in small diff-sized steps while Claude Code remains usable.

After import, ask Codex to review the generated harness.

Review the Codex harness that was just imported or converted.

Check:
- Was CLAUDE.md or .claude/ deleted or renamed?
- Did AGENTS.md accidentally include Claude-specific instructions?
- Do skills contain risky shell execution steps?
- Are subagents too broad?
- Could MCP auth, secrets, or deploy commands run automatically?

Do not edit files. Return a risk list and recommended diffs only.

5.8 Practical Conclusion: Let Codex Draft, Keep Human Ownership

Whether AGENTS.md and harness files should be written by humans or generated automatically is contested.

Write it yourself (Osmani) ^[9]: AI-generated AGENTS.md fails when it does not reflect real codebase pathologies. The true bottlenecks and mistakes come from human experience.

Automate the feedback loop (Jagtap) ^[10]: Extract repeated failure patterns from agent run logs and append them to AGENTS.md. This learns from actual failures without human bias.

This book takes the middle position. It is fine to let Codex draft. But humans decide what becomes a rule. In an empty project, provide goals and constraints, then ask for an AGENTS.md draft. In an existing Claude Code repo, first ask for interpretation and classification, then add AGENTS.md, HANDOFF.md, skills, and subagents one small diff at a time.

The chapter's operating sequence is:

1. For an empty project, explain the goal and request an AGENTS.md draft.
2. For an existing Claude Code repo, first inspect CLAUDE.md and .claude/ in Read Only mode.
3. Do not copy config blindly; choose a safety profile.
4. Add agents and skills after repeated patterns appear, not at the start.
5. Always review import and auto-conversion results manually.

The next chapter puts this harness into the work loop: create a small diff, attach a reviewer, and verify with tests.

References

1. OpenAI Codex repo, "AGENTS.md example," 2026. [OpenAI, 2026]
2. AGENTS.md Open Standard, "60K+ projects," 2026. [Foundation, 2026]
3. OpenAI, "AGENTS.md specification," 2026. [OpenAI, 2026]
4. OpenAI, "Codex config reference," 2026. [OpenAI, 2026]
5. OpenAI, "Codex subagents," 2026. [OpenAI, 2026]
6. OpenAI, "Codex skills," 2026. [OpenAI, 2026]
7. Willison, Simon, "Codex subagents GA," simonwillison.net, 2026-03-16. [Willison, 2026]
8. Augment, "How to build a great AGENTS.md," 2026. [Code, 2026]
9. Osmani, Addy, "Code orchestra — multi-model routing," 2026. [Osmani, 2026]
10. Jagtap, "Codex AGENTS.md auto-optimization," 2026. [Jagtap, 2026]
11. Vjujini, "Codex app — Korean hands-on review," 2026. [velog), 2026]
12. OpenAI, "Migrate to Codex," 2026. [OpenAI, 2026]
13. OpenAI, "Codex rules," 2026. [OpenAI, 2026]
14. OpenAI, "Codex permissions," 2026. [OpenAI, 2026]