opc/dev_harness
2
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

精简 AGENTS 中重复的解释性内容 #5

New Issue
Closed
opened 2026-08-08 10:01:24 +08:00 by ila · 4 comments
ila commented 2026-08-08 10:01:24 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：重构
  • 所属 Epic：无
  • 所属 MVP / 版本：无
  • 阶段：已完成

要解决什么

当前 AGENTS.md 的安全、工单、效率、验证和验收规则合理，但部分解释性内容已在 Wiki 中完整维护，形成重复：

  • Epic/MVP/单元任务的层级图和定义；
  • 初级维护者风险分级示例表；
  • 核心文档完整清单和稳定文档说明；
  • 归档流程的部分细节；
  • dev_scripts/ 目录职责说明。

目标是让 AGENTS.md 更像简洁的强制规则入口，详细解释继续由现有 Wiki 页面维护。

做什么 / 不做什么

  • 做：
    • 核对现有 Wiki 已覆盖准备精简的解释性内容。
    • 精简工单层级说明，保留“单元任务是唯一实施单位”和父工单索引规则。
    • 精简归档步骤，保留强制顺序、命令、待验收和关闭条件。
    • 用简短强制规则替代初级维护者风险示例表，并链接常见修改指南。
    • 用文档更新触发条件替代完整核心文档清单，并链接新项目初始化指南。
    • 保留 dev_scripts/ 不与业务脚本混放的项目红线。
  • 不做：
    • 不删除或削弱永久安全规则。
    • 不删除工单、方案确认、工作区保护、效率控制、测试、Wiki、提交、验收和归档要求。
    • 不修改 Wiki 现有内容；经核对，目标页面已经完整承接说明。
    • 不改变程序行为、工具命令或工单模板。
    • 不修改历史任务归档。

已确认方案

详细说明继续由以下 Wiki 页面维护：

  • 工单层级与归档：Development-Workflow、Business-Rules-and-Glossary。
  • 风险示例：Common-Changes。
  • 核心文档清单：New-Project-Documentation-Setup。
  • 目录职责：Project-Profile、Architecture-and-Code-Map。

AGENTS.md 只保留 Agent 必须直接执行的结论，并使用本地只读镜像链接作为入口。

预计修改文件：

  • AGENTS.md
  • 如结构检查需要同步调整，则修改 dev_scripts/check_harness.py 和对应测试
  • 任务归档及 wiki-docs.json

文档影响

  • 不修改长期 Wiki 内容，原因：目标解释已存在并已核对 revision
  • 精简 Agent 入口规则，保留指向现有 Wiki 镜像的链接
  • 历史归档不修改

验收标准

  • 永久安全、建单、方案确认、工作区、效率、验证、Wiki、提交、验收和归档规则全部保留。
  • 工单层级、风险分级、核心文档和目录说明的详细解释不再在 AGENTS 重复。
  • AGENTS 对每类被精简内容提供明确的现有文档入口。
  • 单元任务仍是唯一实施单位，父工单仍只维护索引。
  • 高风险修改仍必须停止并等待人工确认。
  • 用户验收前不得关闭工单。
  • Harness 严格检查和测试通过。

验证方式

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

另外对比精简前后的强制关键词，并人工确认链接目标存在。

风险和回退

风险：过度精简导致 Agent 只读取 AGENTS 时遗漏强制步骤；链接目标未来变化造成入口失效。

控制：只删除解释和示例，不删除结论；使用受 Harness 映射保护的本地 Wiki 镜像路径；新增规则保留检查。

回退：恢复本任务 Git 提交。Wiki 本身不修改，无需回退页面。

