docs(ai): 强化极简工作流与 Linux 构建约束

AGENTS.md

@@ -26,32 +26,55 @@ QmClient（Q1menG Client）是基于 DDNet / TaterClient 的第三方定制客
 | `docs/ai-workflow/git-workflow.md` | Git - commit、PR 标题/描述和最终汇报格式规范。 | 提交 git 和 PR 时 |
 | `qmclient_scripts/scripts_overview.md` | 脚本分层、推荐入口和 gate 工作流语义。 | 使用脚本时 |
 
+### 极简速查
+
+- 先定范围：一次只做一个功能或一个明确问题；超出当前需求的上游改动、协议/物理/预测/格式改动默认不做。
+- 启动顺序：先读匹配的 `docs/superpowers/plans/` 或 `docs/superpowers/specs/`；再读最小必要的 `docs/ai-workflow/` 规则；这轮涉及文档/入口/gate 时，先看 `check_docs.py` 是否也要同步修改。
+- 开工前先看真实代码：至少确认直接调用点、配置变量、翻译、测试和构建入口；不理解现状时不要直接写代码。
+- 实现时保持补丁聚焦：遵循 DDNet/QmClient 现有模式，不顺手重构无关代码，不把“现代化”当目标。
+- 验证时至少覆盖 build/test/gate，不能只跑 build/test 代替 gate。纯文档改动至少跑 `python qmclient_scripts/gate/check_docs.py`；常规代码改动至少跑 `python qmclient_scripts/gate/check_gate.py --mode quick --base-ref main`。
+- 同一 build 目录里的 `game-client`、`testrunner`、`run_cxx_tests`、`run_rust_tests`、`package_default` 必须串行执行，不要并行；要并行只能拆到不同 build 目录。
+- 影响核心逻辑时，完成后必须派发一个新的只读子代理做代码审查；审查先列 findings，再给总体结论；审查问题修完后再准备提交。
+- 完成任务后：先按 `docs/ai-workflow/verification.md` 跑对应验证，至少覆盖当前改动的 build/test/gate；子代理指出的问题修完后，再考虑收口提交范围。
+- 改文档、入口、gate 或 governance 内容时，先同步对应规则/脚本，再跑 `python qmclient_scripts/gate/check_docs.py --sync-only --prefer agents` 和 `python qmclient_scripts/gate/check_docs.py`。
+- 提交 commit / PR 前，先确认 review findings 已收口、gate 证据已补齐；不要带着“只跑过 build/test、没跑 gate”的状态提交。
+- commit / PR 标题统一用 `<type>(<scope>): <中文简述>`；正文先写问题/背景，再按 `fix`、`test`、`docs` 等分组。
+- 最终汇报必须写清：改了什么、跑了哪些验证、结果如何、还有哪些 gaps；没跑的不要说通过。
+
 ## 极简工作流
 
 ### 启动顺序
 
 - 先读 `docs/superpowers/plans/` 和 `docs/superpowers/specs/` 里与当前任务匹配的计划或规格。
 - 再读与当前任务匹配的最小 `docs/ai-workflow/` 规则。
 - 如果这轮涉及文档/入口/gate，先看 `check_docs.py` 是否也要同步修改。
-- 读取与任务匹配的聚焦 `docs/ai-workflow/` 文档。
-- 修改前检查附近源码、调用点、配置变量、翻译和测试。
+- 修改前检查附近源码、调用点、配置变量、翻译和测试；不理解现状时不要直接写代码。
 
 ### 完成任务后
 
 - 先按 `docs/ai-workflow/verification.md` 跑对应验证，至少覆盖当前改动的 build/test/gate。
+- 除非用户明确把任务限制为纯调查、纯文档同步或只要求某个单项命令，否则不要只用 build/test 代替 gate；代码改动完成后，至少补一条与范围匹配的 `python qmclient_scripts/gate/check_gate.py --mode ...` 验证。
+- 默认口径：纯文档 / harness 改动至少跑 `python qmclient_scripts/gate/check_docs.py`；常规代码改动至少跑 `check_gate.py --mode quick`；提交前如环境允许优先补到 `--mode default`；集中收口或准发布改动再用 `--mode full`。
+- 同一 build 目录中的 `game-client`、`testrunner`、`run_cxx_tests`、`run_rust_tests`、`package_default` 必须串行执行，不要并行；要并行只能拆到不同 build 目录。
 - 影响核心逻辑时，必须派发一个新的只读子代理，按 `docs/ai-workflow/review.md` 做代码审查。
 - 子代理指出的问题修完后，再看这次改动能否最小化提交：只保留和当前任务直接相关的文件与说明。
 
 ### 提交 commit / PR 前
 
 - 先跑 `python qmclient_scripts/gate/check_docs.py`。
