📝 Add agent contribution guidelines

[AlexV525]

Introduces AGENTS.md (+ Simplified Chinese mirror) as this repo's rules for AI-agent-assisted contributions, along with pointers from CONTRIBUTING and a PR-template checklist item.

AGENTS.md is the de-facto standard filename that agent tools (Claude Code, Codex, Cursor, Devin, etc.) pick up automatically, so agents on external forks get these rules without extra setup.

What the guidelines cover

1. Motivation first — every non-trivial change must answer four questions (what can't be done today, who needs it, why in core rather than an interceptor/adapter/transformer/plugin, cost). Closes #NNNN alone does not count as prior discussion — the referenced issue must show maintainer buy-in. One PR = one concern.
2. Mandatory, effective, non-duplicated tests — tests must fail without the change; coverage minimum is a floor, not a target; no test-theater for coverage numbers.
3. Compatibility is sacred — additive-by-default; deprecations with Use XXX instead. This will be removed in 6.0.0 (next major); no SDK-lower-bound bumps outside the Compatibility Policy; watch behavioral breaks. Explicit sensitive-area list (SSL/TLS + cert pinning, redirects, cookies, headers, timeout/cancellation/connection pooling, interceptor pipeline, request-body encoding) and dependency-change rules (no drive-by bumps; state motivation; narrowest constraint; disclose new transitives).
4. Understand before you change — no API guessing; cross-platform pub-cache paths + PUB_CACHE env var.
5. Production quality only — no TODO/mock/simplified-and-called-done code.
6. When to stop and ask — general rule for ambiguity and out-of-scope work, distinct from §3's breaking-change escalation.
7. Repository layout — Melos mono-repo, per-package SDK lower bounds.
8. Commits, changelog, and PR hygiene
   • §8.1 Branch naming — category/ticket-id-or-short-description
   • §8.2 Commit format — gitmoji + Conventional Commits with an emoji reference table matched to the repo's actual usage
   • §8.3 AI attribution mandatory — every contributing agent gets a Co-Authored-By: trailer; the PR body discloses agent + stage (design / implementation / tests / review)
   • §8.4 CHANGELOG rules
   • §8.5 Self-review your diff — remove debug prints, commented code, unrelated formatting; git add . / -A forbidden
   • §8.6 Opening the PR — draft PRs for large/exploratory changes; describe verification honestly in prose rather than a boilerplate "Test plan" checklist; anything genuinely un-verifiable goes under an Unverified paragraph
   • §8.7 Review iteration — append commits (no squash-force-push mid-review); no close/reopen to reset state; design feedback is conversation, not instruction; CI failures require log-reading, not retry-until-green
9. Patterns that may lead to closure — cross-reference table linking each anti-pattern back to the rule it violates, softened wording (may / might).

Iteration notes

Five commits total. Follow-ups after the initial commit addressed:

• @AmosHuKe inline comments — cross-platform pub-cache paths and PUB_CACHE, 「包」 → package in the Chinese version, mainland-accessible Melos URL, softened minor-version breaking-change wording per dio's own CHANGELOG preamble.
• @CaiJingLong via GLM-5.2 — fixed the @Deprecated example's target version (7.0.0 → 6.0.0 to match repo reality); expanded the workflow gaps GLM flagged (commit format, self-review, review iteration, when-to-ask, sensitive areas); collapsed the "patterns that may lead to closure" section from a full restatement of §§1–8 into a cross-reference table.
• Stress-tested against feat: warn about CORS preflight requests on Web #2556 (opened by @CaiJingLong via GLM-5.2 + Devin right after this PR) — that PR validated the branch-naming convention and motivated the "describe verification honestly" rule in §8.6, after its Test-plan section carried a well-intentioned but misleading "existing tests still cover" note on an untested new code path.

Files

• AGENTS.md — English rules
• AGENTS-ZH.md — Simplified Chinese mirror
• CONTRIBUTING.md / CONTRIBUTING-ZH.md — link to the new guidelines
• .github/PULL_REQUEST_TEMPLATE.md — checklist item pointing to AGENTS.md

Verification

Documentation change; no code paths to exercise. All internal §-references were grep-verified for consistency after each renumbering pass. The gitmoji reference table in §8.2 was cross-checked against the last 300 commits (git log --pretty=format:'%s' -300 | grep -oE '^[^A-Za-z0-9 (]+' | sort | uniq -c) to ensure the emojis it endorses match the repo's real usage frequency.

New Pull Request Checklist

• I have read the Documentation
• I have searched for a similar pull request in the project and found none
• I have updated this branch with the latest main branch to avoid conflicts
• I have added the required tests to prove the fix/feature I'm adding (not applicable — documentation only)
• I have updated the documentation (if necessary)
• I have run the tests without failures (not applicable — documentation only)
• I have updated the CHANGELOG.md in the corresponding package (not applicable — repository-level docs, no package touched)

[CaiJingLong]

PR Review — Source: GLM-5.2

Risk: LOW — Documentation-only change, 5 files, 0 deletions, no code/test/CI impact.

Changes Summary

• Adds AGENTS.md (175 lines) and AGENTS-ZH.md (115 lines), 8 sections of agent contribution guidelines.
• CONTRIBUTING.md / CONTRIBUTING-ZH.md each get a one-line pointer to the new guidelines.
• .github/PULL_REQUEST_TEMPLATE.md gets a new checklist item (required when AI assistance is involved).

Fact-checking (verified against the actual repo)

• Repository layout table, 8 paths: all exist ✓
• COMPATIBILITY_POLICY.md, dio/doc/migration_guide.md, README.md/README-ZH.md: all exist ✓
• melos run format / format:fix / analyze / test / test:vm / test:web / test:flutter: all defined in melos.yaml ✓
• "replace *None.*": 4 plugin CHANGELOGs currently show *None.* ✓
• EN and ZH versions are faithful translations; section numbering matches ✓

Findings

1. [minor] Deprecation example's removal version contradicts the "next major" rule

   • AGENTS.md / AGENTS-ZH.md example: @Deprecated('Use XXX instead. This will be removed in 7.0.0')
   • Rule text: deprecations are "only removed in the next major release".
   • Repo reality: dio is currently 5.9.2; all 8 existing @Deprecated annotations target removed in 6.0.0 (see io_adapter.dart, dio_exception.dart, etc.).
   • The next major is 6.0.0, so the 7.0.0 example steers contributors toward removing in the major after next, contradicting the rule. Suggest changing the example to 6.0.0, or rewording the rule to "no earlier than the next major release" to accommodate the example.

2. [nit] PR template hardcodes an absolute URL pointing at the main branch

   • https://github.com/cfug/dio/blob/main/AGENTS.md: acceptable in a PR template (GitHub renders it), but if the default branch is ever renamed this needs syncing. Other checklist items use relative/external doc links, so the style is slightly inconsistent. Keep as-is, just a heads-up.

3. [nit] Checklist conditional wording could be clearer

   • Currently "(required if any part of the change was produced with AI assistance)". Consider adding "(skip if not applicable)" or similar, so pure-human contributors don't mistake it as mandatory reading. Optional polish.

No issues found

• No code changes, no breaking-change risk.
• EN and ZH versions are aligned; no missing sections.
• All referenced in-repo files/paths/commands actually exist.
• PR description's checklist is self-consistent (doc-only items marked not applicable, reasonable).

Recommendation

APPROVE (suggest addressing finding 1's version-number example before merge; findings 2/3 are optional).

---

This review was generated by GLM-5.2.

[AmosHuKe]

中文内的 包 建议都改为 package，
以及建议也对文档进行格式化（断句换行等等）~

[CaiJingLong]

AGENTS.md 工作流约束审阅 — 来源：GLM-5.2

本评论仅针对 AGENTS.md 作为 agent 完整工作流约束的完备性，不涉及其他文件。

一个 agent 完整工作流的阶段覆盖

阶段	覆盖	章节
1. 任务理解 / 动机确认	✓ 充分	§1
2. 代码库探索	✓ 有但薄	§4
3. 方案设计 / 规划	✗ 缺失	—
4. 实现	✓ 有	§4, §5
5. 测试编写	✓ 充分	§2
6. 本地验证（format/analyze/test）	✓ 充分	§2
7. 自审 diff	✗ 缺失	—
8. Changelog / commit / PR 创建	✓ 有但薄	§7
9. CI 等待与修复	✗ 缺失	—
10. 回应 review 反馈 / 迭代	✗ 几乎缺失	§7 仅一句
11. 合并后	✗ 缺失	—

缺失项（按重要性排序）

1. Commit message 规范 [高]
§7 只说"follow existing style (see git log)"，但仓库实际使用 Conventional Commits（fix:, feat:, docs:, test:）。agent 不会主动去翻 git log 推断格式，应明确写出前缀规范和 scope 用法。这是 agent 每次提交都会踩的点。

2. 自审 diff 要求 [高]
agent 最常见的失误是：顺手改了不相关的文件、留下 debug print、格式化波及未涉及代码。§4 说了"keep diffs minimal"但没要求 agent 在 commit 前执行 git diff 自检。应加一条：提交前必须 review 自己的完整 diff，确认无意外改动、无调试残留。

3. 回应 review 的工作流 [高]
§7 仅说"respond to review feedback substantively"，但没覆盖：

• 收到 change request 后是追加 commit 还是 squash
• force-push 策略（仓库是否允许、是否要避免）
• 不要关闭重开 PR
• review 意见指向设计层面时要先讨论再改代码，不要机械执行
• 维护者标记 "resolved" 的惯例

agent 在 review 迭代阶段的行为完全无约束。

4. 何时停下来问人 [中]
§3 说 breaking change 要停下来开 issue，§1 说 feature 要先讨论。但缺少一条通用规则：当任务描述模糊、需求矛盾、或遇到多种合理方案时，agent 应停下来向操作者确认，而不是自行假设后推进。agent 的默认行为是"猜了就做"，这条缺失影响很大。

5. CI 失败处理 [中]
§2 列了本地验证命令，但没提 CI。agent 应知道：CI 会跑什么、CI 失败后先读日志定位根因再修、不要靠反复 push 碰运气、flaky test 的处理方式。

6. 性能与安全敏感区域 [中]
dio 是网络库，涉及证书校验、重定向、cookie、header 处理。没有一条提示 agent 这些区域改动需格外谨慎、可能需要维护者额外 review。§3 只讲 API 兼容性，没讲安全/正确性敏感区域。

7. Draft PR 使用 [低]
大改动应先开 draft PR 供早期反馈，没有提及。

8. 依赖变更规则 [低]
§4 禁止 drive-by dependency bumps，但如果依赖变更是 PR 的正当目的呢？没有说。应补：依赖升级需说明原因、验证范围、最低版本策略。

9. 调试残留禁止 [低]
§5 说了不留 TODO/FIXME，但没提 print()、注释掉的代码块、临时日志。agent 经常留下这些。

10. 分支命名 [低]
无分支命名约定。看仓库实际有 alexv525-fix-queued-interceptor-reject、docs/agents-guidelines 等风格不一，但至少应给 agent 一个默认模式。

冗余项

1. §8 与 §1-§5 大面积重复 [主要冗余]

§8 "Patterns that may lead to closure" 的 6 条几乎全部是前文的复述：

§8 条目	已在何处规定
Feature dumps with no motivation	§1 全节
Multiple unrelated changes bundled	§1 "One PR, one concern"
Logic changes without tests	§2 全节
Unrelated file churn	§4 "Keep diffs minimal"
Falsely checked checklist	§2 "Never state that tests pass"
Breaking API without sign-off	§3 "stop and raise it in an issue"

§8 的价值在于"快速对照表"，但当前写法是完整重述而非引用。建议改为：列出模式名 + 一行引用（如 "see §1"），避免规则更新时两处不同步。

2. §1 内部轻微重复
"Feature PRs without prior discussion... might be closed" 与 §8 "Feature dumps with no stated motivation or prior discussion" 是同一句话的两个版本。

3. §2 "Run the checks locally" 与 "Never state that tests pass without having run them"
后者是前者的推论。对人类可以合并，但对 agent 保留两条有强化效果，不算硬冗余。

结构性观察

§4 "Understand before you change" 混了两个关注点：探索理解（read surrounding code, fix root causes, never guess API）和 diff 卫生（keep diffs minimal, no drive-by refactoring）。后者更适合放到 §7（PR hygiene）或独立为"diff discipline"小节，与缺失项 #2（自审 diff）合并。

缺少"执行顺序"指引：8 节内容是规则清单，但没有一条说"你拿到任务后应该按什么顺序做"。agent 需要的是：理解动机 → 探索代码 → 确认方案 → 实现 → 写测试 → 本地验证 → 自审 diff → 更新 changelog → 提交。加一段简短 workflow checklist 会让文档从"规则手册"变成"可执行流程"。

总结

类别	数量	最关键的
缺失	10 项	commit 规范、自审 diff、review 迭代流程、何时停下来问
冗余	3 项	§8 与 §1-5 大面积重复（最值得处理）
结构	2 项	§4 混关注点、缺执行顺序指引

如果要排优先级，最该补的三条：commit message 规范、提交前自审 diff、review 迭代工作流。最该精简的一处：§8 改为引用式速查表。

---

本审阅意见由 GLM-5.2 生成。

[AmosHuKe]

无法访问 https://melos.invertase.dev ，建议换成 https://github.com/invertase/melos/tree/main/docs

[CaiJingLong]

The #2556 was created by the AGENTS.md , by GLM5.2 and devin agent.

[AmosHuKe]