docs: rewrite CLAUDE.md to point to AGENTS.md as authoritative source#5138
Conversation
|
Thanks for the PR! Template looks good ✓ — all required sections present (What/Why/Reviewer Test Plan/Risk/Linked Issues/中文说明). On direction: this is well-aligned. The project already maintains tool-specific config files ( On approach: scope is minimal and appropriate — 2 files, +41/-1. The decision to include a distilled summary of key rules (ESM, Prettier, Vitest, conventional commits, PR template) rather than just a one-liner redirect is a good hedge against drift. The bold "Read AGENTS.md first" directive ensures the authoritative source is always clear. No concerns. Moving on to code review. 🔍 中文说明感谢贡献! 模板完整 ✓ — 所有必填部分齐全(What/Why/Reviewer Test Plan/Risk/Linked Issues/中文说明)。 方向:完全对齐。项目已经在维护各 AI 工具的配置文件( 方案:范围最小且恰当 — 2 个文件,+41/-1。包含关键规则的摘要(ESM、Prettier、Vitest、conventional commits、PR 模板)而不只是一行重定向,是防止漂移的好策略。醒目的"Read AGENTS.md first"指令确保权威来源始终清晰。 没有顾虑,进入代码审查。🔍 — Qwen Code · qwen3.7-max |
Code Review (2a)Clean, minimal change. The new
The No correctness issues, no AGENTS.md violations. The content faithfully reflects the conventions defined in Testing (2b)Docs-only PR — verified the file tracking and content integrity via tmux. Before (main branch)
After (PR branch)
中文说明代码审查 (2a)简洁、最小化的改动。新的
无正确性问题,无 AGENTS.md 违规。内容忠实反映了 测试 (2b)纯文档 PR —— 通过 tmux 验证了文件追踪和内容完整性。见上方终端输出。 — Qwen Code · qwen3.7-max |
d52e9e8 to
98b1f52
Compare
|
Stepping back: this is a small, well-targeted fix for a real gap. The project already supports Qwen Code ( The fix does exactly what it needs to: point Claude Code at My independent proposal from Stage 2a was essentially identical to what this PR does. Nothing simpler was missed. Approving. ✅ 中文说明退一步看:这是一个针对真实缺口的小型、精准修复。项目已经支持 Qwen Code( 修复做了该做的事:让 Claude Code 指向 我在 Stage 2a 的独立方案与这个 PR 基本一致,没有发现更简单的路径。 通过。✅ — Qwen Code · qwen3.7-max |
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
LGTM, looks ready to ship. ✅
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
No issues found. LGTM! ✅ — qwen3.7-max via Qwen Code /review
What this PR does
The existing
CLAUDE.mdwas a standalone ~100-line project overview with no reference toAGENTS.md, and was gitignored so it was never tracked. When contributors use Claude Code to submit PRs, Claude Code reads onlyCLAUDE.md— it never sees our PR template, commit conventions, or review workflow defined inAGENTS.md. This led to PRs like #5137 where the tool followed its own context file style instead of our project conventions.This PR:
CLAUDE.mdas a thin pointer that tells Claude Code to readAGENTS.mdas the single source of truthCLAUDE.mdfrom.gitignoreso it is tracked in version controlNo duplicated content —
AGENTS.mdremains the authoritative source for all rules.Why it is needed
Our project already supports multiple AI coding tools — Qwen Code reads
QWEN.md+AGENTS.md, Codex readsAGENTS.md(same file, zero extra work), and Gemini CLI readsGEMINI.md. ButCLAUDE.mdwas previously gitignored and contained a standalone project overview with no reference to our actual conventions.By making
CLAUDE.mda lightweight bridge toAGENTS.mdinstead of a parallel source of truth, we ensure all contributors — regardless of which AI coding tool they use — follow the same PR workflow, commit conventions, and code style. No product code changes needed; this is purely a repository-level fix.Reviewer Test Plan
How to verify
AGENTS.mdreference and PR template requirement.gitignoreno longer ignoresCLAUDE.mdEvidence (Before and After)
CLAUDE.mdwas gitignored and contained a ~100-line standalone project overview with no mention ofAGENTS.md, PR template, or commit conventions.CLAUDE.mdis tracked in git. It is a 3-line pointer toAGENTS.md— the single source of truth.Tested on
Risk and Scope
Linked Issues
Related: #5137
中文说明
这个 PR 做了什么
现有的
CLAUDE.md是一份约 100 行的独立项目概述,没有引用AGENTS.md,且被.gitignore忽略从未纳入版本控制。当贡献者使用 Claude Code 提交 PR 时,Claude Code 只读CLAUDE.md——它永远看不到我们在AGENTS.md中定义的 PR 模板、commit 规范和 review 流程。这导致像 #5137 这样的 PR,工具遵循的是自己 context file 的风格而不是项目的规范。本 PR:
CLAUDE.md重写为 3 行指针文件,告诉 Claude Code 去读AGENTS.md作为唯一权威来源.gitignore中移除CLAUDE.md使其纳入版本控制不重复任何内容——
AGENTS.md仍然是所有规则的唯一来源。为什么需要
我们的项目已经支持多种 AI 编码工具——Qwen Code 读
QWEN.md+AGENTS.md,Codex 读AGENTS.md(同名文件,零额外工作),Gemini CLI 读GEMINI.md。但CLAUDE.md之前被 gitignore 忽略,且内容是一份独立的项目概述,完全没有引用我们的实际规范。通过让
CLAUDE.md成为指向AGENTS.md的轻量桥梁,而不是平行的信息源,我们确保所有贡献者——无论使用哪种 AI 编码工具——都遵循相同的 PR 流程、commit 规范和代码风格。不需要改动产品代码,纯粹是仓库层面的修复。