Reconcile .codex/AGENTS.md with .claude/CLAUDE.md (shared origin, drifted)
Nobody has claimed this yet.
- Dominant language
- Shell
- Stars
- 114
- Forks
- 14
- PR merge metrics
- No merged PRs in 30d
Description
Both agent-instruction files are now tracked in this repo:
.claude/CLAUDE.md(~133 lines) — Claude Code's global instructions.codex/AGENTS.md(~101 lines) — Codex's equivalent
They share a common origin (the same "experienced, pragmatic software engineer" engineering-principles doc) but have drifted apart. A rough content diff shows ~42 lines present in CLAUDE.md but not AGENTS.md (rules added to CLAUDE.md over time — e.g. the parallel-agents/file-state-race guidance, the time-estimate and trivial-work sections, expanded testing rules) and ~18 lines unique to AGENTS.md (e.g. its more specific "don't test rendered scripts" testing guidance).
This is a deliberate "look at it later" item — both were tracked as-is during the config sweep rather than reconciled in-flight.
Decision to make
- Unify: pick one canonical source and generate/symlink the other (with a tool-specific header), so a rule added once lands in both. Risk: the two tools genuinely want some different guidance.
- Keep separate, intentionally: accept per-tool divergence but do a one-time merge pass so neither is missing a rule the other has, then let them drift on purpose.
Suggested first step
Three-way against the common ancestor (if recoverable from history) to see which differences are intentional per-tool vs just stale, then fold the stale-only-in-one deltas into both.
Filed during the $HOME config-tracking sweep.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare .codex/AGENTS.md and .claude/CLAUDE.md, starting with their shared history and a three-way diff against the common ancestor if it can be recovered. Identify which differences are intentional per-tool guidance and which are stale; done means the chosen relationship is documented and both files reflect the agreed reconciliation.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100