增加 Agent 效率与范围控制规则 #4

New Issue

2026-08-08T09:35:48+08:00

ila commented

2026-08-08 09:35:48 +08:00

基本信息

类型：需求
所属 Epic：无
所属 MVP / 版本：无
阶段：已完成

要解决什么

当前 DevHarness 对安全、工单、测试、Wiki 和归档闭环约束完整，但尚未明确限制 Agent 的无关扩展、重复检查、预防性验证和完成后的继续优化。新项目使用时可能出现超出字面范围、重复读取环境、同时猜测多个错误原因或在达到验收后继续工作的情况。

目标是在不削弱安全和必要闭环的前提下，增加效率与范围控制规则。

做什么 / 不做什么

做：
- 明确默认严格按用户确认的目标和单元任务范围执行。
- 限制无关文档、脚本、备份、框架、重构和扩展性设计。
- 建立“必要前置检查 → 最小执行 → 首个真实错误 → 最小修复”的渐进闭环。
- 允许复用同一任务、同一环境状态下已经验证的事实，并定义失效条件。
- 明确最小验收包含用户验收标准和仓库强制闭环。
- 相邻问题只提示或单独建单，不自动处理。
- 更新开发工作流 Wiki、Agent 规则、Claude 入口和对应结构检查。
不做：
- 不跳过安全、工作区、破坏性目标、迁移、权限等必要前置检查。
- 不跳过代码修改后的受影响测试、最终验收、提交前状态或推送前远端检查。
- 不改变 Skill 和平台级触发规则。
- 不新增辅助脚本、执行框架或缓存系统。
- 不修改产品代码。

已确认方案

新增四组规则：

严格控制范围：不主动扩展相邻问题，不新增与目标和仓库强制规则无关的产物。
渐进执行和修复：完成已知必要前置检查后，用最小命令获得真实反馈，一次处理首个可行动错误。
复用已验证事实：仅在会话、环境、代码、配置、依赖、凭据、远端状态或关键前提变化时重检。
明确停止条件：完成工单验收和强制闭环后立即停止，相邻问题只提示或另建单。

规则优先级：本节只能减少无关工作，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档。

预计修改文件：

Gitea Wiki Development-Workflow
AGENTS.md
CLAUDE.md
docs/01-workflow.md 镜像
dev_scripts/check_harness.py
tests/test_harness_docs.py

文档影响

更新开发工作流
更新 Agent 和 Claude 入口规则
不影响项目档案、代码地图、业务规则、常见修改和故障排查，原因：本任务只调整通用执行纪律

验收标准

默认范围限制明确，但不禁止任务必需或仓库强制产物。
渐进执行规则保留安全和高风险前置检查。
已验证事实复用包含清晰失效条件和必须重检的例外。
最小验收明确包含测试、文档影响、Wiki、提交和证据回写。
相邻问题不会自动混入当前任务。
Harness 能检查开发工作流中的四组核心规则章节。
Wiki 镜像、自动化测试和严格检查通过。

验证方式

python -m unittest discover -s tests -v
python dev_scripts/check_harness.py --strict
python dev_scripts/sync_wiki_docs.py --check
python -m compileall -q dev_scripts tests
git diff --check

人工核对规则没有与永久安全规则、工单闭环和 Skill 触发要求冲突。

风险和回退

风险：过度强调速度导致跳过必要验证；“同一任务指纹”定义不清导致错误复用旧事实；“最小验收”被误解为首次运行成功。

控制：明确规则优先级、状态失效条件和必须重检项；使用“同一任务和同一环境状态”替代不透明的任务指纹。

回退：通过 Wiki revision 和 Git 提交恢复原开发工作流与 Agent 规则。

