docs: 增加 Agent 效率与范围控制 (#4)
This commit is contained in:
QiuSW
@@ -40,6 +40,38 @@
|
||||
|
||||
Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。
|
||||
|
||||
### 效率与范围控制
|
||||
|
||||
本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。
|
||||
|
||||
#### 严格控制范围
|
||||
|
||||
- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
|
||||
- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
|
||||
- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
|
||||
- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。
|
||||
|
||||
#### 渐进执行和修复
|
||||
|
||||
- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
|
||||
- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
|
||||
- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
|
||||
- 不在真实证据出现前堆叠与已知风险无关的预防性检查。
|
||||
- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。
|
||||
|
||||
#### 复用已验证事实
|
||||
|
||||
- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
|
||||
- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
|
||||
- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
|
||||
- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。
|
||||
|
||||
#### 明确停止条件
|
||||
|
||||
- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
|
||||
- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
|
||||
- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
|
||||
|
||||
## 4. 工单层级
|
||||
|
||||
```text
|
||||
|
||||
@@ -15,6 +15,7 @@ Claude Code 开始任何工作前，必须按顺序阅读：
|
||||
- 方案经用户确认并建立单元任务工单后，才能修改产品代码。
|
||||
- 只修改当前工单范围内的文件，保留用户已有和无关的改动。
|
||||
- 在单元任务中明确文档影响；入口、命令、配置、数据、业务规则或排错方式变化时先更新对应 Wiki。
|
||||
- 严格遵守 `AGENTS.md` 的效率与范围控制：优先真实反馈、复用未失效的检查结果、完成必要闭环后停止，但不得省略安全和最终验收。
|
||||
- 实现、测试、Git 提交、待验收、Wiki 任务归档、导出本地镜像和关闭工单的顺序不得跳过。
|
||||
- 长期文档先修改 Wiki，再导出 `docs/`；不得直接编辑镜像作为最终结果。
|
||||
- 未经用户明确验收，不得关闭工单。
|
||||
|
||||
@@ -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:
|
||||
|
||||
+34
-2
@@ -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
|
||||
synchronized_at: 2026-08-08T01:16:48Z
|
||||
wiki_revision: d00ceed847becc95439296f618bd8a461c0a4c0f
|
||||
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 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
|
||||
- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
|
||||
|
||||
## 什么时候重新确认方案
|
||||
|
||||
以下变化必须先更新工单，再由用户确认：
|
||||
|
||||
@@ -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()
|
||||
|
||||
Reference in New Issue
Block a user