File-Based Plans Beat Chat Memory for Claude Code in 2026

For medium-or-larger Claude and Codex projects, do not treat chat or TodoWrite as the source of truth. Keep the restart point in a repository plan file and accept completion only from tests, diffs, or checks against a real environment, not from the agent’s verbal claim.

📑Table of Contents

1. Why Chat and Memory Are Not a Task Ledger
2. How to Keep the Plan File as Source of Truth
3. How to Split Work Between Claude Code and Codex
4. Do Not Accept Done From Self-Report
5. The Minimum Set to Place Tomorrow
6. FAQ
7. Summary

Official documentation states that each session starts with a fresh context window.

• Instructions that live only in conversation disappear after /compact.
• Chat history is not a durable ledger.
• The search intent here is not “which model is faster.” It is whether AI coding work can restart across sessions and whether “done” can be verified.

One file and one first check

The comparison table and checklist below reduce that to one PLAN/TODO file (or task_plan.md / ExecPlan) and one first completion command.

---

Why Chat and Memory Are Not a Task Ledger

CLAUDE.md and AGENTS.md hold rules you want every session to see, while in-progress checkboxes belong in a different file.

What CLAUDE.md keeps and what compaction drops

Claude Code Memory states that each session starts with an empty context window. What survives is human-authored CLAUDE.md and Claude-written auto memory. Both load at the start of a session, but they are context, not enforced config. If a behavior must be blocked, put it in a hook, not in a reminder sentence.

Project-root CLAUDE.md is re-read from disk after /compact. Conversation-only instructions, nested CLAUDE.md files, and path-scoped rules can look gone after compaction.

• Keep each file under about 200 lines; files over 4 MiB are skipped.
• @path imports expand at startup, so they do not save tokens.

---

Codex AGENTS.md merge limit

Codex has a matching size and merge rule. AGENTS.md discovery loads global, then project, then cwd files, with later directories winning.

• Combining stops at project_doc_max_bytes (32 KiB by default).
• Empty files, surprise overrides, and truncated tails will not be repaired by a later chat message.

---

Conversation is not a cross-session ledger

Sejuku’s independent guide makes the same operational distinction: conversation is a poor durable tracker, so cross-session work needs Markdown, JSON, an external tracker, or a CLAUDE.md list.

Dumping every live checkbox into CLAUDE.md conflicts with the official size guidance, so put the live list in TODO.md.

If you also need the two instruction files to stay aligned, use How to keep CLAUDE.md and AGENTS.md in sync. This article only cuts the restart ledger that sits outside those rule files.

---

How to Keep the Plan File as Source of Truth

File names do not have to match across teams. The chosen file must keep the restart point, the completion check, and the human approval gate.

Claude Code official loop

Claude Code’s documented loop is Explore → Plan → Implement → Commit. Best practices warn that mixing research into implementation solves the wrong problem.

• Plan mode is Shift+Tab or claude --permission-mode plan.
• Official guidance lets you skip planning for a typo, one log line, or a rename.
• Plan when the change spans files or the approach is unclear.

---

Codex ExecPlan

For Codex, the ExecPlan cookbook tells you to mention ExecPlan in AGENTS.md and keep a self-contained plan in .agent/PLANS.md.

• Progress must be a checklist.
• Acceptance is an observable behavior (“health returns HTTP 200 after boot”), not “I added a HealthCheck struct.”
• A later session should resume from that file and the worktree, without the old chat.

---

Same split, different filenames

Independent operators use different names for the same split.

• minorun365: PLAN.md (intent) → SPEC.md (spec) → TODO.md (restart ledger) → KNOWLEDGE.md (do-not-repeat). Do not implement first, and do not dump the whole job into one prompt.
• OthmanAdi: task_plan.md / findings.md / progress.md. Chat and TodoWrite vanish on /clear, compaction, or a crash. Isolate parallel work under .planning/YYYY-MM-DD-slug/.

---

Confirm the files loaded

Confirm that files loaded, not that the model remembers them.

1. Claude Code: /context and check Memory files. /init does not overwrite an existing CLAUDE.md.
2. Codex: codex --ask-for-approval never "Summarize the current instructions."
3. Nested check: codex --cd <subdir> --ask-for-approval never "List the instruction sources you loaded."

Keep CLAUDE.md itself small with CLAUDE.md design patterns for personal, team, and monorepo use. The decision here is simpler: do not mix live tasks into the rule file.

---

How to Split Work Between Claude Code and Codex

Using both tools is not a goal. Combine them only when the planner, implementer, and verifier can stay in separate files.

Comparison axes