## 基本信息 - 类型：需求 - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：已完成 ## 要解决什么当前 DevHarness 对安全、工单、测试、Wiki 和归档闭环约束完整，但尚未明确限制 Agent 的无关扩展、重复检查、预防性验证和完成后的继续优化。新项目使用时可能出现超出字面范围、重复读取环境、同时猜测多个错误原因或在达到验收后继续工作的情况。目标是在不削弱安全和必要闭环的前提下，增加效率与范围控制规则。 ## 做什么 / 不做什么 - 做： - 明确默认严格按用户确认的目标和单元任务范围执行。 - 限制无关文档、脚本、备份、框架、重构和扩展性设计。 - 建立“必要前置检查 → 最小执行 → 首个真实错误 → 最小修复”的渐进闭环。 - 允许复用同一任务、同一环境状态下已经验证的事实，并定义失效条件。 - 明确最小验收包含用户验收标准和仓库强制闭环。 - 相邻问题只提示或单独建单，不自动处理。 - 更新开发工作流 Wiki、Agent 规则、Claude 入口和对应结构检查。 - 不做： - 不跳过安全、工作区、破坏性目标、迁移、权限等必要前置检查。 - 不跳过代码修改后的受影响测试、最终验收、提交前状态或推送前远端检查。 - 不改变 Skill 和平台级触发规则。 - 不新增辅助脚本、执行框架或缓存系统。 - 不修改产品代码。 ## 已确认方案新增四组规则： 1. 严格控制范围：不主动扩展相邻问题，不新增与目标和仓库强制规则无关的产物。 2. 渐进执行和修复：完成已知必要前置检查后，用最小命令获得真实反馈，一次处理首个可行动错误。 3. 复用已验证事实：仅在会话、环境、代码、配置、依赖、凭据、远端状态或关键前提变化时重检。 4. 明确停止条件：完成工单验收和强制闭环后立即停止，相邻问题只提示或另建单。规则优先级：本节只能减少无关工作，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档。预计修改文件： - Gitea Wiki `Development-Workflow` - `AGENTS.md` - `CLAUDE.md` - `docs/01-workflow.md` 镜像 - `dev_scripts/check_harness.py` - `tests/test_harness_docs.py` ## 文档影响 - [x] 更新开发工作流 - [x] 更新 Agent 和 Claude 入口规则 - [x] 不影响项目档案、代码地图、业务规则、常见修改和故障排查，原因：本任务只调整通用执行纪律 ## 验收标准 - [x] 默认范围限制明确，但不禁止任务必需或仓库强制产物。 - [x] 渐进执行规则保留安全和高风险前置检查。 - [x] 已验证事实复用包含清晰失效条件和必须重检的例外。 - [x] 最小验收明确包含测试、文档影响、Wiki、提交和证据回写。 - [x] 相邻问题不会自动混入当前任务。 - [x] Harness 能检查开发工作流中的四组核心规则章节。 - [x] Wiki 镜像、自动化测试和严格检查通过。 ## 验证方式 ```powershell python -m unittest discover -s tests -v python dev_scripts/check_harness.py --strict python dev_scripts/sync_wiki_docs.py --check python -m compileall -q dev_scripts tests git diff --check ``` 人工核对规则没有与永久安全规则、工单闭环和 Skill 触发要求冲突。 ## 风险和回退风险：过度强调速度导致跳过必要验证；“同一任务指纹”定义不清导致错误复用旧事实；“最小验收”被误解为首次运行成功。控制：明确规则优先级、状态失效条件和必须重检项；使用“同一任务和同一环境状态”替代不透明的任务指纹。回退：通过 Wiki revision 和 Git 提交恢复原开发工作流与 Agent 规则。

ila commented

2026-08-08 09:35:56 +08:00

用户已确认方案，开始实施。工作区干净；本任务只修改执行纪律相关规则和检查，不新增辅助脚本或执行框架。

ila commented

2026-08-08 09:38:28 +08:00

实现完成，进入待验收

最终方案

在 AGENTS.md 和 Development-Workflow 中加入“效率与范围控制”，明确其优先级低于安全、工单和必要闭环。
严格控制范围：只禁止无关产物和无关验证，不禁止任务必需文档、受影响测试和仓库强制步骤。
渐进执行：完成必要前置检查后，以最小命令获得真实反馈，一次处理首个可行动错误。
复用事实：仅在同一任务和同一环境状态下复用，并列出会话、代码、配置、依赖、凭据、远端状态等失效条件。
明确停止：完成用户验收标准和仓库闭环后停止；首次运行成功不等于最小验收。
Claude 入口增加简明引用；Harness 同时检查 Wiki 镜像和 AGENTS 的四组章节。
未新增辅助脚本、缓存系统或执行框架。

