From 4a6d8f7eff583cc6c78e0d7af403a15e4ef6bf90 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:26:37 +0900 Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=93=84=20=E6=8F=90=E5=8D=87=20PR=20?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=E8=A7=84=E8=8C=83=E7=9A=84=E5=8F=AF=E8=A7=81?= =?UTF-8?q?=E5=BA=A6=EF=BC=8C=E9=98=B2=E6=AD=A2=E4=BB=A3=E7=90=86=E9=BB=98?= =?UTF-8?q?=E8=AE=A4=E5=9B=9E=E9=80=80=E5=88=B0=E9=80=9A=E7=94=A8=E6=A8=A1?= =?UTF-8?q?=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 10 ++++++---- docs/DOC-MAINTENANCE.md | 2 +- docs/pull-request.md | 6 ++++++ 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 63d90e238..2a4c939fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,12 @@ This file provides guidance to AI coding agents (Claude Code, etc.) when working > current, no duplication) and every claim factually true against the current branch (*if you can't grep it on > this branch, don't claim it*). +> **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — the +> required description structure (checklist, 背景/本次改动/已知限制/建议审查重点/验证, etc.), not a generic +> `## Summary` / `## Test plan` template. Re-check this at PR-creation time specifically — by then "read the +> docs at task start" is easy to have deprioritized, and a generic template is an easy default to reach for +> instead. Never claim human review, testing, or verification that did not happen. + > **Doc map:** [`docs/README.md`](docs/README.md) indexes every contributor doc (development, architecture, > translation, contributing, localized READMEs). @@ -99,7 +105,3 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of > Two conventions are enforced via built-in rules in `eslint.config.mjs`: `no-restricted-imports` bans `@radix-ui/react-*` single packages (use the merged `radix-ui`) and the `sonner` `toast` export (use `notify`); `no-restricted-syntax` bans `forwardRef` across `src/pages/**` (use React 19 `function` + ref-prop). All four syntax-based harness rules are covered by `eslint-rules/harness.test.mjs`. > > Separately, type-aware rules run on `src/pages/**` (tests excluded) via `projectService` — `@typescript-eslint/no-floating-promises`, `no-misused-promises` (with `checksVoidReturn.attributes: false`, so `async` JSX handlers are allowed), and `await-thenable`, all `error` — to catch missing `await`s and promises misused as void callbacks. These need type information, so they are *not* part of `harness.test.mjs`. - -## Pull Request Description Format - -Detailed PR description guidance lives in [`docs/pull-request.md`](docs/pull-request.md). Start from the human-facing template, preserve its checklist, and expand the description only when the change needs more context. Do not claim human review or other evidence that did not happen. diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md index 64679645e..990b64a11 100644 --- a/docs/DOC-MAINTENANCE.md +++ b/docs/DOC-MAINTENANCE.md @@ -100,7 +100,7 @@ git ls-files eslint-rules/; git grep -l "require-last-error-check" -- eslint.con Link integrity — confirm every relative markdown link in the core docs resolves: ```bash -for doc in AGENTS.md docs/README.md docs/DOC-MAINTENANCE.md docs/develop.md docs/references/develop-testing.md docs/design.md docs/references/design-tokens.md docs/references/design-components.md docs/references/design-patterns.md docs/architecture.md docs/references/architecture-services.md docs/references/architecture-data.md docs/references/architecture-gm-api.md docs/references/architecture-execution.md docs/references/architecture-build.md docs/verification.md docs/references/verification-debugging.md docs/references/verification-report-template.md docs/cloud-sync.md docs/translation.md; do +for doc in AGENTS.md docs/README.md docs/DOC-MAINTENANCE.md docs/develop.md docs/references/develop-testing.md docs/pull-request.md docs/design.md docs/references/design-tokens.md docs/references/design-components.md docs/references/design-patterns.md docs/architecture.md docs/references/architecture-services.md docs/references/architecture-data.md docs/references/architecture-gm-api.md docs/references/architecture-execution.md docs/references/architecture-build.md docs/verification.md docs/references/verification-debugging.md docs/references/verification-report-template.md docs/cloud-sync.md docs/translation.md; do # the sed pipeline drops fenced code blocks and inline code spans first, so illustrative sample # links inside ```md snippets or `single-backtick` text (e.g. references/verification-report-template.md's # screenshot/resource examples, verification.md's "Evidence location" spans) aren't false-flagged as broken diff --git a/docs/pull-request.md b/docs/pull-request.md index b3e4ce25c..0ed24c4bc 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -2,6 +2,12 @@ This guide defines the detailed PR description format for agents and contributors. The human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) intentionally remains lightweight; use it as the starting point and expand its `Description / 描述` section when the change needs more context. +**Do not fall back to a generic `## Summary` / `## Test plan` template.** That structure is a common +default many coding agents reach for out of habit (it is even the literal example baked into some +agent tool descriptions for "creating a pull request") — it is not this repo's format. A PR opened +against this repo with that generic structure has already skipped the checklist below; if you notice +you are about to write `## Summary`, stop and use the structure in *Recommended structure* instead. + ## Recommended structure For a normal feature or behavior change, use the following sections when they are meaningful: From df2fe4bbffbec3030420f35c0e86dc3598680ebd Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:31:26 +0900 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=93=84=20=E7=B2=BE=E7=AE=80=20PR=20?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=E8=A7=84=E8=8C=83=E6=8F=90=E7=A4=BA=E7=9A=84?= =?UTF-8?q?=E6=8E=AA=E8=BE=9E=EF=BC=8C=E9=81=BF=E5=85=8D=E5=AF=B9=E4=B8=AA?= =?UTF-8?q?=E4=BA=BA=E7=BB=8F=E5=8E=86=E7=9A=84=E8=BF=87=E5=BA=A6=E5=8F=99?= =?UTF-8?q?=E4=BA=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按体量、语气对齐 AGENTS.md 中另外四条 "Before X, read Y" 提示——本条 此前偏重叙述本次遗漏的具体成因，不利于作为面向所有代理的通用规范； 现改为与其余提示一致的简洁祈使句。docs/pull-request.md 开头的反模式 提示同样精简。 Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 6 ++---- docs/pull-request.md | 7 ++----- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2a4c939fe..4e743ead8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,10 +23,8 @@ This file provides guidance to AI coding agents (Claude Code, etc.) when working > this branch, don't claim it*). > **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — the -> required description structure (checklist, 背景/本次改动/已知限制/建议审查重点/验证, etc.), not a generic -> `## Summary` / `## Test plan` template. Re-check this at PR-creation time specifically — by then "read the -> docs at task start" is easy to have deprioritized, and a generic template is an easy default to reach for -> instead. Never claim human review, testing, or verification that did not happen. +> required PR description structure. Do not default to a generic `## Summary` / `## Test plan` template. Never +> claim human review, testing, or verification that did not happen. > **Doc map:** [`docs/README.md`](docs/README.md) indexes every contributor doc (development, architecture, > translation, contributing, localized READMEs). diff --git a/docs/pull-request.md b/docs/pull-request.md index 0ed24c4bc..079bec7e1 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -2,11 +2,8 @@ This guide defines the detailed PR description format for agents and contributors. The human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) intentionally remains lightweight; use it as the starting point and expand its `Description / 描述` section when the change needs more context. -**Do not fall back to a generic `## Summary` / `## Test plan` template.** That structure is a common -default many coding agents reach for out of habit (it is even the literal example baked into some -agent tool descriptions for "creating a pull request") — it is not this repo's format. A PR opened -against this repo with that generic structure has already skipped the checklist below; if you notice -you are about to write `## Summary`, stop and use the structure in *Recommended structure* instead. +**Do not use a generic `## Summary` / `## Test plan` template** — that's a common default baked into +many agent tool instructions, not this repo's format. Use the structure below instead. ## Recommended structure From f0c8b1d5a9dc4dbf3f48f3e3d4482d8a77ce6d38 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:33:30 +0900 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=93=84=20=E8=A1=A5=E5=9B=9E=20"preser?= =?UTF-8?q?ve=20its=20checklist"=20=E7=9A=84=E6=8E=AA=E8=BE=9E=EF=BC=8C?= =?UTF-8?q?=E6=9C=AA=E9=9A=8F=E5=8E=9F=20AGENTS.md=20=E5=B0=8F=E8=8A=82?= =?UTF-8?q?=E4=B8=80=E5=B9=B6=E8=BF=81=E7=A7=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除 AGENTS.md 末尾旧小节时，"preserve its checklist" 这一细节未一并 转移到 docs/pull-request.md——原文仅隐含在"推荐结构"示例中包含 Checklist 小节，但没有明确写出"必须保留"这条规则。现补充到文首段落。 Co-Authored-By: Claude Sonnet 5 --- docs/pull-request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pull-request.md b/docs/pull-request.md index 079bec7e1..c1a4febad 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -1,6 +1,6 @@ # Pull Request Description Guide -This guide defines the detailed PR description format for agents and contributors. The human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) intentionally remains lightweight; use it as the starting point and expand its `Description / 描述` section when the change needs more context. +This guide defines the detailed PR description format for agents and contributors. Start from the human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when the change needs more context. **Do not use a generic `## Summary` / `## Test plan` template** — that's a common default baked into many agent tool instructions, not this repo's format. Use the structure below instead. From 87b0ad3f90a42b9b11114997ed467a3b51cbcd94 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:43:51 +0900 Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=93=84=20=E6=B6=88=E9=99=A4=20require?= =?UTF-8?q?d/recommended=20=E7=9F=9B=E7=9B=BE=E8=A1=A8=E8=BF=B0=EF=BC=8C?= =?UTF-8?q?=E8=BD=AF=E5=8C=96=E6=A0=87=E9=A2=98=E5=90=8D=E7=A6=81=E4=BB=A4?= =?UTF-8?q?=EF=BC=8C=E5=8E=BB=E9=87=8D=E5=A4=8D=E8=BF=B0=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md 不再声称该结构是 "required"——与 docs/pull-request.md 自身 "recommended, not mandatory headings" 的表述直接矛盾；改为不对合规 级别下结论，完全交由 docs/pull-request.md 定义。 - docs/pull-request.md 中对通用 ## Summary / ## Test plan 标题的禁令 软化为"信号"表述，避免过度针对具体英文标题字面量（真正的问题是未查阅 本指南，不是这两个词本身），并删除"许多代理工具都内置此模板"这一 无法对照当前分支验证的元评论。 - 移除 AGENTS.md 中复述 docs/pull-request.md 已有规则（"Never claim human review..."）的句子，遵循 DOC-MAINTENANCE.md 的不重复原则。 Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 5 ++--- docs/pull-request.md | 5 +++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4e743ead8..2830e3651 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,9 +22,8 @@ This file provides guidance to AI coding agents (Claude Code, etc.) when working > current, no duplication) and every claim factually true against the current branch (*if you can't grep it on > this branch, don't claim it*). -> **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — the -> required PR description structure. Do not default to a generic `## Summary` / `## Test plan` template. Never -> claim human review, testing, or verification that did not happen. +> **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — this +> repo's PR description structure and evidence rules, not a generic `## Summary` / `## Test plan` template. > **Doc map:** [`docs/README.md`](docs/README.md) indexes every contributor doc (development, architecture, > translation, contributing, localized READMEs). diff --git a/docs/pull-request.md b/docs/pull-request.md index c1a4febad..2dbdc3bd2 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -2,8 +2,9 @@ This guide defines the detailed PR description format for agents and contributors. Start from the human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when the change needs more context. -**Do not use a generic `## Summary` / `## Test plan` template** — that's a common default baked into -many agent tool instructions, not this repo's format. Use the structure below instead. +A description using only generic `## Summary` / `## Test plan` headings is a sign this guide wasn't +consulted. Use the structure below instead — its sections are recommended, not all mandatory (see below +for which ones). ## Recommended structure From 99b7fc08ec4a23bcc01262db00a7ce091ddb1b4a Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:52:50 +0900 Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=93=84=20=E7=94=A8=E5=8F=AF=E9=AA=8C?= =?UTF-8?q?=E8=AF=81=E7=9A=84"=E5=86=85=E5=AE=B9=E8=A6=81=E6=B1=82"?= =?UTF-8?q?=E8=A1=A8=E8=BF=B0=E5=8F=96=E4=BB=A3=E5=AF=B9=E8=B4=A1=E7=8C=AE?= =?UTF-8?q?=E8=80=85=E6=B5=81=E7=A8=8B=E7=9A=84=E4=B8=8D=E5=8F=AF=E9=AA=8C?= =?UTF-8?q?=E8=AF=81=E6=8E=A8=E6=96=AD=EF=BC=8C=E8=A1=A5=E9=BD=90=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E4=B8=8D=E9=80=82=E7=94=A8=E9=A1=B9=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/pull-request.md："使用通用标题即代表未查阅本指南"是对贡献者 流程的推断，无法验证（有人查阅后仍选用同义英文标题，也有人照抄标题 却未真正理解内容）。改为可验证的表述：无论使用何种标题，本指南的 清单与验证信息要求依然适用——标题本身不能豁免这些要求。 - 补充清单项"不适用/未执行时应留空而非改写文字"的规则，此前仅对 "Code reviewed by human"一项有此说明，现推广到整个清单。 - AGENTS.md 中的提示不再复述具体标题示例（## Summary / ## Test plan）， 该示例只保留在 docs/pull-request.md 这一权威来源中，减少未来漂移点。 Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 2 +- docs/pull-request.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2830e3651..0aa78f1fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ This file provides guidance to AI coding agents (Claude Code, etc.) when working > this branch, don't claim it*). > **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — this -> repo's PR description structure and evidence rules, not a generic `## Summary` / `## Test plan` template. +> repo's PR description structure and evidence rules. > **Doc map:** [`docs/README.md`](docs/README.md) indexes every contributor doc (development, architecture, > translation, contributing, localized READMEs). diff --git a/docs/pull-request.md b/docs/pull-request.md index 2dbdc3bd2..59146c0d8 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -2,9 +2,9 @@ This guide defines the detailed PR description format for agents and contributors. Start from the human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when the change needs more context. -A description using only generic `## Summary` / `## Test plan` headings is a sign this guide wasn't -consulted. Use the structure below instead — its sections are recommended, not all mandatory (see below -for which ones). +Whatever headings you use, this guide's checklist and evidence expectations still apply — `## Summary` / +`## Test plan` headings don't exempt a PR from them. Use the structure below; its sections are +recommended, not all mandatory (see below for which ones). ## Recommended structure @@ -52,7 +52,7 @@ For a normal feature or behavior change, use the following sections when they ar `Checklist`、`背景`、`本次改动` and `验证` are the recommended core for a normal feature or behavior change, not mandatory headings for every PR. Add `实现考虑` for meaningful design or concurrency implications; add `已知限制` and `建议审查重点` when reviewers need explicit boundaries or risk areas. `参考` and `关联` are optional. -Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR. +Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR — the same applies to any other checklist item: if it doesn't apply or wasn't done, leave it unchecked rather than rewording it. ## Review-oriented content From c410868864ca612e050d610b9db4abc011019db7 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:59:36 +0900 Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=93=84=20=E5=8C=BA=E5=88=86=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E9=A1=B9"=E4=B8=8D=E9=80=82=E7=94=A8"=E4=B8=8E"?= =?UTF-8?q?=E6=9C=AA=E6=89=A7=E8=A1=8C"=EF=BC=8C=E9=81=BF=E5=85=8D?= =?UTF-8?q?=E4=B8=A4=E7=A7=8D=E7=8A=B6=E6=80=81=E8=A2=AB=E5=90=8C=E4=B8=80?= =?UTF-8?q?=E4=B8=AA=E6=9C=AA=E5=8B=BE=E9=80=89=E7=8A=B6=E6=80=81=E6=B7=B7?= =?UTF-8?q?=E6=B7=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上一版把"不适用"和"应做但未做"统一处理为"留空"，导致审查者（及未来 可能的自动化校验）无法从一个未勾选的框区分这两种含义完全不同的状态。 现按建议方案调整：清单文字保持不变；未执行的项目留空；不适用的项目 除留空外，还需在清单下方补一行简短的 N/A 说明其原因。 Co-Authored-By: Claude Sonnet 5 --- docs/pull-request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pull-request.md b/docs/pull-request.md index 59146c0d8..bac8c4953 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -52,7 +52,7 @@ For a normal feature or behavior change, use the following sections when they ar `Checklist`、`背景`、`本次改动` and `验证` are the recommended core for a normal feature or behavior change, not mandatory headings for every PR. Add `实现考虑` for meaningful design or concurrency implications; add `已知限制` and `建议审查重点` when reviewers need explicit boundaries or risk areas. `参考` and `关联` are optional. -Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR — the same applies to any other checklist item: if it doesn't apply or wasn't done, leave it unchecked rather than rewording it. +Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR — the same applies to any other checklist item: leave it unchecked (without rewording it) whether the work wasn't done or doesn't apply. If an item doesn't apply to this PR, add a brief `N/A — ` note below the checklist, so reviewers can tell "not applicable" from "not done" — an unchecked box alone doesn't distinguish the two. ## Review-oriented content