docs: 增加 Agent 效率与范围控制 (#4)

AGENTS.md

@@ -40,6 +40,38 @@
 
 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。
 
+### 效率与范围控制
+
+本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。
+
+#### 严格控制范围
+
+- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
+- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
+- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
+- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。
+
+#### 渐进执行和修复
+
+- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
+- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
+- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
+- 不在真实证据出现前堆叠与已知风险无关的预防性检查。
+- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。
+
+#### 复用已验证事实
+
+- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
+- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
+- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
+- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。
+
+#### 明确停止条件
+
+- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
+- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
+- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
+
 ## 4. 工单层级
 
 ```text

CLAUDE.md

@@ -15,6 +15,7 @@ Claude Code 开始任何工作前，必须按顺序阅读：
 - 方案经用户确认并建立单元任务工单后，才能修改产品代码。
 - 只修改当前工单范围内的文件，保留用户已有和无关的改动。
 - 在单元任务中明确文档影响；入口、命令、配置、数据、业务规则或排错方式变化时先更新对应 Wiki。
+- 严格遵守 `AGENTS.md` 的效率与范围控制：优先真实反馈、复用未失效的检查结果、完成必要闭环后停止，但不得省略安全和最终验收。
 - 实现、测试、Git 提交、待验收、Wiki 任务归档、导出本地镜像和关闭工单的顺序不得跳过。
 - 长期文档先修改 Wiki，再导出 `docs/`；不得直接编辑镜像作为最终结果。
 - 未经用户明确验收，不得关闭工单。

dev_scripts/check_harness.py

@@ -44,6 +44,11 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "## 面向初级维护者的修改边界",
         "## 每个任务的文档影响",
         "## 稳定文档与任务归档",
+        "## 效率与范围控制",
+        "### 严格控制范围",
+        "### 渐进执行和修复",
+        "### 复用已验证事实",
+        "### 明确停止条件",
     ),
     "docs/02-architecture-and-code-map.md": (
         "## 项目定位",
@@ -165,6 +170,22 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None:
         errors.append(f"单元任务模板缺少：{section}")
 
 
+def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
+    path = root / "AGENTS.md"
+    if not path.is_file():
+        return
+    content = path.read_text(encoding="utf-8")
+    required = (
+        "### 效率与范围控制",
+        "#### 严格控制范围",
+        "#### 渐进执行和修复",
+        "#### 复用已验证事实",
+        "#### 明确停止条件",
+    )
+    for section in missing_sections(content, required):
+        errors.append(f"AGENTS.md 缺少：{section}")
+
+
 def core_mapping_errors(configured_mappings: dict[str, str]) -> list[str]:
     errors: list[str] = []
     for page, expected_path in CORE_PAGE_PATHS.items():
@@ -231,6 +252,7 @@ def main() -> int:
     check_wiki_mirrors(errors)
     check_core_documents(errors)
     check_task_template(errors)
+    check_agent_efficiency_rules(errors)
     check_archives(errors)
 
     for warning in warnings:

docs/01-workflow.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Development-Workflow
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.-
-wiki_revision: 2ce05d5688fa3802ad62667a5ba34a90cf2a02f7
+wiki_revision: d00ceed847becc95439296f618bd8a461c0a4c0f
-synchronized_at: 2026-08-08T01:16:48Z
+synchronized_at: 2026-08-08T01:36:38Z
 <!-- gitea-wiki-mirror:end -->
 
 # 开发工作流
@@ -121,6 +121,38 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 - 新人先读稳定主题页，只有追查历史原因时才读任务归档。
 - 任务产生的长期结论必须合并到主题页，不能只留在归档。
 
+## 效率与范围控制
+
+本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。
+
+### 严格控制范围
+
+- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
+- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
+- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
+- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。
+
+### 渐进执行和修复
+
+- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
+- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
+- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
+- 不在真实证据出现前堆叠与已知风险无关的预防性检查。
+- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。
+
+### 复用已验证事实
+
+- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
+- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
+- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
+- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。
+
+### 明确停止条件
+
+- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
+- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
+- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
+
 ## 什么时候重新确认方案
 
 以下变化必须先更新工单，再由用户确认：

tests/test_harness_docs.py

@@ -13,6 +13,7 @@ from check_harness import (  # noqa: E402
     CORE_PAGE_PATHS,
     REQUIRED_FILES,
     check_core_documents,
+    check_agent_efficiency_rules,
     check_task_template,
     core_mapping_errors,
     missing_sections,
@@ -55,5 +56,12 @@ class TaskTemplateTests(unittest.TestCase):
         self.assertEqual(errors, [])
 
 
+class AgentRuleTests(unittest.TestCase):
+    def test_agent_efficiency_sections_are_required(self) -> None:
+        errors: list[str] = []
+        check_agent_efficiency_rules(errors)
+        self.assertEqual(errors, [])
+
+
 if __name__ == "__main__":
     unittest.main()