方案差异

无影响用户确认结果的方案差异。采用“同一任务和同一环境状态”而非“任务指纹”，避免引入未定义概念。

验证结果

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：通过。
人工核对：规则保留安全、高风险前置检查、代码修改后的测试、提交前状态、推送前远端检查、Skill 触发和完整验收闭环。
未验证部分：Agent 在不同新项目中的实际效率提升需要后续任务数据验证。

实现提交

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

状态保持待验收，用户确认前不关闭。

## 实现完成，进入待验收 ### 最终方案 - 在 `AGENTS.md` 和 Development-Workflow 中加入“效率与范围控制”，明确其优先级低于安全、工单和必要闭环。 - 严格控制范围：只禁止无关产物和无关验证，不禁止任务必需文档、受影响测试和仓库强制步骤。 - 渐进执行：完成必要前置检查后，以最小命令获得真实反馈，一次处理首个可行动错误。 - 复用事实：仅在同一任务和同一环境状态下复用，并列出会话、代码、配置、依赖、凭据、远端状态等失效条件。 - 明确停止：完成用户验收标准和仓库闭环后停止；首次运行成功不等于最小验收。 - Claude 入口增加简明引用；Harness 同时检查 Wiki 镜像和 AGENTS 的四组章节。 - 未新增辅助脚本、缓存系统或执行框架。 ### 方案差异无影响用户确认结果的方案差异。采用“同一任务和同一环境状态”而非“任务指纹”，避免引入未定义概念。 ### 验证结果 - `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`：通过。 - 人工核对：规则保留安全、高风险前置检查、代码修改后的测试、提交前状态、推送前远端检查、Skill 触发和完整验收闭环。 - 未验证部分：Agent 在不同新项目中的实际效率提升需要后续任务数据验证。 ### 实现提交 - `d3df733` docs: 增加 Agent 效率与范围控制 (#4) 状态保持待验收，用户确认前不关闭。

ila referenced this issue from a commit

2026-08-08 09:40:42 +08:00

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

ila referenced this issue from a commit

2026-08-08 09:40:42 +08:00

docs: 归档任务 #4

ila commented

2026-08-08 09:40:50 +08:00

归档与推送完成

Wiki 归档：Task-4-Agent-Efficiency-Scope
Wiki revision：d659521d10749dfde343b5524114efdda8251a03
本地镜像：docs/task/4-Agent效率与范围控制.md
实现提交：d3df733 docs: 增加 Agent 效率与范围控制 (#4)
归档提交：e29b9e4 docs: 归档任务 #4
两个任务提交已推送到 origin/main，远端当前为 e29b9e4。
最终验证：17/17 测试通过、Harness 严格检查通过、14/14 Wiki 映射一致、Python 编译和 diff 检查通过。
工单保持“待验收”，用户确认前不关闭。

## 归档与推送完成 - Wiki 归档：[Task-4-Agent-Efficiency-Scope](http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-4-Agent-Efficiency-Scope.-) - Wiki revision：`d659521d10749dfde343b5524114efdda8251a03` - 本地镜像：`docs/task/4-Agent效率与范围控制.md` - 实现提交：`d3df733` docs: 增加 Agent 效率与范围控制 (#4) - 归档提交：`e29b9e4` docs: 归档任务 #4 - 两个任务提交已推送到 `origin/main`，远端当前为 `e29b9e4`。 - 最终验证：17/17 测试通过、Harness 严格检查通过、14/14 Wiki 映射一致、Python 编译和 diff 检查通过。 - 工单保持“待验收”，用户确认前不关闭。

ila referenced this issue from a commit

2026-08-08 10:00:19 +08:00

docs: 记录任务 #4 验收完成

ila commented

2026-08-08 10:00:28 +08:00