## 基本信息 - 类型：重构 - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：已完成 ## 要解决什么 当前 `AGENTS.md` 的安全、工单、效率、验证和验收规则合理，但部分解释性内容已在 Wiki 中完整维护，形成重复： - Epic/MVP/单元任务的层级图和定义； - 初级维护者风险分级示例表； - 核心文档完整清单和稳定文档说明； - 归档流程的部分细节； - `dev_scripts/` 目录职责说明。 目标是让 `AGENTS.md` 更像简洁的强制规则入口，详细解释继续由现有 Wiki 页面维护。 ## 做什么 / 不做什么 - 做： - 核对现有 Wiki 已覆盖准备精简的解释性内容。 - 精简工单层级说明，保留“单元任务是唯一实施单位”和父工单索引规则。 - 精简归档步骤，保留强制顺序、命令、待验收和关闭条件。 - 用简短强制规则替代初级维护者风险示例表，并链接常见修改指南。 - 用文档更新触发条件替代完整核心文档清单，并链接新项目初始化指南。 - 保留 `dev_scripts/` 不与业务脚本混放的项目红线。 - 不做： - 不删除或削弱永久安全规则。 - 不删除工单、方案确认、工作区保护、效率控制、测试、Wiki、提交、验收和归档要求。 - 不修改 Wiki 现有内容；经核对，目标页面已经完整承接说明。 - 不改变程序行为、工具命令或工单模板。 - 不修改历史任务归档。 ## 已确认方案 详细说明继续由以下 Wiki 页面维护： - 工单层级与归档：Development-Workflow、Business-Rules-and-Glossary。 - 风险示例：Common-Changes。 - 核心文档清单：New-Project-Documentation-Setup。 - 目录职责：Project-Profile、Architecture-and-Code-Map。 `AGENTS.md` 只保留 Agent 必须直接执行的结论，并使用本地只读镜像链接作为入口。 预计修改文件： - `AGENTS.md` - 如结构检查需要同步调整，则修改 `dev_scripts/check_harness.py` 和对应测试 - 任务归档及 `wiki-docs.json` ## 文档影响 - [x] 不修改长期 Wiki 内容，原因：目标解释已存在并已核对 revision - [x] 精简 Agent 入口规则，保留指向现有 Wiki 镜像的链接 - [x] 历史归档不修改 ## 验收标准 - [x] 永久安全、建单、方案确认、工作区、效率、验证、Wiki、提交、验收和归档规则全部保留。 - [x] 工单层级、风险分级、核心文档和目录说明的详细解释不再在 AGENTS 重复。 - [x] AGENTS 对每类被精简内容提供明确的现有文档入口。 - [x] 单元任务仍是唯一实施单位，父工单仍只维护索引。 - [x] 高风险修改仍必须停止并等待人工确认。 - [x] 用户验收前不得关闭工单。 - [x] Harness 严格检查和测试通过。 ## 验证方式 ```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 ``` 另外对比精简前后的强制关键词，并人工确认链接目标存在。 ## 风险和回退 风险：过度精简导致 Agent 只读取 AGENTS 时遗漏强制步骤；链接目标未来变化造成入口失效。 控制：只删除解释和示例，不删除结论；使用受 Harness 映射保护的本地 Wiki 镜像路径；新增规则保留检查。 回退：恢复本任务 Git 提交。Wiki 本身不修改，无需回退页面。
ila commented 2026-08-08 10:01:31 +08:00
Author
Owner
Copy Link
Copy Source

用户已确认精简建议，开始实施。已核对六个现有 Wiki 页面包含工单层级、术语状态、风险示例、核心文档清单和目录职责，因此本任务不修改 Wiki 正文，只精简 AGENTS 的重复解释。

用户已确认精简建议，开始实施。已核对六个现有 Wiki 页面包含工单层级、术语状态、风险示例、核心文档清单和目录职责，因此本任务不修改 Wiki 正文，只精简 AGENTS 的重复解释。
ila commented 2026-08-08 10:03:57 +08:00
Author
Owner
Copy Link
Copy Source

实现完成，进入待验收

最终方案

  • 工单层级移除图示和重复定义，保留单元任务唯一实施单位、父工单索引和同步规则，链接开发工作流与业务术语。
  • 归档流程由 8 步压缩为 5 步，保留待验收、Wiki 优先、镜像检查、独立归档提交、证据回写和用户验收关闭。
  • 初级维护者风险示例表改为三条强制结论，详细示例链接 Common-Changes。
  • 核心文档完整清单改为文档影响触发条件，清单链接新项目初始化指南。
  • dev_scripts/ 不与业务脚本混放的项目红线保留。
  • Harness 除效率章节外，增加单元任务、高风险停止、用户验收、Wiki 优先和提交范围等关键文本检查。
  • 经核对，详细说明已存在于六个 Wiki 页面，因此未修改长期 Wiki 正文。

Wiki 承接证据

  • Development-Workflow d00ceed847be...：Epic、MVP 和归档。
  • Business-Rules-and-Glossary 7534fd601570...：术语和工单状态。
  • Common-Changes 9b223d2feada...：风险分级示例。
  • New-Project-Documentation-Setup a0eeab23a416...：核心文档清单。
  • Project-Profile 2a81c9e4508c...、Architecture-and-Code-Map f93132ddd5bb...：目录职责。

验证结果

  • AGENTS.md 非空规则行：115 降至 102。
  • python -m unittest discover -s tests -v：17/17 通过。
  • python dev_scripts/check_harness.py --strict：通过。
  • python dev_scripts/sync_wiki_docs.py --check：14/14 映射一致。
  • python -m compileall -q dev_scripts tests：通过。
  • git diff --check：通过。
  • 人工核对：安全、建单、方案确认、工作区、效率、验证、Wiki、提交、验收、归档和高风险停止规则均保留。
  • 未验证部分：无。

