📄 修正 AGENTS.md 与 develop.md 中的过期事实与措辞歧义#1611
Open
cyfung1031 wants to merge 7 commits into
Open
Conversation
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
cyfung1031
marked this pull request as draft
July 18, 2026 01:29
- docs/develop.md：两处 "react/jsx-no-literals: warn" 均为过期表述，
eslint.config.mjs 实际配置为 "error"；一并改为不重复硬编码 locale
数量/列表，改为指向 docs/translation.md 这一权威来源，避免该计数
再次漂移（此前已从 8 漂移到 9）。
- AGENTS.md：
- 将 "apply to every code change" 的整体范围限定去掉，改为按条目
各自标注适用范围——原有的"every code change"表述本身仍会把 TDD
要求错误地套用到行为保持型重构、类型清理、配置/依赖变更、死代码
删除、机械改名等不需要先写失败测试的改动上；同时又可能让"Scope
discipline"这类本应通用于文档/翻译/配置改动的原则被误读为仅限
代码改动。现改为 TDD 条目自带范围说明，其余条目不再受统一限定词
约束。
- "If a test fails, fix the code, not the test" 的例外表述中
"tautological"归类有误——重言式测试通常恒为真，不会"失败"，因此
不适合作为"测试失败时可能是测试本身错了"的例子；已改为区分两类
不同情况：测试失败因其自身断言的契约有误（应修正测试）、与测试
从一开始就不该存在因而应主动清理（不依赖是否失败）。
- "Confirm before you fix" 补充：并非所有复现都需要走
docs/verification.md 的浏览器端 scratch-script 流程——纯逻辑/解析
/工具函数类 bug 用最小的失败单元测试复现即可，只有依赖真实扩展、
浏览器 API 或跨上下文行为的 bug 才需要该工作流。
- 新增的"详细指南不放在 AGENTS.md、避免重复"表述与文件末尾仍保留
的 ESLint 规则详细清单（含插件命名空间、精确文件范围、harness 覆盖
情况）直接冲突——已在该清单前补充一句说明：这是有意为之的窄范围
例外，因为这些规则由 lint/测试机制强制执行，不会像纯文字文档那样
悄悄漂移。
- docs/design.md 的阅读触发条件从嵌在 "UI stack" 段落中的被动陈述，
提升为与其他四条文档提示同级的顶部 "Before X, read Y" 引用块（并把
UI stack 段落中原本重复的触发语句删除，避免两处各说一次）。
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
TDD 例外原按"config/dependency changes"整类豁免失败测试要求，但此类 改动本身可能改变可观察行为（解析器升级修复缺陷、打包配置影响产物、 manifest/permission 变更）；改为以"是否改变可观察行为"作为判断标准， 并给出反例防止被当作豁免借口。 ESLint 规则清单此前声称"lint/tests 强制执行，不会像文档一样悄悄漂移"， 但该清单本身是人工维护的 prose（哪条规则覆盖什么范围、哪些测试验证 它），lint 只强制规则本身的行为，不强制这段描述的准确性——本 PR 上一轮 就是在修正这段描述的过期内容，这本身就反驳了"不会漂移"的说法。改为 明确该清单仍是需要用 grep 复核的陈述，而非既定事实。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
TDD/Confirm-before-you-fix 此前对"改变可观察行为"的改动一律要求先写 失败测试，未考虑纯视觉/动画调整、仅特定浏览器版本或扩展生命周期阶段 才能复现的问题、文案/翻译改动、无法可靠自动化的平台行为等场景——这类 改动缺乏可行的自动化覆盖手段，硬性要求容易诱导写空跑/不稳定的低价值 测试，与 develop-testing.md 反对无价值测试的既有规则冲突。补充第二类 例外：改用 docs/verification.md 的人工验证并记录证据。 design.md 触发提示（AGENTS.md、docs/develop.md、docs/design.md 自身 开头）此前均写"建任意新 page/dialog/block 前读"，但 design.md 的 Core Constraints 一节明确"every UI change must satisfy all of these" ——范围比"新建"更广，修改已有 UI 同样适用。三处触发文字统一改为 "building or modifying"，消除范围不一致。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
AGENTS.md 此前新增的失败测试例外未同步到 docs/verification.md 与 docs/references/develop-testing.md：verification.md 仍无条件要求 "scratch reproduction 必须晋升为已提交的失败测试"，develop-testing.md 仍无条件写"write failing tests before implementation"，AGENTS.md 自身 "确定 bug 存在 → 写测试 → 修复"的中文摘要也未反映新例外——三处对"失败 测试是否强制"给出不同答案。已让 verification.md/develop-testing.md 改为指向 AGENTS.md 作为该策略的唯一权威（不再各自重复并可能过期的 断言），中文摘要补上"或记录验证证据"分支。 ESLint 自定义规则清单（规则名、范围、harness 覆盖情况）此前直接嵌在 AGENTS.md 里，与文件开头"keeps only the non-negotiable engineering principles and the architecture map"的范围声明矛盾，且是本 PR 反复 被指出"新增文本过多、应下放到其他文档"的主要来源。已整体迁移到 docs/develop.md 新增的 "ESLint custom rules" 小节（该文档本就是 "concrete how"的权威归属），AGENTS.md 改为四行指针，不再需要额外的 "例外"措辞。 TDD 第二类例外（自动化覆盖不可行）此前一律指向 docs/verification.md 的浏览器扩展 scratch-script 工作流，但该工作流是为依赖真实扩展/浏览器 API 的场景设计的，对纯文案/翻译改动而言过重——已改为按是否需要真实 扩展区分：需要时用该工作流，否则用更轻量的记录说明即可。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Engineering Principles 一节里 "Fix root causes"、"Confirm before you fix"、"TDD/BDD first" 三条经过五轮修正，逐条累积了大量例外场景与反例 说明，成为 AGENTS.md（每次会话都会加载）里最重的部分。这些例外/反例 本质上是"如何执行"的机制细节，而非不可协商的原则本身，按 AGENTS.md 自己的所有权声明应归属专属文档： - "Fix root causes" 的测试例外（契约本身有误 / 从未有价值）细节迁移 到 docs/references/develop-testing.md 的 "Writing meaningful tests" 小节开头，AGENTS.md 保留原则本身 + 一处指针。 - "Confirm before you fix" 的复现方式选择（单元测试 vs 扩展级 scratch-script）迁移到 docs/verification.md，该文档本就以复现 bug 为职责范围。 - "TDD/BDD first" 的两类例外（行为保持型改动；自动化覆盖不可行）整段 迁移到 docs/references/develop-testing.md 新增的 "When TDD doesn't apply" 小节。 AGENTS.md 该节三条从长段落收窄为原则 + 指针，文件总字节数减少约 12%（10347 → 9132 字节），例外内容本身未删减，只是搬到了各自的所有权 文档，不损失约束力（harness）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
"a scratch reproduction... is not itself the required test or evidence" 此前无条件表述，但 AGENTS.md 的自动化覆盖不可行例外场景下 scratch 复现（report.md、截图、观察记录）本身就是要求的证据——两处 表述冲突。已补充"一般情况下"限定，并明确例外场景下 scratch 复现即为 所需证据，无需再补一个已提交的测试。 同时修正所有权表述："该策略（含其例外）归属 AGENTS.md" 已不准确—— 例外细节在上一轮迁移到了 docs/references/develop-testing.md，AGENTS.md 只保留原则本身。改为分别说明两份文档各自的所有权范围。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
cyfung1031
marked this pull request as ready for review
July 18, 2026 02:20
This was referenced Jul 18, 2026
Collaborator
Author
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
1 participant
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.
Checklist / 检查清单
背景
在 #1610 修复
AGENTS.md中 PR 描述规范提示的可见度问题后，收到提示"检查AGENTS.md其余内容是否有类似问题"。逐条核对AGENTS.md全文后发现若干过期事实与措辞歧义（第一轮改动），随后收到六轮对改动本身的审阅意见，指出前一轮改动引入或未完全解决的问题（第二至七轮改动）。全部条目均已按docs/DOC-MAINTENANCE.md的规则重新对照代码库验证，不直接采信未经验证的外部结论。本次改动
第一轮：过期事实与触发/所有权歧义
AGENTS.md："Key Packages" 中filesystem/被描述为 "(WebDAV + local)"，但packages/filesystem/factory.ts中实际的FileSystemType并无 "local" 选项（实为zip | webdav | baidu-netdsik | onedrive | googledrive | dropbox | s3）——改为准确描述并链接到docs/cloud-sync.md。AGENTS.md："All four syntax-based harness rules are covered byeslint-rules/harness.test.mjs" 具有误导性：该文件实际只覆盖no-i18n-default-value、no-raw-color-classname、no-restricted-imports的radix-ui模式、no-restricted-syntax四项，require-last-error-check（列表中排最前、最易被误认为已覆盖）与no-restricted-imports的sonner模式均未被覆盖——已用grep确认该文件全文无相关字样，改为明确列出实际覆盖与未覆盖的项目，并补上require-last-error-check缺失的chrome-error/插件命名空间前缀。docs/develop.md："8 locales" 但src/locales/下实际有 9 个语言目录（遗漏pt-BR）。AGENTS.md：docs/design.md的阅读触发条件写作"建任意 page 前"，但docs/design.md/docs/develop.md自身都写"page, dialog, or block"——三处范围不一致，已统一。AGENTS.md："single source of truth"/"put all guidance here" 的表述容易与docs/DOC-MAINTENANCE.md的所有权模型混淆——已明确该句是相对CLAUDE.md而言。AGENTS.md："If a test fails, fix the code, not the test" 的绝对化表述与docs/references/develop-testing.md允许清理无价值测试的既有规则存在潜在冲突——补充窄化例外。AGENTS.md："apply to every change" 改为 "every code change"，并补充docs/verification.md/Confirm before you fix的连接、DEVELOP.md/DESIGN.md大小写不一致修正。第二轮：对第一轮改动本身的修正
docs/develop.md：Coding Style 与 i18n 两处仍写 "react/jsx-no-literals: warn"，但eslint.config.mjs实际为"error"——这是第一轮"已核对 eslint.config.mjs"这一说法本身的反例，已修正两处措辞。docs/develop.md：不再硬编码 locale 数量/列表，直接指向docs/translation.md，从根源上避免再次漂移。AGENTS.md："apply to every code change" 对 TDD 而言范围过宽、对 Scope discipline 而言范围过窄——改为不再用统一限定词覆盖整节，TDD 条目自带精确范围说明。AGENTS.md：docs/design.md触发提示提升为独立顶部引用块，删除 UI stack 段落中重复的触发语句。AGENTS.md："Confirm before you fix" 补充区分：纯逻辑/解析/工具函数类 bug 用单元测试复现，依赖真实扩展/浏览器 API/跨上下文行为时才需要docs/verification.md的 scratch-script 工作流。AGENTS.md："fix the code, not the test" 例外拆分为两类：契约有误（应修正测试）与从一开始就不该存在（应主动清理，与是否失败无关）。第三轮：对第二轮新增表述本身的修正
AGENTS.md：TDD 例外从"config/dependency changes"整类豁免，改为以"是否改变可观察行为"为判断标准（标题改为 "for changes that alter observable behavior"），避免解析器升级、bundler 配置变更等实际改变行为的改动被错误跳过测试。AGENTS.md：ESLint 规则清单引导句移除"lint/tests 强制执行所以不会像文档一样漂移"的说法——第二轮修正的正是这段描述自己的过期内容，这本身反驳了"不会漂移"。第四轮：TDD 遗漏"自动化覆盖不可行"例外、design.md 触发范围仍限于"新建"
AGENTS.md：补充 TDD 第二类例外——纯视觉/动画调整、仅特定浏览器版本或生命周期阶段才能复现的问题、文案/翻译改动、无法可靠自动化的平台行为，改用人工验证并记录证据，明确不得为满足本条而提交低价值测试。AGENTS.md、docs/develop.md、docs/design.md：design.md 触发范围从"新建"统一改为"新建或修改"，与该文档 Core Constraints 一节"every UI change"的实际范围对齐。第五轮：token 效率、TDD 三文档冲突、验证工作流适配范围（基于新一轮审阅意见，逐条核实后采纳）
AGENTS.md（每次会话都会加载的文件）持续新增大量文本，多数应下放到其他专属文档而不损失 harness 效果。已将占用最多篇幅的 ESLint 自定义规则清单（规则名、范围、harness.test.mjs覆盖情况，约 9 行密集内容）整体迁移到docs/develop.md新增的 "ESLint custom rules" 小节——该文档本就是AGENTS.md自称"concrete how"的权威归属。AGENTS.md对应位置改为 4 行指针，AGENTS.md总行数相比上一轮净减少。同时不再需要"这是有意为之的窄范围例外"这类说明性文字，因为详细内容已不在AGENTS.md里。AGENTS.md已定义"自动化覆盖不可行时可用验证证据替代失败测试"的例外，但docs/verification.md仍无条件断言"scratch reproduction 必须晋升为已提交的失败测试"，docs/references/develop-testing.md仍无条件写"write failing tests before implementation"，AGENTS.md自身"确定 bug 存在 → 写测试 → 修复"的中文摘要也未反映新例外——按读到哪份文档，代理会得出不同结论，这正是本 PR 意在减少的跨文档漂移。已让verification.md/develop-testing.md不再各自重复并可能过期地断言该策略的具体内容，改为指向AGENTS.md作为唯一权威；AGENTS.md中文摘要补上"或记录验证证据"分支。AGENTS.md"keeps only" 与 ESLint 详细清单的矛盾：随上一条 ESLint 清单迁出AGENTS.md一并解决——"This file keeps only the non-negotiable engineering principles and the architecture map" 现在是准确陈述，无需额外的例外措辞，也与docs/DOC-MAINTENANCE.md所有权表中AGENTS.md一行的描述重新保持一致（此前"已知限制"记录的这一条已随之消失）。docs/verification.md的扩展级 scratch-script 工作流，对文案/翻译改动等简单场景过重：已改为按是否需要真实扩展/浏览器 API 区分——需要时用该工作流，否则用更轻量的记录说明即可，不再一律套用面向浏览器扩展集成场景设计的完整流程。第六轮：Engineering Principles 仍偏重，例外细节下放到专属文档（基于新一轮审阅意见，逐条核实后采纳）
Fix root causes、Confirm before you fix、TDD/BDD first三条经五轮修正累积了大量例外场景与反例说明，是该节最重的部分。已将例外细节按各自所有权迁移：Fix root causes的测试例外（契约本身有误 / 从未有价值）迁移到docs/references/develop-testing.md的 "Writing meaningful tests" 小节开头。Confirm before you fix的复现方式选择（单元测试 vs 扩展级 scratch-script）迁移到docs/verification.md（该文档本就以复现 bug 为职责范围）。TDD/BDD first的两类例外整段迁移到docs/references/develop-testing.md新增的 "When TDD doesn't apply" 小节。AGENTS.md三条对应位置收窄为"原则本身 + 一处指针"，文件字节数相比上一轮再减少约 12%（10347 → 9132 字节），例外内容未删减，只是搬到了各自的所有权文档。第七轮：verification.md 中 scratch 证据与例外的措辞歧义（非阻断，基于新一轮审阅意见，逐条核实后采纳）
docs/verification.md："a scratch reproduction... is not itself the required test or evidence" 无条件表述，但在AGENTS.md的自动化覆盖不可行例外场景下，scratch 复现（report.md、截图、观察记录）本身就是要求的证据——docs/references/develop-testing.md的 "When TDD doesn't apply" 小节也支持这一解读。已补充"一般情况下"限定，并明确例外场景下 scratch 复现即为所需证据，无需再补一个已提交的测试。docs/verification.md："该策略（含其例外）归属AGENTS.md" 在第六轮例外细节迁出AGENTS.md后已不准确——已改为分别说明：AGENTS.md拥有原则本身，docs/references/develop-testing.md拥有例外判定标准。已知限制
docs/architecture.md新增多个触发回调块）——改动范围更大、收益不确定，留待后续按需评估。建议审查重点
docs/verification.md新增的"一般情况 vs 例外情况证据要求不同"表述，是否与docs/references/develop-testing.md的例外判定标准完全对齐，不会出现"符合哪条例外"本身产生新的跨文档分歧。AGENTS.md三条原则收窄为"原则 + 指针"后，是否仍能在不点开链接的情况下让代理理解约束的边界，还是必须打开docs/references/develop-testing.md/docs/verification.md才能正确执行。docs/references/develop-testing.md新增的 "When TDD doesn't apply" 小节与 "Writing meaningful tests" 开头新增的契约区分说明，措辞是否与AGENTS.md迁移前的原文一致，没有在搬运过程中引入新的表述漂移。docs/develop.md后，AGENTS.md的 4 行指针是否仍能让代理在需要时快速找到细节，而不必先读完整个develop.md。docs/verification.md/docs/references/develop-testing.md改为指向AGENTS.md作为 TDD 策略唯一权威后，是否遗漏了这两份文档原本承担的、AGENTS.md不适合覆盖的机制性说明（例如 scratch-script 具体怎么写、测试文件放在哪）。关联
AGENTS.md中 PR 描述规范提示的可见度与措辞），本 PR 是对AGENTS.md其余内容的后续审计。两个 PR 都改动AGENTS.md，但改动的段落不重叠。验证
docs/DOC-MAINTENANCE.md自带的链接完整性检查脚本每轮改动后均本地执行，全部链接可解析，无BROKEN输出（第五轮改动含docs/verification.md中一处链接文本调整，已确认解析正常）。git grep/git ls-tree确认filesystem/实际 provider 列表、harness.test.mjs实际覆盖的规则、chrome-error//scriptcat/插件命名空间前缀、src/locales/实际的 9 个语言目录、eslint.config.mjs中react/jsx-no-literals的实际级别。grep -n "does not replace\|committed failing test\|scratch reproduction" docs/verification.md与grep -n "write failing tests\|failing test" docs/references/develop-testing.md确认两处此前均为无条件表述，与AGENTS.md当前例外确实矛盾。wc -l AGENTS.md确认第五轮改动后AGENTS.md总行数相比上一轮净减少（ESLint 清单迁出的行数多于本轮新增行数）。wc -c AGENTS.md（改动前后对比git show <上一轮commit>:AGENTS.md | wc -c）确认字节数从 10347 降至 9132；docs/DOC-MAINTENANCE.md链接完整性检查脚本改动后本地执行，全部链接可解析，无BROKEN输出。sed -n '1,35p' docs/verification.md重读改动前原文，确认"is not itself the required test or evidence"确无限定词、且与例外场景矛盾，改动后再次执行链接完整性检查脚本，无BROKEN输出。git commit触发的预提交钩子（lint-staged）因每轮改动仅涉及.md文件而跳过 JS/TS 相关检查。