From ce5c20f627f57c1e6195831b378373a5a333e6ab Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Sat, 11 Jul 2026 03:07:01 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E7=94=A8=E6=88=B7?=
 =?UTF-8?q?=E4=BA=A4=E4=BB=98=E5=8F=98=E6=9B=B4=E8=AE=B0=E5=BD=95=E5=86=99?=
 =?UTF-8?q?=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/reference/devops-hygiene.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/reference/devops-hygiene.md b/docs/reference/devops-hygiene.md
index bb9036d6..2662e2e7 100644
--- a/docs/reference/devops-hygiene.md
+++ b/docs/reference/devops-hygiene.md
@@ -139,6 +139,25 @@ For backend-core artifact publication, the required implementation is the host-f
 
 If a CI repo-check task fails at `git clone` because credentials are unavailable, classify it as a CI infrastructure/auth gap, not as an application test failure.
 
+## 用户交付 CHANGELOG 写法
+
+面向用户、交付方或评审方的 CHANGELOG 必须先说明用户可感知的功能改进或问题修复，再在同一条目的后半句说明交付文档同步情况。不要把 commit、内部函数、调试注入、测试过程、构建下载过程或治理动作写成用户更新；测试只用于证明条目成立，测试结果应留在测试报告或任务记录中。
+
+CHANGELOG 的文档交叉引用必须同时满足以下要求：
+
+- 精确到文件名和文档内稳定编号或章节，例如 `jsonrpc_api_design.md` A14、`03_input_filter_output_mainline.md` T3.5。
+- 对每个被引用的文档分别用一个短语说明具体同步内容，不能只罗列一串文件名和编号。
+- API 文档说明字段、接口或状态语义的变化；配置文档说明字段默认值、范围和生效规则；测试文档说明新增或修改的验收场景与判定标准。
+- 同一功能涉及多个提交时合并成一个用户条目；纯内部治理只并入对应功能条目，不单独包装成功能更新。
+- 只有说明补充、没有代码功能变化时，明确写“补充文档说明”，不能表述为功能已经修复。
+- 用语必须直接描述最终行为，例如“输入无效后自动停止硬件输出并归零”，避免“受控处理”“优化逻辑”等不能回答实际结果的含混措辞。
+
+推荐格式：
+
+```markdown
+- <用户可感知的功能或问题修复>。文档同步：`<API 文档>` <编号> <接口或字段变化>；`<配置文档>` <编号> <默认值、范围或生效规则变化>；`<测试文档>` <编号> <验收场景或判定变化>。
+```
+
 ## Verification Priority
 
 The user's latest explicit objective takes precedence over stale tests, guards, preflights and assertions. When an old gate blocks the current requirement without protecting a still-valid high-value risk, remove it from the active path instead of preserving a fallback, legacy mode or compatibility branch around it.