docs: 归档任务 #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 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
+- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
+
 ## 什么时候重新确认方案
 
 以下变化必须先更新工单，再由用户确认：

docs/task/4-Agent效率与范围控制.md

@@ -0,0 +1,70 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-4-Agent-Efficiency-Scope
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-4-Agent-Efficiency-Scope.-
+wiki_revision: d659521d10749dfde343b5524114efdda8251a03
+synchronized_at: 2026-08-08T01:39:24Z
+<!-- gitea-wiki-mirror:end -->
+
+# 4 增加 Agent 效率与范围控制规则
+
+- 类型：需求
+- 所属 Epic：无
+- 所属 MVP / 版本：无
+- 状态：待验收
+- 日期：2026-08-08
+- Gitea 工单：[opc/dev_harness#4](http://ilaer.eicp.net:8418/opc/dev_harness/issues/4)
+- Wiki 页面：Task-4-Agent-Efficiency-Scope
+- Wiki revision：见本地镜像头
+
+## 背景与目标
+
+DevHarness 已有完整安全和交付闭环，但缺少对无关扩展、重复检查、预防性验证和完成后继续优化的限制。本任务在不削弱安全、测试和归档的前提下增加效率规则。
+
+## 最终方案
+
+- 严格控制范围：默认按用户确认目标和工单执行，只限制无关产物、无关验证和相邻问题。
+- 渐进执行和修复：完成必要前置检查后，用最小命令获得真实反馈，一次处理首个可行动错误。
+- 复用已验证事实：只在同一任务和同一环境状态下复用，关键前提变化时重检。
+- 明确停止条件：完成用户验收标准和仓库必要闭环后停止，首次运行成功不等于完成。
+- 安全、高风险前置检查、代码修改后的测试、提交前状态、推送前远端检查和 Skill 规则不允许省略。
+- Harness 检查开发工作流镜像和 AGENTS 中四组章节是否存在。
+
+## 修改文件
+
+- `AGENTS.md`：增加效率与范围控制的完整规则。
+- `CLAUDE.md`：增加简明执行入口。
+- `Development-Workflow` Wiki：增加长期工作流说明。
+- `docs/01-workflow.md`：Wiki 更新后的只读镜像。
+- `dev_scripts/check_harness.py`：检查四组核心规则章节。
+- `tests/test_harness_docs.py`：验证当前 Agent 规则结构。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 范围限制不禁止任务必需或仓库强制产物 | 通过 |
+| 渐进执行保留安全和高风险前置检查 | 通过 |
+| 事实复用包含失效条件和重检例外 | 通过 |
+| 最小验收包含完整项目闭环 | 通过 |
+| 相邻问题不会自动混入 | 通过 |
+| Harness 检查四组章节 | 通过 |
+| Wiki、测试和严格检查通过 | 通过 |
+
+## 测试
+
+- 执行命令：`python -m unittest discover -s tests -v`
+- 结果：17/17 通过。
+- 执行命令：`python dev_scripts/check_harness.py --strict`
+- 结果：通过。
+- 执行命令：`python dev_scripts/sync_wiki_docs.py --check`
+- 结果：13/13 映射一致。
+- 执行命令：`python -m compileall -q dev_scripts tests`
+- 结果：通过。
+- 执行命令：`git diff --check`
+- 结果：通过。
+- **未验证部分**：不同新项目中的实际效率提升需要通过后续任务数据验证。
+
+## 相关提交
+
+- `d3df733` docs: 增加 Agent 效率与范围控制 (#4)

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()

wiki-docs.json

@@ -55,6 +55,10 @@
     {
       "page": "Task-3-Dev-Scripts-Rename",
       "path": "docs/task/3-dev_scripts目录重命名.md"
+    },
+    {
+      "page": "Task-4-Agent-Efficiency-Scope",
+      "path": "docs/task/4-Agent效率与范围控制.md"
     }
   ]
 }