✂️ CLAUDE.md → AGENTS.md

Open your CLAUDE.md and read it line by line asking a single question: would this sentence still be true if the executor were Codex, Gemini CLI or a local model? If the answer is yes, the line is portable. It speaks about your world — the way you publish, your paths, your conventions — and not about the program that is reading it.

In this machine's global CLAUDE.md, the overwhelming majority of the file is portable. Rules like "publishing = commit + push to git, never poke Vercel directly", "the commit author follows the repo's target GitHub account", "semver versioning vX.XX.YY: minor bumps the XX and carries the YY, never resets it", "API keys always in ~/projetos/openpcbotv2/.env or ~/projetos/wifi/.env, load at runtime and never print the value" — none of them mentions Claude. They are work policy. Any agent that reads them behaves better.

Key concepts

Residue is not garbage. These are legitimate, useful instructions — they're just tied to one program. The kit's script recognizes residue through a list of keywords, which is literally a regular expression inside the file: AskUserQuestion, superpowers, context-mode, fable-mindset, claude-mem, ultrareview, /code-review, Artifact, advisor, plugin and hook. Every line matching one of these terms goes to the residue; all the others go to the portable file.

# inside scripts/adapt-instructions.sh — the cut rule, in one line:
CLAUDE_ONLY='AskUserQuestion|superpowers|context-mode|fable-mindset|claude-mem|ultrareview|/code-review|Artifact|advisor|plugin|hook'

Notice what this implies. The rule "never use AskUserQuestion (interactive menu), always ask in free text" is residue because of the tool name — but the intent ("I prefer to answer in text, not pick from a menu") is portable. The script can't tell intent from name: it cuts by word. That's why the result is a proposal, not a final file. When you review it, rewrite the intent in neutral language and leave the tool name in the residue.

cd ~/projetos/<your-project>

# how many lines in total
wc -l CLAUDE.md

# which lines are residue (same regex as the script)
grep -nE 'AskUserQuestion|superpowers|context-mode|fable-mindset|claude-mem|ultrareview|/code-review|Artifact|advisor|plugin|hook' CLAUDE.md

Key concepts

The script takes a project folder and looks for a CLAUDE.md inside it. If it doesn't find one, it says so and exits with code 0 — that's not an error, it's "nothing to adapt". If it does find one, it writes two files next to the original, with the suffix .proposto.md. That detail is the safety guarantee of the whole module: the script never overwrites anything. You read, fix, and only then rename by hand.

cd ~/projetos/agente-claude-codex

# 1. rehearsal: generates, shows the counts and deletes the files
scripts/adapt-instructions.sh ~/projetos/<your-project> --dry-run

# 2. for real: leaves the two .proposto.md in the project folder
scripts/adapt-instructions.sh ~/projetos/<your-project>

# Proposed (review and rename manually):
#   ~/projetos/<your-project>/AGENTS.proposto.md  (71 lines)
#   ~/projetos/<your-project>/CLAUDE.proposto.md   (7 lines)

# 3. see what changed before accepting
diff ~/projetos/<your-project>/CLAUDE.md \
     ~/projetos/<your-project>/AGENTS.proposto.md | head -40

This is worth scaling up. On this machine, 165 projects have a CLAUDE.md, 54 already have an AGENTS.md and 39 have both. In other words: 15 projects have AGENTS.md without CLAUDE.md (born portable) and 126 are still tied to a single runtime. On top of that, 13 projects marked as trusted in Codex have no AGENTS.md — those are the obvious pilot candidates, because Codex can already work in them but doesn't yet know the rules.

Key concepts

The question everyone asks at this point: "if I pull the rules out of CLAUDE.md, does Claude stop knowing them?". No. Claude Code understands an import line: an @ followed by the path of another Markdown file pulls that file's contents into the instructions. So the new CLAUDE.md starts with @AGENTS.md and continues with the seven lines of residue. Claude reads both. Codex reads only the AGENTS.md. Neither one loses anything that concerns it.

cd ~/projetos/<your-project>

# 1. back up the original, with the date in the name
cp CLAUDE.md CLAUDE.md.bak-$(date +%Y%m%d)

# 2. promote the ALREADY REVIEWED proposals
mv AGENTS.proposto.md AGENTS.md
mv CLAUDE.proposto.md CLAUDE.md

# 3. the new CLAUDE.md must start with the import
head -1 CLAUDE.md
# @AGENTS.md

Key concepts

Here is the detail that separates a workspace that works from one that only looks organized: nothing auto-loads. The runtime reads the instruction file — and that's it. The context/, tasks/ and handoffs/ folders are a human convention; no program will open them on its own. If you want the agent to read them, you write that it must, at the top of AGENTS.md. That is why the script injects this line automatically into every portable file it generates.

# AGENTS.md — portable project instructions

> Reading order for any agent: 1) this file, 2) context/overview.md,
> 3) context/current-state.md, 4) tasks/current.md, 5) handoffs/latest.md.
> These names are a convention: nothing is loaded automatically outside of
> AGENTS.md/CLAUDE.md.

Key concepts

When building the portable file, the script does two things: it filters out the residue lines and, on what remains, runs sed 's/CLAUDE\.md/AGENTS.md/g'. The replacement is global and blind. It does not distinguish "the CLAUDE.md of this project" from "the CLAUDE.md of that other project" — and the second mention should not change, because that other project still has a real CLAUDE.md on disk. The script's own header warns about this in a comment line.

# what the script does with the portable part:
grep -vE "$CLAUDE_ONLY" "$SRC" | sed 's/CLAUDE\.md/AGENTS.md/g'

# before (correct):
#   See the portal's `CLAUDE.md` for the update step by step.
#   Each project can have its own `CLAUDE.md` saying which account to use.
# after (broken — these files do not exist):
#   See the portal's `AGENTS.md` for the update step by step.
#   Each project can have its own `AGENTS.md` saying which account to use.

cd ~/projetos/<your-project>

# 1. where the original talked about CLAUDE.md
grep -n 'CLAUDE\.md' CLAUDE.md

# 2. where the proposal now talks about AGENTS.md
grep -n 'AGENTS\.md' AGENTS.proposto.md

# 3. the two lists side by side: every extra line is a replacement to check
diff <(grep -c 'CLAUDE\.md' CLAUDE.md) <(grep -c 'AGENTS\.md' AGENTS.proposto.md)

# 4. revert a mention that belonged to ANOTHER project
sed -i 's|AGENTS.md do portal|CLAUDE.md do portal|' AGENTS.proposto.md

Key concepts