From 9b17df200e623b5c820c7def28142ba03abfe60c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 11:03:00 +0000 Subject: [PATCH] docs: bake cross-agent coordination rules into CLAUDE.md and CODEX.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add matching 'Coordination' sections so Claude Code and Codex self-coordinate: lane/branch ownership (claude/* vs codex/*, never share a branch), base PRs on master (don't stack on an in-flight branch — the #3007 orphan lesson), one concern per PR, cross-review before merge, the @codex dispatch conventions (review reserved, serial, fix-in-place), and CI as the gate. --- CLAUDE.md | 12 ++++++++++++ CODEX.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index ddcd25efae..fadd915fbc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -137,6 +137,18 @@ Build compelling demos showing agents interacting with go-micro services in real - **[internal/docs/IMPLEMENTATION_SUMMARY.md](internal/docs/IMPLEMENTATION_SUMMARY.md)** - Implementation notes - **[CHANGELOG.md](CHANGELOG.md)** - What changed and when +## Coordination with Codex + +Go Micro is maintained by two AI tools — **Claude Code** (you) and **Codex** (its playbook is [CODEX.md](CODEX.md)) — plus the human maintainer, who routes work and owns every merge. To work side by side without collisions: + +- **Lanes / branches.** You work on `claude/*` branches; Codex on `codex/*`. Never push to Codex's branch, and never have both agents committing the same branch at once. +- **Base PRs on `master`; don't stack on Codex's in-flight branch.** If that base squash-merges, your commit gets orphaned (this happened — the #3007 fixes had to be re-landed). If the code you need isn't merged yet, wait for it, then branch off `master`. To improve an *open* Codex PR, fix it in place (once Codex is done with the branch, or via an `@codex` comment on the PR) rather than a separate stacked PR. +- **One concern per PR.** Single-purpose PRs; don't bundle (e.g.) a feature with a docs change. +- **Cross-review.** Review Codex's PRs before merge — mechanical fixes you can land yourself (based on `master`), but design/scope/positioning calls go to the human; don't silently rewrite Codex's intent. Codex reviews yours via `@codex review`. +- **Dispatching Codex.** Start a task by commenting `@codex ` on an issue/PR (that issue/PR is its context). `@codex review` is reserved for review; any other instruction starts a *task*. It's consequential (spends a Codex task slot, pushes commits) and **serial** (one task at a time) — so dispatch one task at a time, only on the human's go-ahead, and never write a literal `@codex` in a comment unless you intend to trigger it (write "Codex" in prose otherwise). +- **CI is the gate.** `go build`, `go test`, `golangci-lint` (blocking), and `make harness` must pass before merge. `internal/harness/` and `examples/` are excluded from errcheck; everything else gets the full set. +- **Backlog = GitHub issues**, each a scoped, self-contained brief with acceptance criteria. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines. Key points: diff --git a/CODEX.md b/CODEX.md index f12cdd0b0d..47a282819a 100644 --- a/CODEX.md +++ b/CODEX.md @@ -18,6 +18,18 @@ bar for review, tests, or design taste. 5. **No blind merges.** Codex output is treated like any contributor output: reviewed by a maintainer, backed by tests, and checked for public API impact. +## Coordination with Claude Code + +Go Micro is maintained by two AI tools — **Codex** (you) and **Claude Code** (its guide is [CLAUDE.md](CLAUDE.md)) — plus the human maintainer, who routes work and owns every merge. + +- **Lanes / branches.** You work on `codex/*` branches; Claude Code on `claude/*`. Never push to a branch the other owns, and never have both agents on one branch at once. +- **Base PRs on `master`.** Don't stack a PR on another agent's in-flight branch — if that base squash-merges, your changes can be orphaned. If the code you need isn't merged yet, wait, then branch off `master`. To improve a PR that hasn't merged, push to that PR's branch rather than opening a separate stacked PR — keep the change one mergeable unit. +- **One concern per PR.** Keep each PR single-purpose so a reviewer can read it in one sitting; don't bundle unrelated changes (e.g. a feature plus a docs rebrand). +- **Cross-review before merge.** Claude Code reviews your PRs; you review its with `@codex review`. A fresh pass from the other model catches what the author misses. +- **Dispatch.** Maintainers (or Claude Code) start your tasks with `@codex ` on the relevant issue/PR — that's your context. `@codex review` is review; any other instruction is a *task*. You run one task at a time: take the current one to a clean, green PR before the next is dispatched. +- **CI is the gate.** `go build`, `go test`, `golangci-lint` (blocking), and `make harness` must pass; never merge red. `internal/harness/` and `examples/` are excluded from errcheck; everything else gets the full set. +- **Backlog = GitHub issues**, each a scoped brief with acceptance criteria. + ## Best uses ### 1. PR review and triage