obra / obra/dotfiles

Reconcile .codex/AGENTS.md with .claude/CLAUDE.md (shared origin, drifted)

Open
#4 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.