docs(agents): the two multi-agent failure modes that cost this branch the most rounds - #4152
Merged
Merged
Conversation
… the most rounds Both written from one branch's lifetime, so every row is something actually hit rather than something that might happen. #9 — refresh a long-lived worktree's build state after merging main. Four stale artefacts each fail AS IF your change broke something, naming other people's exports, other packages' files, or config you never touched: packages/spec/dist check:api-surface reports OTHER people's exports as "N breaking"; check:i18n-coverage rejects an example config for a value the spec allows node_modules a package cannot resolve a dependency it declares runtime/.objectstack/ fixture rows accumulating across runs .cache/objectui-* dozens of lint errors in files never opened None is CI-visible — CI checks out fresh and installs clean — so the whole cost lands on whoever is debugging, which is exactly why it is worth recognising in one step instead of re-diagnosing per gate. Also records that OS_SKIP_DTS=1 leaves no .d.ts, so gen:api-surface cannot run under it at all. #10 — a clean merge is not a working merge. Git conflicts on overlapping lines and says nothing when two changes are individually fine and jointly wrong. Both examples are recent: a test pinning a response body's exact shape landed while that shape was being changed elsewhere (merged clean, failed CI), and a domain file was deleted while another agent's guard still declared it (caught only because the guard existed). Hence pull main and re-run before opening a PR, and again before merging. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CYbS3kS8xzsHNXFTzp4e2z
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
July 30, 2026 12:48
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs only — two entries appended to AGENTS.md § Multi-agent working discipline. Both written from one branch's lifetime (the #3843 envelope line, 16 PRs), so every row is something that actually happened rather than something that might.
#9 — refresh a long-lived worktree's build state after merging
mainFour distinct stale artefacts, each of which fails as if your change broke something — naming other people's exports, other packages' files, or config you never touched:
packages/spec/distcheck:api-surfacereports other people's exports as "5 breaking (removed/narrowed)";check:i18n-coveragerejects an example config for a chart type the spec allowsnode_modulesCannot find package 'hono')packages/runtime/.objectstack/datasource-autoconnectsees each row 6×.cache/objectui-*pnpm lintreports 61 errors in files you have never openedI hit the first one three separate times before writing it down, and diagnosed it from scratch on two of them. The message that names someone else's export as a breaking change is a genuinely alarming thing to read on your own PR.
Also records that
OS_SKIP_DTS=1— the flag that keeps local builds fast — leaves no.d.ts, sogen:api-surfacecannot run under it at all, failing withCould not resolve module symbol … Is the package built?. That reads as a broken build rather than a missing flag.None of this is CI-visible: CI checks out fresh and installs clean. The entire cost lands on whoever is debugging, which is the argument for recognising it in one step rather than re-diagnosing per gate.
#10 — a clean merge is not a working merge
Git conflicts on overlapping lines. Nothing warns you when two changes are individually fine and jointly wrong. Two real cases from this branch:
/ai/agents's body is exactly{ agents: [] }whileGET /ai/agentsis SDK-addressable but unenveloped, and the SDK compensates — making it conformant without a coordinated change silently returns an empty agent list #4053 was enveloping that body one commit earlier. Merged clean, failed CI.runtime/src/domains/storage.tswhilecheck-route-envelope.mjs's table still declared it — caught only because that guard exists and treats an undeclared/missing module as an error.A third was a genuine textual conflict (#4133 and I both removed the same stale ledger entry), and that one git did flag — which is the contrast worth internalising: the conflicts git catches are the ones where two people touched the same line, not the ones where the result is broken.
So: pull
mainand re-run before opening a PR, and again before merging. Much ofscripts/check-*.mjsexists precisely because this class of breakage is invisible togit merge.Verification
check:doc-authoring·check:role-word·check:org-identifier·check:nul-bytes·check:release-notes— all clean. Empty changeset: docs, releases nothing.Generated by Claude Code