-- commit 和 PR 文案按 `docs/ai-workflow/git-workflow.md` 编写。
+- 不要带着“只跑过 build/test、没跑 gate”的状态进入 commit / PR；至少记录一条与本轮范围匹配的 gate 证据。
+- commit 和 PR 文案按 `docs/ai-workflow/git-workflow.md` 编写：标题统一用 `<type>(<scope>): <中文简述>`，正文先写问题/背景，再按 `fix`、`test`、`docs` 等分组。
 - 如果准备提 PR，先确保这轮审查结论已经收口，不要带着已知 review finding 进入 PR。
 
 ### 修改文档后
 
-- 先判断这次文档改动是否改变了入口或规范；如果改变了，先同步修改 `check_docs.py` 或其约束，再跑文档检查
-- 最后运行 `python qmclient_scripts/gate/check_docs.py`，确认没有断链或镜像漂移。
+- 先判断这次文档改动是否改变了入口或规范；如果改变了，先同步修改 `check_docs.py` 或其约束，再跑文档检查。
+- 运行 `python qmclient_scripts/gate/check_docs.py --sync-only --prefer agents`，再运行 `python qmclient_scripts/gate/check_docs.py`，确认没有断链或镜像漂移。
+
+### 最终汇报
+
+- 最终汇报必须写清：改了什么、跑了哪些验证、结果如何、还有哪些 gaps。
+- 没跑的不要说通过；没收口的不要说完成。
 
 ## 全局硬约束（简略版，详细看 `docs/ai-workflow/ddnet-development.md`）
 
@@ -82,6 +105,7 @@ QmClient（Q1menG Client）是基于 DDNet / TaterClient 的第三方定制客
 - 修改 `AGENTS.md`、`CLAUDE.md`、`docs/ai-workflow/`、workflow 脚本或 governance CI 后，运行 `python qmclient_scripts/gate/check_docs.py --sync-only --prefer agents`，再运行 `python qmclient_scripts/gate/check_docs.py`
 - Windows 上默认用 `qmclient_scripts/cmake-windows.cmd` 作为构建入口；常规构建/测试目录是 `cmake-build-release`，交互式完整构建命令：`qmclient_scripts/cmake-windows.cmd --build cmake-build-release --target game-client -j 14`。自动化子进程显式走 `cmd.exe` 宿主时再使用 `cmd /c qmclient_scripts/cmake-windows.cmd ...`；只有已确认当前 shell 已注入可用的 VS/MSVC 环境时，才直接使用裸 `cmake`
 - 构建目录名规范：debug - `cmake-build-debug`；release - `cmake-build-release`；release-pdb - `cmake-build-release-pdb`
+- 同一 build 目录中的 `game-client`、`testrunner`、`run_cxx_tests`、`run_rust_tests`、`package_default` 不要并行发起；这些目标会共享生成产物和中间文件，必须串行执行。需要并行时，只能拆到不同 build 目录。
 
 ## 十二原则：软件工程
 

CLAUDE.md

@@ -26,32 +26,55 @@ QmClient（Q1menG Client）是基于 DDNet / TaterClient 的第三方定制客
 | `docs/ai-workflow/git-workflow.md` | Git - commit、PR 标题/描述和最终汇报格式规范。 | 提交 git 和 PR 时 |
 | `qmclient_scripts/scripts_overview.md` | 脚本分层、推荐入口和 gate 工作流语义。 | 使用脚本时 |
 
+### 极简速查
+
+- 先定范围：一次只做一个功能或一个明确问题；超出当前需求的上游改动、协议/物理/预测/格式改动默认不做。
+- 启动顺序：先读匹配的 `docs/superpowers/plans/` 或 `docs/superpowers/specs/`；再读最小必要的 `docs/ai-workflow/` 规则；这轮涉及文档/入口/gate 时，先看 `check_docs.py` 是否也要同步修改。
+- 开工前先看真实代码：至少确认直接调用点、配置变量、翻译、测试和构建入口；不理解现状时不要直接写代码。
+- 实现时保持补丁聚焦：遵循 DDNet/QmClient 现有模式，不顺手重构无关代码，不把“现代化”当目标。
+- 验证时至少覆盖 build/test/gate，不能只跑 build/test 代替 gate。纯文档改动至少跑 `python qmclient_scripts/gate/check_docs.py`；常规代码改动至少跑 `python qmclient_scripts/gate/check_gate.py --mode quick --base-ref main`。
+- 同一 build 目录里的 `game-client`、`testrunner`、`run_cxx_tests`、`run_rust_tests`、`package_default` 必须串行执行，不要并行；要并行只能拆到不同 build 目录。
+- 影响核心逻辑时，完成后必须派发一个新的只读子代理做代码审查；审查先列 findings，再给总体结论；审查问题修完后再准备提交。
+- 完成任务后：先按 `docs/ai-workflow/verification.md` 跑对应验证，至少覆盖当前改动的 build/test/gate；子代理指出的问题修完后，再考虑收口提交范围。
+- 改文档、入口、gate 或 governance 内容时，先同步对应规则/脚本，再跑 `python qmclient_scripts/gate/check_docs.py --sync-only --prefer agents` 和 `python qmclient_scripts/gate/check_docs.py`。
+- 提交 commit / PR 前，先确认 review findings 已收口、gate 证据已补齐；不要带着“只跑过 build/test、没跑 gate”的状态提交。
+- commit / PR 标题统一用 `<type>(<scope>): <中文简述>`；正文先写问题/背景，再按 `fix`、`test`、`docs` 等分组。
+- 最终汇报必须写清：改了什么、跑了哪些验证、结果如何、还有哪些 gaps；没跑的不要说通过。
+
 ## 极简工作流
 
 ### 启动顺序
 
 - 先读 `docs/superpowers/plans/` 和 `docs/superpowers/specs/` 里与当前任务匹配的计划或规格。
 - 再读与当前任务匹配的最小 `docs/ai-workflow/` 规则。
 - 如果这轮涉及文档/入口/gate，先看 `check_docs.py` 是否也要同步修改。