Axis	Claude Code	Codex
Always-on instructions	CLAUDE.md / auto memory; context, not enforcement	AGENTS.md chain; later wins; 32 KiB default
Source of truth for live work	Official Plan mode; in practice TODO.md or task_plan.md	ExecPlan / PLANS.md; update Progress to resume

---

Done, parallel work, and fit

Axis	Claude Code	Codex
Definition of done	Tests, builds, Stop hooks, verifier subagents	Observable acceptance (for example health 200); no self-report
Parallel work	Official subagents; independent guides isolate directories	Reported as assigning different parts of one job
Better fit	Split explore from implement; stop rules with hooks	Multi-hour self-contained plans; review rules on disk

---

Sources

• Claude Code Memory
• Claude Code Best practices
• Codex AGENTS.md
• Codex ExecPlan
• ZDNET Japan via Yahoo News (as of August 2026)

---

Constraints when combining tools

ZDNET Japan reports a large commercial plugin rewrite that assigned different parts of the same job to Claude and Codex at task granularity, not line-by-line chat. Both agents can run for a long time. Shared chat as the ledger still collapses the boundary.

If you run parallel agents, cut directories or owned files first. Destructive actions stay behind a human approval line in the plan file.

---

Do Not Accept Done From Self-Report

“It looks done” is not a pass. Give the session a signal it can read: tests, build exit codes, linters, fixture diffs, or screenshot comparison.

Strengthen verification in stages

Official best practices rank verification as follows:

1. Rerun the same prompt
2. Re-evaluate with /goal
3. Add a Stop hook (eight consecutive blocks force an override exit)
4. Split implementer and scorer with a verifier subagent

OthmanAdi’s completion gate is opt-in and checks every phase before any oral completion counts.

---

Feeling faster is not completion evidence

GitKraken’s 20 August 2026 survey of 554 developers and engineering leaders shows why self-report is a weak close.

• 84% feel faster
• only 20% of orgs measure impact
• 39% have no measurement method
• 33% rely on developer self-report alone
• about 45% of Codex / Cursor users already run parallel agents

Feeling faster is a discovery signal, not completion evidence.

Lock one of diff, test, or live environment on the first task. For forcing the rule with hooks, see Enforce Claude Code rules with Hooks and permissions. Here, decide only the pass/fail command that feeds that gate.

---

The Minimum Set to Place Tomorrow

Move one live task onto disk and pin its completion to a single test command. A file-backed plan is not a silver bullet. Stale plans, weak checks, and parallel agents without permission remain the usual failure modes.

Checklist

• ✓ Keep CLAUDE.md / AGENTS.md to always-on rules; do not mix live tasks (stay under 200 lines / 32 KiB)
• ✓ Pick one restart file (TODO.md, task_plan.md, or ExecPlan)
• ✓ Make the first done condition an observable command (for example npm test, a named test, an expected exit code)
• ✓ Approve the plan in Plan mode or ExecPlan before implementation
• ✓ If you run parallel agents, cut directories or owned files first
• ✓ After /clear or compaction, resume from the file, not from chat
• ✓ Write human approval points (merge, permissions, destructive ops) into the file

---

After the files exist

For keeping the two rule files aligned, see How to keep CLAUDE.md and AGENTS.md in sync. The next action is not another model bake-off. Put the restart point and the verification command on disk.

---

FAQ

Is TodoWrite in chat enough?

Official docs do not treat TodoWrite as a durable source of truth. OthmanAdi notes it disappears on /clear, compaction, or a crash. Put live tasks on disk.

---

Can the whole task list live in CLAUDE.md?

Sejuku lists that as one option. Official guidance keeps the file near 200 lines and limited to facts every session needs. Live checkboxes are safer in TODO.md.

---

What is the AGENTS.md size limit in Codex?

Combined files stop at project_doc_max_bytes, 32 KiB by default. Anything past that is not added.

---

Does every small fix need Plan mode?

Official guidance allows a direct path for typos, one log line, or a rename. Plan when multiple files or an unclear approach are involved.

---

Can I ask the agent whether the work is done?

Official docs want a pass/fail signal. GitKraken shows the limit of self-report. Lock a test or a diff first.

---

Should Claude Code and Codex run at the same time?

ZDNET Japan documents a task-level split. Combine them only when planner, implementer, and verifier stay in separate files.

---

Related articles:

• 13629
• 13624
• 13641

Summary

The useful difference is not raw model speed. It is refusing to treat volatile chat as the ledger, and making completion checkable.

Keep CLAUDE.md / AGENTS.md for always-on rules, plan files for live work, and verification outside self-report. The next step is one restart file and one test command pinned as the first definition of done.