docs: require bilingual design documents (#11419)

Co-authored-by: probe <probe@local>

.github/pull_request_template.md

@@ -49,6 +49,8 @@ Non–user-visible (refactor, types, docs): commands and output below; write N/A
 - Not validated / out of scope:
 - Breaking changes / migration notes:
 
+<!-- If this PR creates or updates a design document, link both its English (.md) and Chinese (.zh-CN.md) versions. Verify that both are complete and synchronized, including decisions, constraints, acceptance criteria, and follow-up work. See docs/design/README.md. / 新增或修改设计文档时，请附上英文和中文版本链接，并确认设计决策、约束、验收标准及后续工作完整同步。详见 docs/design/README.zh-CN.md。 -->
+
 ## Linked Issues
 
 <!--

AGENTS.md

@@ -204,7 +204,11 @@ npm run preflight  # Full check: clean → install → format → lint → build
 
 1. **Design doc for non-trivial work** — write one in `docs/design/` if the
    change touches multiple files or involves design decisions. Skip for small
-   bugfixes.
+   bugfixes. Provide both an English `<name>.md` and a Chinese
+   `<name>.zh-CN.md` version in the same directory, following the
+   [design documentation requirements](docs/design/README.md). Add reciprocal
+   language links and keep both versions complete and synchronized in the same
+   change, including when updating an existing design.
 2. **Test plan for behavioral changes** — write an E2E test plan in
    `.qwen/e2e-tests/` when the change affects user-observable behavior. Dry-run
    against the global `qwen` CLI first to confirm the baseline.
@@ -270,6 +274,10 @@ things a reviewer of _this_ codebase must check — not general advice.
   longer applies.
 - **A missing test for changed behavior is a Suggestion, not a Critical**, unless
   the untested path is itself the defect.
+- **Check design documentation in both languages.** New or updated designs
+  must include linked English and Chinese versions with matching structure,
+  decisions, constraints, and acceptance criteria. A translation gap alone is
+  a Suggestion, not a Critical.
 
 ## GitHub Operations
 

docs/design/README.md

@@ -0,0 +1,55 @@
+# Design Documentation Requirements
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Design documents describe proposed changes, their rationale, and how to verify
+them. Store them under `docs/design/` and follow the requirements below when
+creating or updating a design.
+
+## File naming and navigation
+
+- Maintain two complete versions in the same directory: `<name>.md` for English
+  and `<name>.zh-CN.md` for Simplified Chinese. Keep the same base name and date
+  prefix, if any. Directory entry pages use `README.md` and `README.zh-CN.md`.
+- Add relative links to both versions immediately below each document title.
+- Preserve existing document paths where possible. If a path or heading anchor
+  changes, update its incoming references in the same change.
+
+## Content alignment
+
+- Both versions must cover the full design. A summary or a link to the other
+  language does not replace a translation.
+- Keep section order and heading levels aligned. Match the meaning of the
+  problem statement, current state, goals, scope boundaries, proposed solution,
+  design decisions and rationale, constraints, risks, validation plan, acceptance
+  criteria, and open questions wherever those sections apply.
+- Preserve technical identifiers, file paths, commands, configuration keys,
+  protocol fields, example values, and numeric limits. Translate explanatory
+  prose and captions without changing the behavior they describe.
+- Keep status, dates, milestones, and follow-up requirements aligned when
+  present. Distinguish proposals, implemented behavior, and verified results in
+  both languages; translation must not change a design's status.
+- Share diagrams and other assets where practical. Provide equivalent
+  explanations for language-specific text in shared assets.
+
+## Requirements for subsequent changes
+
+- Create or update both versions in the same change and submit them together in
+  the same PR. Either language may be edited first; reconcile any differences
+  before considering the documentation complete.
+- When updating an existing single-language design, add the missing version and
+  align the complete pair. Preserve the original design's meaning when
+  translating; explain actual design changes consistently in both versions.
+- Reflect new decisions, implementation constraints, acceptance criteria, and
+  follow-up work in both versions as the design evolves. Do not leave one
+  version with an earlier requirement or an unresolved question that the other
+  version has already answered.
+
+## Review checklist
+
+- Both files exist, and their language links resolve in both directions.
+- Section structure and substantive requirements match; neither version omits
+  decisions, limitations, acceptance criteria, or follow-up work.
+- Technical identifiers, examples, links, and shared assets remain correct.
+- Both versions reflect the same status and the changes proposed in the PR.
+- Markdown formatting and relative links have been checked.

docs/design/README.zh-CN.md

@@ -0,0 +1,42 @@
+# 设计文档要求
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+设计文档用于说明拟议变更、设计理由及验证方式。文档存放在 `docs/design/`
+下，新增或修改设计文档时应遵循以下要求。
+
+## 文件命名与导航
+
+- 在同一目录中维护两个完整版本：英文使用 `<name>.md`，简体中文使用
+  `<name>.zh-CN.md`。文件基础名称及日期前缀（如有）必须一致。目录入口页使用
+  `README.md` 和 `README.zh-CN.md`。
+- 在每份文档标题下方紧接着放置指向两个语言版本的相对链接。
+- 尽量保留现有文档路径。路径或标题锚点发生变化时，在同一次变更中更新引用它们的链接。
+
+## 内容对齐
+
+- 两个版本都必须完整覆盖设计内容，不能用摘要或指向另一语言的链接代替翻译。
+- 保持章节顺序和标题层级一致。适用的章节应在语义上对齐，包括问题描述、现状、目标、
+  范围边界、拟议方案、设计决策及理由、约束、风险、验证计划、验收标准和待定问题。
+- 保持技术标识符、文件路径、命令、配置键、协议字段、示例值和数值限制一致。
+  翻译说明文字及图注时，不得改变其描述的行为。
+- 文档中如有状态、日期、里程碑和后续要求，也必须同步。两个版本都应区分拟议方案、
+  已实现行为和已验证结果；翻译不得改变设计状态。
+- 尽量共享图表及其他资源。共享资源中包含特定语言的文字时，应提供含义一致的说明。
+
+## 后续变更要求
+
+- 在同一次变更中新增或更新两个版本，并在同一个 PR 中一并提交。
+  可以先编辑任一语言，但只有消除两个版本的差异后，文档工作才算完成。
+- 修改现有单语设计文档时，补齐缺失的语言版本并对齐完整文档。
+  翻译应保留原设计含义；实际设计变更应在两个版本中作出一致说明。
+- 随设计演进，在两个版本中同步新增决策、实现约束、验收标准和后续工作。
+  不得让一个版本保留旧要求，或保留另一个版本已经解决的待定问题。
+
+## 审查清单
+
+- 两份文件均存在，且双向语言链接有效。
+- 章节结构与实质要求一致，两个版本均未遗漏决策、限制、验收标准或后续工作。
+- 技术标识符、示例、链接和共享资源正确。
+- 两个版本的状态一致，且均反映 PR 中拟议的变更。
+- 已检查 Markdown 格式和相对链接。

docs/developers/contributing.md

@@ -47,6 +47,12 @@ Before submitting your PR, ensure that all automated checks are passing by runni
 
 If your PR introduces a user-facing change (e.g., a new command, a modified flag, or a change in behavior), you must also update the relevant documentation in the `/docs` directory.
 
+New or updated design documents must include complete English (`<name>.md`) and
+Simplified Chinese (`<name>.zh-CN.md`) versions in the same directory and PR.
+Keep their structure, decisions, constraints, and acceptance criteria aligned,
+and add reciprocal language links. See the design documentation requirements
+in [English](../design/README.md) or [简体中文](../design/README.zh-CN.md).
+
 #### 6. Write Clear Commit Messages and a Good PR Description
 
 Your PR should have a clear, descriptive title and a detailed description of the changes. Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for your commit messages.