-- 读取与任务匹配的聚焦 `docs/ai-workflow/` 文档。
-- 修改前检查附近源码、调用点、配置变量、翻译和测试。
+- 修改前检查附近源码、调用点、配置变量、翻译和测试；不理解现状时不要直接写代码。
 
 ### 完成任务后
 
 - 先按 `docs/ai-workflow/verification.md` 跑对应验证，至少覆盖当前改动的 build/test/gate。
+- 除非用户明确把任务限制为纯调查、纯文档同步或只要求某个单项命令，否则不要只用 build/test 代替 gate；代码改动完成后，至少补一条与范围匹配的 `python qmclient_scripts/gate/check_gate.py --mode ...` 验证。
+- 默认口径：纯文档 / harness 改动至少跑 `python qmclient_scripts/gate/check_docs.py`；常规代码改动至少跑 `check_gate.py --mode quick`；提交前如环境允许优先补到 `--mode default`；集中收口或准发布改动再用 `--mode full`。
+- 同一 build 目录中的 `game-client`、`testrunner`、`run_cxx_tests`、`run_rust_tests`、`package_default` 必须串行执行，不要并行；要并行只能拆到不同 build 目录。
 - 影响核心逻辑时，必须派发一个新的只读子代理，按 `docs/ai-workflow/review.md` 做代码审查。
 - 子代理指出的问题修完后，再看这次改动能否最小化提交：只保留和当前任务直接相关的文件与说明。
 
 ### 提交 commit / PR 前
 
 - 先跑 `python qmclient_scripts/gate/check_docs.py`。
-- commit 和 PR 文案按 `docs/ai-workflow/git-workflow.md` 编写。
+- 不要带着“只跑过 build/test、没跑 gate”的状态进入 commit / PR；至少记录一条与本轮范围匹配的 gate 证据。
+- commit 和 PR 文案按 `docs/ai-workflow/git-workflow.md` 编写：标题统一用 `<type>(<scope>): <中文简述>`，正文先写问题/背景，再按 `fix`、`test`、`docs` 等分组。
 - 如果准备提 PR，先确保这轮审查结论已经收口，不要带着已知 review finding 进入 PR。
 
 ### 修改文档后
 
-- 先判断这次文档改动是否改变了入口或规范；如果改变了，先同步修改 `check_docs.py` 或其约束，再跑文档检查
-- 最后运行 `python qmclient_scripts/gate/check_docs.py`，确认没有断链或镜像漂移。
+- 先判断这次文档改动是否改变了入口或规范；如果改变了，先同步修改 `check_docs.py` 或其约束，再跑文档检查。
+- 运行 `python qmclient_scripts/gate/check_docs.py --sync-only --prefer agents`，再运行 `python qmclient_scripts/gate/check_docs.py`，确认没有断链或镜像漂移。
+
+### 最终汇报
+
+- 最终汇报必须写清：改了什么、跑了哪些验证、结果如何、还有哪些 gaps。
+- 没跑的不要说通过；没收口的不要说完成。
 
 ## 全局硬约束（简略版，详细看 `docs/ai-workflow/ddnet-development.md`）
 
