docs(agents,pr-template): add Working Principles and restructure PR template - #4496
Conversation
Add a "Working Principles" section at the top of AGENTS.md, with Simplicity First (adapted from Andrej Karpathy's CLAUDE.md) as the lead principle. Extend Code Conventions with two new entries: - File naming: PascalCase for React components, kebab-case preferred for new non-component files, existing camelCase stays as-is. - Comments: default to none; explain why, not what. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
📋 Review SummaryThis PR adds a new "Working Principles" section to AGENTS.md, introducing the "Simplicity First" principle (adapted from Andrej Karpathy's CLAUDE.md) as the lead guiding principle for AI-assisted contributions. It also extends the Code Conventions section with two new entries on file naming and comment density. This is a documentation-only change with no code modifications. 🔍 General Feedback
🎯 Specific Feedback🔵 Low
✅ Highlights
|
Per review feedback, make the source attribution clickable so reviewers can reach the original document in one hop. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
|
Thanks for the review! Triaged below — 1 accepted, 3 respectfully declined. ✅ Accepted
❌ Respectfully declined
TL;DR: three of the four suggestions all push toward "explain the rule with more rules and examples," which is exactly what Simplicity First is meant to push back against. Applying the new principle to the doc that introduces it felt like the most honest thing to do. 中文感谢 review!逐条 triage——1 条采纳,3 条婉拒。 ✅ 已采纳
❌ 婉拒
简而言之: 四条建议里有三条都指向"用更多规则和例子去解释规则",而这恰恰是 Simplicity First 要抵制的。把新原则首先应用到引入它的文档本身,是最诚实的做法。 |
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 Review — ULTRA_LIGHTPreflight triage decided this PR does not need a deep review. Rationale: Pure docs change to AGENTS.md: all 5 blast-radius dimensions false, no runtime/API/build/data impact
Reply Reviewed by |
Raise the bar for code comments from "add sparingly" to "default to none" in the runtime prompt, matching the AGENTS.md convention. Add a preservation clause to AGENTS.md so agents do not strip existing high-value comments during cleanup passes. Update snapshots. Co-Authored-By: Qwen Code <noreply@alibaba-inc.com>
Qwen Code Review (LIGHT)What this PR does: Adds a "Working Principles" section (led by Simplicity First, adapted from Karpathy's CLAUDE.md) and two new Code Conventions entries (file naming, comments) to Findings: No issues found in the visible diff at this tier. The three-file change is self-consistent: the Qwen Code |
- Reorganize PR template around a Reviewer Test Plan section with How to verify, Before/After, and Tested on - Add collapsible Chinese description section for bilingual PRs - Simplify create-pr command guidance to match the new template - Tighten AGENTS.md file naming and comments conventions; align PR submission guide with the new template This makes PRs easier to review by focusing contributors on the evidence reviewers need most.
…Chinese translation - Consolidate Before and After sections into a single Evidence (Before & After) section - Update Chinese summary comment to require full paragraph-by-paragraph translation instead of abbreviated bullets This reduces template redundancy for non-UI changes and ensures the Chinese block is a proper translation, not a summary.
What this PR does
This PR does two things. First, it adds a new Working Principles section to
AGENTS.md— anchored by Simplicity First, adapted from Andrej Karpathy's CLAUDE.md — and establishes two new Code Conventions entries: file naming (kebab-casefor new non-component files; don't rename existing ones) and comment density (default to none; add only when the why cannot be conveyed through naming). The comments guidance is then synced into the runtime system prompt inprompts.ts, with 15 snapshot tests updated accordingly.Second, it restructures the PR template itself: the old multi-section format (Summary / Validation / Scope-Risk / Testing Matrix) is replaced with a single-flow Reviewer Test Plan structure (How to verify / Evidence / Tested on), and a collapsible Chinese summary block is added for bilingual collaboration.
Why it's needed
These preferences have shaped how AI-assisted contributions work in this repo for a long time, but they were never written down. Codifying them keeps future agent runs aligned with maintainer expectations and gives reviewers a clearer bar to hold PRs to. Simplicity First in particular is the principle the maintainers care about most — it's the one that most directly prevents the over-engineering that LLM agents default to.
The comments guidance tightening matters for a specific reason: "sparingly" is too loose for LLM agents whose prior is biased toward adding comments. "Default to none" flips that default and forces each comment to justify itself.
The PR template restructure addresses a different problem: the old format had too many sections that contributors either left empty or filled with low-signal content. The new template focuses reviewers on the evidence they actually need.
Reviewer Test Plan
How to verify
Read the diff — 4 commits across 5 files (
AGENTS.md,prompts.ts, snapshot file, PR template, create-pr command). Key things to confirm:AGENTS.mdrenders correctly on GitHub: the new "Working Principles" section appears above "Common Commands", with the Karpathy attribution link working.prompts.tswording matches theAGENTS.mdguidance — both say "Default to none" for comments..github/pull_request_template.md) renders with all new sections: Reviewer Test Plan (How to verify / Evidence / Tested on), Risk & Scope, Linked Issues, and the<details>Chinese block..qwen/commands/qc/create-pr.mdguidance is consistent with the new template.Snapshot test verification:
Evidence (Before & After)
N/A — this is a docs and template change, no user-visible TUI behavior affected.
Tested on
Environment (optional)
npx vitest runfrompackages/coreon macOS — 60/60 tests passed, 15 snapshots updated to match the newprompts.tswording.Risk & Scope
kebab-casewill coexist with the existingcamelCasetree (~1000+ files). The guidance explicitly tells contributors NOT to rename existing files, preservinggit blamecontinuity and import paths.prompts.tschange is a wording-only update to the runtime system prompt with no API or behavioral impact. The PR template restructure replaces the old format; existing open PRs are unaffected.Linked Issues
None.
中文说明
本 PR 做了什么
本 PR 做了两件事。第一,在
AGENTS.md中新增了 Working Principles 章节——以 Simplicity First 为首,改编自 Andrej Karpathy 的 CLAUDE.md——同时建立两条新的 Code Conventions 条目:文件命名(新的非组件文件用kebab-case;不要重命名已有文件)和注释密度(默认为空;只有当"为什么"无法通过命名传达时才添加)。注释规范随后同步更新到了prompts.ts中的 runtime system prompt,对应的 15 个快照测试也一并更新。第二,重构了 PR 模板本身:旧的多段式格式(Summary / Validation / Scope-Risk / Testing Matrix)被替换为单流程的 Reviewer Test Plan 结构(How to verify / Evidence / Tested on),并新增了可折叠的中文说明区块,用于双语协作。
为什么需要这个改动
这些偏好已经隐性指导了本仓库的 AI 辅助贡献方式很长时间,但从未正式文档化。将它们写下来可以让未来的 agent 运行与 maintainer 的预期保持一致,也给 reviewer 提供更清晰的评判标准。Simplicity First 尤其重要——它是 maintainer 最看重的原则,因为它最直接地防止了 LLM agent 默认的过度工程化倾向。
注释规范的收紧有一个具体原因:"sparingly"(少量添加)对 LLM agent 来说太宽松了,因为它们的先验倾向就是添加注释。"Default to none"(默认为空)翻转了这个默认行为,迫使每条注释都必须自我证明其存在的合理性。
PR 模板重构解决的是另一个问题:旧格式有太多段落,贡献者要么留空,要么填入低信号内容。新模板把 reviewer 实际需要的证据放在了最前面。
Reviewer 测试计划
如何验证
读 diff 即可——4 个 commit,涉及 5 个文件(
AGENTS.md、prompts.ts、快照文件、PR 模板、create-pr 命令)。需要确认的关键点:AGENTS.md在 GitHub 上渲染正确:新的 "Working Principles" 章节出现在 "Common Commands" 上方,Karpathy 署名链接可点击。prompts.ts的措辞与AGENTS.md中的规范一致——两处都写了 "Default to none"。.github/pull_request_template.md)渲染后各新章节完整:Reviewer Test Plan(How to verify / Evidence / Tested on)、Risk & Scope、Linked Issues、以及<details>中文区块。.qwen/commands/qc/create-pr.md的指引与新模板一致。快照测试验证:
前后对比证据
N/A——这是文档和模板改动,没有用户可见的 TUI 行为变化。
测试环境
运行环境(可选)
在 macOS 上从
packages/core运行npx vitest run——60/60 测试通过,15 个快照已同步更新以匹配新的prompts.ts措辞。风险与范围
kebab-case将与现有的camelCase文件树共存(约 1000+ 个文件)。规范明确告知贡献者不要重命名已有文件,以保留git blame的连续性和 import 路径。prompts.ts的改动仅涉及 runtime system prompt 的措辞更新,无 API 或行为影响。PR 模板重构替换了旧格式;已打开的 PR 不受影响。关联 Issue
无。
🤖 Generated with Qwen Code