🚀 Project 1: migrate your first real project
So far you have understood the philosophy (Track 1) and practiced each script in isolation (Track 2). Now comes Phase 0 and Phase 2 of the plan for real: give Codex a global base, pick a project that Codex currently opens "blind", clean up the CLAUDE.md, run the five scripts in order and prove it with readback in both runtimes. At the end, a handoff that either one can pick up.
🎯 The project on one screen
~/.codex/AGENTS.md, a project with a lean AGENTS.md + context/ + tasks/ + handoffs/, two readback reports and a handoff.🎯 Pick the pilot
The 2026-09-14 diagnostic found 13 projects marked as trusted in Codex that have no AGENTS.md. That means Codex enters them without any instructions: every session starts from scratch. They are the natural pilot candidates, because the gain is immediate and measurable. The Prompt B rule applies here: the smallest pilot that preserves a representative task. Don't start with the biggest one, start with the one you use most.
Read it as a staircase: the glowing steps are the ones this project climbs. Phase 0 gives Codex a global base; Phase 2 applies the portable core to one of the 13 projects it currently opens without instructions. Phase 1 (pilot skill) you already did in Track 2.
📊 The 13 candidates, by usage
Order suggested by the diagnosis, from most used to least used. The more sessions a project gets, the sooner AGENTS.md pays for itself.
✓ A good pilot
- ✓You open it every week, in both runtimes.
- ✓It has a CLAUDE.md that already says something useful (rules, paths, commit author).
- ✓It has a clear representative task: "publish to the portal", "run the backup", "generate the report".
- ✓Clean working tree when you start.
✗ A bad pilot
- ✗The biggest CLAUDE.md on the machine (ruflo, 1,391 lines) just because "it's the most complete".
- ✗A project another session is editing right now (the edits collide; it already happened in the portal).
- ✗A client project mixed with personal knowledge (that's Project 5).
- ✗A project nobody has opened in months: no usage, no evidence.
Concrete suggestion: start with wifi. It's the monitoring hub, has its own CLAUDE.md, gets sessions almost every day and already holds this course's own diagnosis. If you'd rather have something smaller and isolated, skool-roast or iccmonit.
Key concepts
Codex trusts the folder but receives no instructions from it.
The one that preserves a real task with the fewest files.
The flow that has to keep working after the migration.
Two sessions in the same repo corrupt the working tree.
🌐 Global base: ~/.codex/AGENTS.md
This is Phase 0. Claude has a 72-line global ~/.claude/CLAUDE.md with rules that apply to every project: commit author account per repo, where the API keys live, versioning, default image model. Codex has nothing equivalent: the file ~/.codex/AGENTS.md doesn't exist. Deriving one from the other is the cheapest step of the whole migration, and it's what makes Codex stop ignoring rules you consider obvious.
Generate the proposals
The script reads the global CLAUDE.md and separates the portable part from the Claude-specific residue, without touching the original.
Review both files
You read AGENTS.proposto.md and CLAUDE.proposto.md. Nothing goes in without your eyes on it.
Write to Codex and wire up the import in Claude
The portable part becomes ~/.codex/AGENTS.md. The global CLAUDE.md now starts with @AGENTS.md pointing to a local copy.
Goal: create ~/.codex/AGENTS.md from the global CLAUDE.md, with human review in between.
# 1. generate the proposals (overwrites nothing)
cd ~/projetos/agente-claude-codex
scripts/adapt-instructions.sh ~/.claude
# expected output: ~/.claude/AGENTS.proposto.md (71 lines) and ~/.claude/CLAUDE.proposto.md (7 lines)
# 2. review (open both, fix what grep got wrong)
less ~/.claude/AGENTS.proposto.md
less ~/.claude/CLAUDE.proposto.md
# 3. write: the portable part goes to Codex AND sits next to CLAUDE.md to be imported
cp ~/.claude/AGENTS.proposto.md ~/.codex/AGENTS.md
cp ~/.claude/AGENTS.proposto.md ~/.claude/AGENTS.md
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak-$(date +%Y%m%d) # backup before swapping
cp ~/.claude/CLAUDE.proposto.md ~/.claude/CLAUDE.md
rm ~/.claude/*.proposto.mdHow to verify: head -1 ~/.claude/CLAUDE.md shows @AGENTS.md; wc -l ~/.codex/AGENTS.md gives around 71.
⚠️ The rename trap
The script replaces every mention of CLAUDE.md with AGENTS.md in the portable part. Your global CLAUDE.md talks about other projects ("see its CLAUDE.md", "each project can have its own CLAUDE.md"). Those sentences get renamed too, and the meaning changes. During the review in step 2, search for AGENTS.md dele and put back the right name wherever it refers to another project.
30-second test: after saving, run codex exec "Qual conta de autor devo usar num commit para um repo da conta inematds? Cite a fonte." from ~. If it answers inematds <inematds@gmail.com> and cites AGENTS.md, Phase 0 passed.
Key concepts
Rules that apply in any folder: author, keys, versioning.
Claude imports the portable file; the leftovers stay only in CLAUDE.md.
Script output awaiting review; it is never applied on its own.
Before replacing the original, a copy with the date in its name.
🧹 Cleanup: a bloated CLAUDE.md becomes a lean AGENTS.md + context/
The newsletter insists: most of the migration is cleanup. The diagnosis found CLAUDE.md files of 1,391 lines (ruflo), 542 (rAgentic-cs), 427 (timesmkt2) and 401 (ruview). A file that size isn't instructions, it's a dumping ground: rules mixed with history, old decisions, runbooks and "lessons" that have already become code. Migrating it raw just carries the noise over to Codex. The rule: AGENTS.md holds only stable instructions; everything else goes to the place that owns it.
The bloated file on the left fans out: stable rules stay in the lean AGENTS.md; facts, decisions and runbooks go to context/, each with an owner. CLAUDE.md is left small, importing AGENTS.md.
✓ Stays in AGENTS.md
- ✓Reading order (AGENTS → context/overview → tasks/current → handoffs/latest).
- ✓Git rules: remote, author, "publish = push".
- ✓How to run, test and restart (3 to 5 commands).
- ✓Hard prohibitions: "never generate paid media without confirming".
✗ Leaves AGENTS.md (and goes to…)
- ✗Phase history and what was done when →
context/current-state.mdand CHANGELOG. - ✗"Lessons" and one-off fixes →
FALHAS.md(one line per failure). - ✗Architecture decisions with context →
context/decisions/AAAA-MM-DD-*.md. - ✗Long runbooks, URLs, where credentials come from →
context/sources.md.
Goal: measure the pilot's CLAUDE.md and separate what is instruction from what is dumping ground, before running the adapter.
P=~/projetos/<your-pilot>
wc -l $P/CLAUDE.md
# headings: the map of what's inside
grep -nE '^#{1,3} ' $P/CLAUDE.md
# candidates to move out: history, lessons, decisions, dates
grep -cniE 'lesson|corrigido em|decidi|fase [0-9]|20[0-9]{2}-[0-9]{2}' $P/CLAUDE.mdHow to verify: if the second grep returns dozens of lines, you have a dumping ground. Target after cleanup: AGENTS.md under 100 lines, and every removed section with a named destination in context/.
Don't delete, move. Cleanup isn't deleting. It's taking content out of the file every agent reads at boot and putting it in the file the agent reads only when needed. The content stays in the repo, versioned; it just changes layers.
Key concepts
Instruction is what changes behavior today; the dumping ground is what explains the past.
What the agent always reads has to be short; the rest is retrieved on demand.
Every removed section gets an owned file in context/.
Cleanup is a change of layer, not a loss of information.
🛠️ The five scripts in order
In Track 2 you ran each script on its own. Here they run in sequence on the pilot, and the order matters: diagnosis first (read-only), then instructions, then the core, then skills, and the proof last. Every step is reversible: nothing in ~/.claude is deleted, the adapter writes .proposto.md, the core does not overwrite, and install makes a backup alongside.
doctor.sh + audit.sh
Confirms both runtimes are ready and generates the inventory report. If you already ran it today, skip it.
adapt-instructions.sh on the pilot
Generates the project's .proposto.md files. You apply the cleanup from topic 3 during review and rename them.
init-core.sh
Copies the template without overwriting. Fill in context/overview.md and tasks/current.md with the representative task.
sync-skills.sh (only if the pilot uses its own skill)
Most projects use global skills. If the pilot has a local .claude/skills/, import it and install it in both.
readback-test.sh
The proof. Topic 5.
Goal: apply the whole kit to the pilot, in one session, without overwriting anything.
K=~/projetos/agente-claude-codex
P=~/projetos/<your-pilot>
cd $K
# 1. diagnosis (read-only)
scripts/doctor.sh && scripts/audit.sh
# 2. instructions: generates *.proposto.md next to the pilot's CLAUDE.md
scripts/adapt-instructions.sh $P
# ... review + cleanup (topic 3) ...
mv $P/AGENTS.proposto.md $P/AGENTS.md
cp $P/CLAUDE.md $P/CLAUDE.md.bak-$(date +%Y%m%d) && mv $P/CLAUDE.proposto.md $P/CLAUDE.md
# 3. portable core (lists [criado] and [mantido])
scripts/init-core.sh $P
# fill in: $P/context/overview.md, $P/tasks/current.md
# 4. only if the pilot has a local skill
ls $P/.claude/skills 2>/dev/null
# 5. minimal core check
bash $P/scripts/check.shHow to verify: check.sh prints [ok] for the 7 required files. head -1 $P/CLAUDE.md shows @AGENTS.md. The .bak exists.
📋 What to fill in tasks/current.md
- •Goal: the representative task, in one sentence. E.g.: "publish item X on the portal".
- •Owner: you. The agent executes.
- •Definition of done: something verifiable. "Push landed on origin" is verifiable; "looks good" is not.
- •Concrete next action: the first command to run or file to touch.
Key concepts
Diagnosis → instructions → core → skills → proof.
Every step leaves the original or a backup alongside.
init-core tells you what it did; it never overwrites.
Seven required files, non-empty. It is the minimum, not the proof.
✅ Readback in both runtimes
A file existing is not proof. The proof is a fresh session, in each runtime, answering five questions without relying on a previous conversation: what the goal and definition of done are, one important rule with its source file, the last accepted decision, the concrete next action, and any conflicts or missing access. The script runs claude -p and codex exec inside the pilot and saves the raw text. The verdict is yours, by reading.
Goal: get both answers and judge whether they cite the right files.
cd ~/projetos/agente-claude-codex
scripts/readback-test.sh ~/projetos/<your-pilot> both
# saves: relatorios/readback-claude-AAAA-MM-DD.md and readback-codex-AAAA-MM-DD.md
# what to look for in the answers
grep -cE 'AGENTS.md|tasks/current|handoffs/latest|context/' relatorios/readback-*-$(date +%F).mdHow to verify: both answers cite AGENTS.md, tasks/current.md and handoffs/latest.md, and the "next action" matches what you wrote in tasks/current.md. If a runtime answers from generic memory without citing a file, it failed.
✓ Answer that passes
- ✓"Goal: publish X. Done when: push on origin. Source: tasks/current.md."
- ✓"Rule: author inematds. Exact source: AGENTS.md, Git section."
- ✓Separates what the files say from what it infers.
- ✓Points out a real inconsistency between two files, if there is one.
✗ Answer that fails
- ✗"The goal seems to be improving the project" (no source).
- ✗Cites the old CLAUDE.md instead of AGENTS.md (the import didn't take).
- ✗"I couldn't read the files" (sandbox: see below).
- ✗Makes up a "last decision" that isn't in context/decisions/.
⚠️ The real failure that already happened
On the first readback run in the kit itself, Codex answered "I couldn't read the files: bwrap: loopback: Failed RTM_NEWADDR". The script forced -s read-only, and on this machine AppArmor restricts user namespaces, so Codex's bwrap sandbox doesn't start. The smallest fix: remove the flag and respect the sandbox_mode in ~/.codex/config.toml. It's logged in FALHAS.md as prompt | infra. If you see this error, the problem is the sandbox, not your AGENTS.md.
Make use of what the readback returns. On the second run, Codex read everything and pointed out three real inconsistencies in the kit: a missing handoff, a wrong sum in the report, a contradictory sentence. A good readback doesn't just pass; it audits. Fix what it finds before calling it done.
Key concepts
No conversation history; only what's in the files.
An answer without a file path doesn't count as evidence.
"I didn't read it" may be infra; tell them apart before touching the files.
Inconsistencies it points out are work for you, not noise.
🏁 Acceptance, handoff, risks and rollback
The project ends when the acceptance criteria are checked off with evidence, not when it "looks done". And it ends with a handoff: the next agent, in any runtime, needs to know what was done, what was verified and what the exact next action is. Without it, next week starts from scratch again, and you're back to depending on the JSONL files.
✅ Acceptance criteria (check off with evidence)
- ☐
~/.codex/AGENTS.mdexists andcodex execin~cites the author rule. Evidence: command output. - ☐The pilot has an AGENTS.md under 100 lines, a CLAUDE.md starting with
@AGENTS.md, andcontext/,tasks/,handoffs/filled in. Evidence:check.sh. - ☐Readback passed in both runtimes. Evidence: the two files in
relatorios/. - ☐The representative task still works in Claude. Evidence: it ran once after the migration.
- ☐Everything committed and on origin. Evidence: clean
git status -sb.
Goal: wrap up with handoff and commit, in one block.
P=~/projetos/<seu-piloto>
cd $P
# handoff: fill in the template sections (what changed, checks run and result, exact next action)
$EDITOR handoffs/latest.md
# the pilot now uses the core: record in tasks/current.md that acceptance passed
$EDITOR tasks/current.md
git add AGENTS.md CLAUDE.md context tasks handoffs scripts
git -c user.name=inematds -c user.email=inematds@gmail.com commit -m "workspace portátil: AGENTS.md + núcleo (context/tasks/handoffs); readback aprovado em Claude e Codex"
git push
git status -sb | head -1 # expected: ## main...origin/mainHow to verify: tomorrow, open a fresh Codex session inside the pilot and ask "read handoffs/latest.md and tell me the next action". If it answers with the same sentence you wrote, the cycle is closed.
⚠️ Risks of this project
- •Blind renaming of CLAUDE.md references from other projects (topic 2).
- •A cleanup that deletes instead of moving (topic 3).
- •Another session editing the same repo during the migration.
- •Each Codex readback uses OpenAI quota; run it per project, not in a loop.
↩️ Rollback in one command
- ✓Pilot CLAUDE.md:
mv CLAUDE.md.bak-AAAAMMDD CLAUDE.md. - ✓Global CLAUDE.md: same pattern in
~/.claude/. - ✓Codex base:
rm ~/.codex/AGENTS.mdreturns to the previous state (nothing). - ✓Core:
git checkout -- .before the commit, orgit revertafter.
Key concepts
Each criterion points to a file or command output.
The structured summary any runtime can pick up.
The work ends when it lands on origin.
Before you start, you already know how to undo each step.
Self-check (optional): the Codex readback answered "I couldn't read the files: bwrap RTM_NEWADDR". What do you do first?
🎯 Project summary
~/.codex/AGENTS.md derived from the global CLAUDE.md, with review and backup.Next project:
3.2 — MCP and hooks between Claude and Codex: tools travel, events don't