@@ -82,6 +105,7 @@ QmClient（Q1menG Client）是基于 DDNet / TaterClient 的第三方定制客
 - 修改 `AGENTS.md`、`CLAUDE.md`、`docs/ai-workflow/`、workflow 脚本或 governance CI 后，运行 `python qmclient_scripts/gate/check_docs.py --sync-only --prefer agents`，再运行 `python qmclient_scripts/gate/check_docs.py`
 - Windows 上默认用 `qmclient_scripts/cmake-windows.cmd` 作为构建入口；常规构建/测试目录是 `cmake-build-release`，交互式完整构建命令：`qmclient_scripts/cmake-windows.cmd --build cmake-build-release --target game-client -j 14`。自动化子进程显式走 `cmd.exe` 宿主时再使用 `cmd /c qmclient_scripts/cmake-windows.cmd ...`；只有已确认当前 shell 已注入可用的 VS/MSVC 环境时，才直接使用裸 `cmake`
 - 构建目录名规范：debug - `cmake-build-debug`；release - `cmake-build-release`；release-pdb - `cmake-build-release-pdb`
+- 同一 build 目录中的 `game-client`、`testrunner`、`run_cxx_tests`、`run_rust_tests`、`package_default` 不要并行发起；这些目标会共享生成产物和中间文件，必须串行执行。需要并行时，只能拆到不同 build 目录。
 
 ## 十二原则：软件工程
 

docs/ai-workflow/verification.md

@@ -28,6 +28,18 @@ cmake -G Ninja -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
 cmake --build cmake-build-release --target game-client -j 14
 ```
 
+说明：如果当前宿主是 Windows，但需要验证 Linux 构建，优先在 WSL Ubuntu 中使用 GCC/G++、CMake 和 Ninja 走原生 Linux 构建，不要复用 Windows 的 `cmake-build-release` 目录。推荐单独使用 `cmake-build-linux-release` 之类的目录，避免和 Windows 生成的 `CMakeCache.txt` 冲突。已验证可用的 WSL 口径示例：
+
+```pwsh
+wsl env HOME=/home/<user> bash -lc 'set -e; . "$HOME/.cargo/env"; cd /mnt/<drive>/<path-to-repo>; cmake -G Ninja -S . -B cmake-build-linux-release -DCMAKE_BUILD_TYPE=Release -DDOWNLOAD_GTEST=ON; cmake --build cmake-build-linux-release --target game-client -j 14'
+```
+
+如果需要 Linux 打包，可直接把 target 切到 `package_default`：
+
+```pwsh
+wsl env HOME=/home/<user> bash -lc 'set -e; . "$HOME/.cargo/env"; cd /mnt/<drive>/<path-to-repo>; cmake -G Ninja -S . -B cmake-build-linux-release -DCMAKE_BUILD_TYPE=Release -DDOWNLOAD_GTEST=ON; cmake --build cmake-build-linux-release --target package_default -j 14'
+```
+
 ## 测试
 
 Windows:
@@ -40,13 +52,21 @@ qmclient_scripts/cmake-windows.cmd --build cmake-build-release --target run_rust
 
 说明：常规运行/测试目录默认是 `cmake-build-release`；C++ 测试主路径是先构建 `testrunner`，再直接执行测试二进制。`default/full` gate 里的严格构建与静态分析会另外使用 `cmake-build-debug` 和 `cmake-build-analyze`。
 
+重要：同一 build 目录中的 `game-client`、`testrunner`、`run_cxx_tests`、`run_rust_tests`、`package_default` 不要并行发起。它们会共享生成产物与中间文件，代理或脚本必须串行执行；如果确实要并行，只能拆到不同的 build 目录。
+
 Linux/macOS:
 
 ```sh
 cmake --build cmake-build-release --target run_cxx_tests
 cmake --build cmake-build-release --target run_rust_tests
 ```
 
+如果走 Windows 宿主下的 WSL Linux 验证，对应地把目录替换成独立的 Linux build 目录，例如：
+
+```pwsh
+wsl env HOME=/home/<user> bash -lc 'set -e; . "$HOME/.cargo/env"; cd /mnt/<drive>/<path-to-repo>; cmake --build cmake-build-linux-release --target run_cxx_tests -j 14; cmake --build cmake-build-linux-release --target run_rust_tests -j 14'
+```
+
 ## Gate 模式
 
 ```bash
@@ -55,6 +75,13 @@ python qmclient_scripts/gate/check_gate.py --mode default --base-ref main
 python qmclient_scripts/gate/check_gate.py --mode full --base-ref main
 ```
 
+说明：除非用户明确把任务限制为纯调查、纯文档同步或只要求某个单项命令，否则不要只用 build/test 代替 gate。至少选择一条与本轮范围匹配的 gate 作为验收证据：
+
+- 纯文档 / harness 变更：`python qmclient_scripts/gate/check_docs.py`
+- 常规代码改动：至少 `python qmclient_scripts/gate/check_gate.py --mode quick --base-ref main`
+- 提交前日常严格门：优先 `python qmclient_scripts/gate/check_gate.py --mode default --base-ref main`
+- 集中收口 / 准发布：`python qmclient_scripts/gate/check_gate.py --mode full --base-ref main`
+
 版本 / release 相关修改后，至少额外验证：
 
 ```bash