From 017872bf2b8c4a33ba6bf4b30861c4f665d9fa55 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sat, 5 Sep 2026 13:48:52 +0900 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=84=20=E8=A1=A5=E5=85=85=20Agent=20?= =?UTF-8?q?=E8=87=AA=E4=B8=BB=E6=93=8D=E4=BD=9C=E8=BE=B9=E7=95=8C=E3=80=81?= =?UTF-8?q?=E6=8C=87=E4=BB=A4=E5=86=B2=E7=AA=81=E8=A3=81=E5=86=B3=E4=B8=8E?= =?UTF-8?q?=E4=BA=BA=E7=B1=BB=E5=8F=AF=E8=AF=BB=E5=86=99=E4=BD=9C=E8=A7=84?= =?UTF-8?q?=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现有 agent 文档规定了改动的质量门槛，但缺三层：agent 在两次人工决策之间可以自行做什么、 指令冲突如何裁决、以及写给人看的东西该怎么写。静态审查的依据： 整套文档没有一处把 agent 写成决策者（`decide` 的主语全是分类表或原则），因而产出「建议生成器」； `material` 作为门槛术语被引用九次却从未定义，且在 pull-request.md 内有两种含义； 测试失败例外在 AGENTS.md 概括成两条而 owner 定义了六种；路由表是一次性分类； 人工指令能覆盖什么没有成文；以及全套文档没有任何一条关于行文的规范， 而 pull-request.md 提供的九级标题骨架会被当成表格来填。 本次补齐：范围内自行决策、交还决定须指名归属与阻塞点、不写可查证却不查的保留意见、 指令冲突裁决与人工指令覆盖边界、连续路由、`material` 定义、测试失败例外改交 owner 裁决、 自主操作边界、不稳定结果报告口径、面向人类读者的写作原则、文档集自身的指令预算。 PR 模板补一条不渲染注释；pull-request.md 明确其结构是待考虑项而非待填表格。 Co-Authored-By: Claude Opus 5 --- .github/pull_request_template.md | 4 ++ AGENTS.md | 106 +++++++++++++++++++++++++++++-- docs/DOC-MAINTENANCE.md | 10 +++ docs/develop.md | 6 ++ docs/pull-request.md | 12 +++- 5 files changed, 131 insertions(+), 7 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index db659cc56..7ce7e9d0a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,6 +4,10 @@ - [ ] Code reviewed by human / 代码通过人工检查 - [ ] Changes tested / 已完成测试 + + ## Description / 描述 diff --git a/AGENTS.md b/AGENTS.md index 929d15163..e735bbb38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,14 @@ quick-map; concrete mechanics belong to the routed docs. Compatibility entry poi separate contract. Use [`docs/README.md`](docs/README.md) as the index and follow the owning doc instead of duplicating its rules. +When two instructions collide, the doc that owns the subject wins over a summary of it, a specific rule wins over +a general one, and a narrower exception wins over the default it names. If that still does not settle it, the +collision is itself a finding: take the more conservative reading, say which one you took, and report the conflict +so the doc set can be repaired — do not resolve it silently. A request from the user or a maintainer sets the goal +and authorizes the work, and it can waive a preference; it does not by itself satisfy a rule that this doc set +states as a prohibition. Say so once, in a sentence, and if the request is reaffirmed, carry it out and record it +in the change as a named, accepted deviation — never as compliance. + ## Route the task before acting | Before you… | Read | @@ -18,8 +26,10 @@ duplicating its rules. | manually confirm a feature works | [`docs/verification.md`](docs/verification.md) — drive a throwaway session against the built extension, not the committed suite | For tasks matching multiple rows, read every applicable owner before that work; do not front-load unrelated -docs. For tasks matching none, inspect `docs/README.md` and nearby implementation/tests before inventing a rule -or abstraction. +docs. Routing is continuous, not a classification you make once: when the work turns out to touch a row you did +not match at the start — a rename that crosses a persistence or message boundary, a UI fix that needs a new +entity — read that owner then, before continuing. For tasks matching none, inspect `docs/README.md` and nearby +implementation/tests before inventing a rule or abstraction. ## DeepWiki Context @@ -38,9 +48,11 @@ These are repo-wide defaults. A linked, narrow exception in its owning doc is pa downstream prose does not override it. - **Fix root causes, not symptoms — refactor over patch.** No `as any`, `// @ts-ignore`, swallowed errors, or - defensive skips or try-catch swallowing (宁愿重构也不要打补丁). When a test fails, fix the code rather than the test, except for a wrong - test contract or valueless test as defined in - [`docs/references/develop-testing.md`](docs/references/develop-testing.md#writing-meaningful-tests-what-to-clean-up--not-write). + defensive skips or try-catch swallowing (宁愿重构也不要打补丁). When a test fails, fix the code rather than + the test, and never weaken an assertion to make it pass. Which failures are an exception — an obsolete contract, a + no-value test, a flake, work misclassified as a unit test — is decided by the classification table in + [`docs/references/develop-testing.md`](docs/references/develop-testing.md#cleaning-up-tests-safely), not by this + summary. - **Confirm before fixing.** Reproduce and confirm a reported bug before changing it; capture the reproduction first (确定 bug 存在 → 写测试或记录验证证据 → 修复). Use [`docs/verification.md`](docs/verification.md) and the TDD principle in this section for the evidence standard. @@ -74,6 +86,11 @@ downstream prose does not override it. observations; normative specifications, compatibility contracts, security policies, accepted contracts or oracles, and maintainer decisions determine correctness. A request/issue/PR does not prove a bug, necessity, or correctness. Label inferences, unverified, and contradicted claims. +- **A change is material when a reviewer could not accept it from inspection alone.** That covers anything able + to alter runtime behavior, a public or persisted contract, security/privacy posture, permissions, cross-context + messaging, or build/release output. Everything else is routine and takes the light path: say what changed and + what you checked. Where the call is genuinely close, say which way you read it instead of quietly taking the + cheaper one. - **State rationale before summary.** For material changes, connect problem/requirement → affected scope/consequence → premise evidence → justification → remedy/trade-off → acceptance evidence → limitation/risk. A diff shows what changed, not why. @@ -82,6 +99,10 @@ downstream prose does not override it. - **Match claim strength to evidence.** Static reasoning, executed tests, browser runs, and external integrations prove different scopes. A negative claim needs the relevant channel observed through its closure window or a causal proof that the side effect cannot occur. +- **Do not write a caveat you could have converted into a fact.** Before recording a concern, a risk, or a + "worth checking" note, check it — an unchecked worry moves the work to the reader and tells them nothing they + could not already guess. If you record one regardless, say why you did not check it and what would settle it. + Hedging is not caution when it costs the reader more than it saves you. - **Bound readiness.** Do not call a material change review-ready with failed acceptance, a critical contradiction or evidence gap, unjustified scope, or stale final-patch evidence. A requested draft/investigation may proceed when labeled; report the blocker and clearing condition. @@ -93,6 +114,81 @@ downstream prose does not override it. useful location, and actionable contract to restore; do not turn an unverified repository assumption into a finding. +## Autonomous operation + +These govern what an agent does on its own between two human decisions — the acting as much as the bounds on it. +Within the work you were asked for you are the contributor, not a proposal generator: decide, do the work, and say +what you decided. Authority over the goal is not authority over every act taken to reach it, which is what the +later bullets bound. + +- **Decide inside the scope you were given.** Three situations get confused as one. If you do not know something, + find out — read the code, run it, write the probe; a question you could have answered yourself is not a question. + If it cannot be known yet, take the cheapest reasonable reading, state the assumption where the work will be + read, and continue. Only the third is escalation: a decision needing authority you do not have — something + irreversible or outward-facing, a product or policy trade-off the maintainer owns, or accepting a residual risk + on their behalf. Difficulty, ambiguity, and ordinary risk are not authority problems. Resolve them and record how. +- **Hand a decision back only with its owner and its blocker named.** When you do escalate, say who owns the + decision, what specifically only they can supply, and what you will do by default if they say nothing. Without + those three it is not an escalation, it is unfinished work moved into someone else's queue. The same test governs + anything you notice in passing: if the task actually requires it, do it and say you did; if it merely happens to + be nearby, record a follow-up and move on — the boundary is the scope-discipline principle above, not the set of + files you happen to have open. Recommending work you were in a position to finish is not a lighter-touch option; + it is a smaller deliverable. +- **Stop and hand back rather than proceed on a broken premise.** Stop when the reported problem does not + reproduce, the confirmed cause lies outside the authorized scope, an observation contradicts the task's premise, + or the only remaining repair would remove supported behavior or violate a principle here. A failing check is not + one of these triggers — fix its cause. Stopping is a deliverable, not a failure: report the attempt, the + evidence, the contradiction, and the decision the human now owns. Do not substitute a smaller change that is + easier to justify for the one that was asked for. Submitting an explicitly requested draft or investigation + instead stays governed by [`docs/pull-request.md`](docs/pull-request.md#decision-evidence-and-readiness). +- **Bind the declared scope before committing or publishing.** The task statement, the commit type (gitmoji), and + the title declare a scope class — a test change, a fix, a refactor, a documentation change. Compare the actual + final diff against that class before you commit or push. Anything outside it is a checkpoint, not a judgement + call: move it into its own change with its own justification, or restate the scope. Do not carry an unexplained + edit forward because it looks harmless — a reviewer who cannot account for a hunk has to treat the whole change + as unreviewed. Mechanics live in [`docs/develop.md`](docs/develop.md#revision-scope-and-publication-binding). +- **Keep outward-facing and irreversible acts under explicit authorization.** Local work — reading, editing, + building, running the suite, driving a verification session — proceeds freely. Acts that leave the working tree + or are hard to undo need authorization for that specific act: pushing, opening or updating a pull request, + commenting on or closing an issue or pull request, deleting or rewriting a branch, and any command with real + external side effects. The task that asked for such an act is that authorization — this is not a rule to ask + permission twice — but a neighboring act it did not ask for is a separate decision. +- **Budget the reviewer's attention, not only your own.** An agent produces far more change per human review-minute + than a human contributor, so reviewability is part of the deliverable. Order the work so each commit is + independently reviewable and states the one thing it does; keep a confirmed behavior fix separate from cleanup + that merely travels with it; and when a correct repair is unavoidably large, say what makes it large and name + the seam a reviewer should check first. +- **Never let a provisional fix pose as the correct model.** The root-cause principle decides whether a + result-correct but mechanism-wrong change is acceptable at all; this decides what must be visible once one is + accepted anyway. A workaround taken for schedule, a compatibility shim, or a symptom suppressed with the cause + identified but unfixed must say so in the change itself — not only in a review thread later readers will not + see. A later agent reads merged code as the intended design and builds on it, so an unmarked workaround becomes + a false foundation that compounds. +- **Do not manufacture an oracle.** A self-generated score, grade, simulated pass rate, or persona review is your + own output, not an accepted oracle, and it cannot establish that a change is correct or good; report it, if at + all, as what it is. The same holds for an attestation that belongs to someone else — never record a human + review, a maintainer acceptance, or released behavior as satisfied on their behalf. + +## Writing for a human reader + +Everything an agent writes for people — pull request bodies, review comments, issue replies, hand-back reports — is +read by someone deciding what to do next. Being understood is part of delivering, and length is a cost the reader +pays rather than the writer. + +- **Write to the reader's next decision.** They are deciding whether to merge, what to change, or what to look at + first. Anything that does not move that decision is padding, however true it is. Lead with the outcome and then + the reasoning; do not make the reader assemble the conclusion out of a narrative of how you reached it. +- **Prose is the default; structure has to earn its place.** A table of three sentences is harder to read than + three sentences. Headings, bullet lists, and severity labels help when the content is genuinely parallel or + enumerable, and get in the way when it is not. Match the shape of the write-up to the size of the change, not to + the longest template you were offered. +- **Say each thing once.** A fact repeated across sections is one fact and several copies, and a reader who notices + the copies differ now has to work out which is current. State it where it belongs and refer back. +- **Shorten by selecting, never by omitting.** Cut what does not change the reader's decision. Never cut a check + you ran, a limitation, an uncertainty, or evidence the change requires — dropping those is not concision, it is + an inaccurate report. And when emphasis is everywhere it is nowhere: reserve it for the one or two things you + would say aloud if you had the reader's attention for ten seconds. + ## Architecture Use [`docs/architecture.md`](docs/architecture.md) and its referenced deep-dives before changing a boundary or diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md index 8e1552cc8..b5c291d67 100644 --- a/docs/DOC-MAINTENANCE.md +++ b/docs/DOC-MAINTENANCE.md @@ -63,6 +63,16 @@ Every hit is a review-queue entry, not an automatic rewrite — confirm whether correct (some are intentional non-negotiables) before loosening it, and confirm a downstream doc's exception survives when you touch the upstream rule it narrows. +## Instruction budget + +Agent-facing instructions are loaded on every task, so each rule carries a standing cost and competes for +attention with the rules already there. Before adding one, establish that it is not already derivable from a rule +present in the doc set, that it states a principle rather than replaying one incident, and that it belongs to the +doc that owns the subject rather than the doc most likely to be read. Prefer correcting or narrowing an existing +rule to appending a new one, and prefer one rule stated once in its owning doc to the same rule restated for +visibility — a rule that has to be repeated to be followed is usually stated in the wrong place. Deleting a rule +that a later rule superseded is maintenance, not loss of coverage. + ## Lint / config documentation depth When a doc describes an ESLint rule, tsconfig setting, or similar config-driven behavior, record the diff --git a/docs/develop.md b/docs/develop.md index 7cd946773..b3774061e 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -208,4 +208,10 @@ branch, bind the artifact, revision, and scope to the current remote state: to its returned head SHA. Any new commit, force-push, rebase, base change, conflict resolution, or scope-claim edit invalidates earlier evidence; rerun the affected review, checks, and final-diff audit. +The same binding applies to the scope you declared for your own change. A commit's gitmoji type and title, and the +task statement they serve, name a scope class; compare the final diff against that class before committing or +pushing. Move anything outside it into its own commit with its own justification, or restate the scope. A +production behavior change that arrives inside a test-cleanup or refactor commit is not reviewable as either, and +stays unreviewable no matter how correct it is on its own. + **Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched. diff --git a/docs/pull-request.md b/docs/pull-request.md index 18ab865e5..2280e9662 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -10,7 +10,9 @@ the change needs more context. 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, not all mandatory (see below for which ones). It is a list of things worth considering, not a form to +complete: a section you have nothing load-bearing to put in is one to leave out, and a description longer than the +diff it explains has usually stopped helping its reviewer. ## Recommended structure @@ -74,7 +76,7 @@ For a material behavior, configuration, security, performance, compatibility, pe 6. acceptance evidence; and 7. the remaining limitation or risk. -Keep this chain proportional. A confirmed one-line correction or a small documentation fix needs only the material parts; a non-trivial design choice should explain why doing nothing or a plausible smaller alternative was not selected and what would reopen the decision. +Keep this chain proportional. A confirmed one-line correction or a small documentation fix needs only the relevant parts; a non-trivial design choice should explain why doing nothing or a plausible smaller alternative was not selected and what would reopen the decision. Keep these roles separate: @@ -91,6 +93,12 @@ An agent must not present a change as review-ready when a material acceptance co Verification claims bind to a revision or clearly identified worktree. If code, configuration, generated artifacts, or a decision-relevant description changes after a check, rerun every affected check before claiming readiness. A final commit SHA is sufficient identity for ordinary GitHub work; a cryptographic evidence ledger is not required by default. +A check that does not reproduce its own result is not yet evidence. When a run is unstable — intermittent +timeouts, order-dependent failures, an environment-blocked step — record what actually ran, which failures +recurred and which did not, and how you separated them from the change under review. Report the residual +uncertainty instead of resolving it in the change's favor: a green rerun does not retract a red run, and +"unrelated to this change" is a claim that needs its own evidence rather than being the default reading. + ### Scope claims and final-diff evidence Claims that a pull request includes only a named scope or excludes another change are evidence-bearing. Before