实现提交

  • c9f1bc8 refactor: 精简 AGENTS 重复说明 (#5)

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

## 实现完成，进入待验收 ### 最终方案 - 工单层级移除图示和重复定义，保留单元任务唯一实施单位、父工单索引和同步规则，链接开发工作流与业务术语。 - 归档流程由 8 步压缩为 5 步，保留待验收、Wiki 优先、镜像检查、独立归档提交、证据回写和用户验收关闭。 - 初级维护者风险示例表改为三条强制结论，详细示例链接 Common-Changes。 - 核心文档完整清单改为文档影响触发条件，清单链接新项目初始化指南。 - `dev_scripts/` 不与业务脚本混放的项目红线保留。 - Harness 除效率章节外，增加单元任务、高风险停止、用户验收、Wiki 优先和提交范围等关键文本检查。 - 经核对，详细说明已存在于六个 Wiki 页面，因此未修改长期 Wiki 正文。 ### Wiki 承接证据 - Development-Workflow `d00ceed847be...`：Epic、MVP 和归档。 - Business-Rules-and-Glossary `7534fd601570...`：术语和工单状态。 - Common-Changes `9b223d2feada...`：风险分级示例。 - New-Project-Documentation-Setup `a0eeab23a416...`：核心文档清单。 - Project-Profile `2a81c9e4508c...`、Architecture-and-Code-Map `f93132ddd5bb...`：目录职责。 ### 验证结果 - `AGENTS.md` 非空规则行：115 降至 102。 - `python -m unittest discover -s tests -v`：17/17 通过。 - `python dev_scripts/check_harness.py --strict`：通过。 - `python dev_scripts/sync_wiki_docs.py --check`：14/14 映射一致。 - `python -m compileall -q dev_scripts tests`：通过。 - `git diff --check`：通过。 - 人工核对：安全、建单、方案确认、工作区、效率、验证、Wiki、提交、验收、归档和高风险停止规则均保留。 - 未验证部分：无。 ### 实现提交 - `c9f1bc8` refactor: 精简 AGENTS 重复说明 (#5) 状态保持待验收，用户确认前不关闭。
ila referenced this issue from a commit 2026-08-08 10:06:52 +08:00
docs: 归档任务 #5
ila commented 2026-08-08 10:07:03 +08:00
Author
Owner
Copy Link
Copy Source

最终实施与归档证据

  • 状态：待验收（未关闭）
  • 实现提交：c9f1bc8（refactor: 精简 AGENTS 重复说明 (#5)）
  • 归档提交：2509d9e（docs: 归档任务 #5）
  • 远端 main：已推送至 2509d9e
  • Wiki 归档：Task-5-Simplify-Agents
  • Wiki 版本：28df4129a9d4d90c42cd24b14a69ab0bcbd6e210
  • 本地只读镜像：docs/task/5-精简AGENTS重复说明.md

最终验证

  • python -m unittest discover -s tests -v：17/17 通过
  • python dev_scripts/check_harness.py --strict：通过
  • python dev_scripts/sync_wiki_docs.py --check：15/15 映射一致
  • python -m compileall -q dev_scripts tests：通过
  • git diff --check：通过
  • 工作区：干净

请按验收标准检查；收到明确“#5 验收通过”后再关闭工单。

## 最终实施与归档证据 - 状态：待验收（未关闭） - 实现提交：`c9f1bc8`（`refactor: 精简 AGENTS 重复说明 (#5)`） - 归档提交：`2509d9e`（`docs: 归档任务 #5`） - 远端 `main`：已推送至 `2509d9e` - Wiki 归档：[Task-5-Simplify-Agents](http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-5-Simplify-Agents.-) - Wiki 版本：`28df4129a9d4d90c42cd24b14a69ab0bcbd6e210` - 本地只读镜像：`docs/task/5-精简AGENTS重复说明.md` ### 最终验证 - `python -m unittest discover -s tests -v`：17/17 通过 - `python dev_scripts/check_harness.py --strict`：通过 - `python dev_scripts/sync_wiki_docs.py --check`：15/15 映射一致 - `python -m compileall -q dev_scripts tests`：通过 - `git diff --check`：通过 - 工作区：干净 请按验收标准检查；收到明确“#5 验收通过”后再关闭工单。
ila closed this issue 2026-08-08 11:27:48 +08:00
ila commented 2026-08-08 11:28:05 +08:00
Author
Owner
Copy Link
Copy Source

验收完成

用户已明确确认 #5 验收通过，工单已关闭。

  • 验收归档提交：d1136c2（已推送至远端 main）
  • Wiki 归档：任务 #5
  • Wiki revision：2096d9eee938c7680c1188dd6a5fbe490d1fd69c
  • 本地只读镜像：docs/task/5-精简AGENTS重复说明.md
  • 最终验证：19/19 单元测试通过、Harness 严格检查通过、17/17 Wiki 镜像一致
## 验收完成 用户已明确确认 #5 验收通过，工单已关闭。 - 验收归档提交：`d1136c2`（已推送至远端 `main`） - Wiki 归档：[任务 #5](http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-5-Simplify-Agents.-) - Wiki revision：`2096d9eee938c7680c1188dd6a5fbe490d1fd69c` - 本地只读镜像：`docs/task/5-精简AGENTS重复说明.md` - 最终验证：19/19 单元测试通过、Harness 严格检查通过、17/17 Wiki 镜像一致
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: opc/dev_harness#5