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

新增已有项目接入 DevHarness 指南 #12

New Issue
Closed
opened 2026-08-16 23:06:45 +08:00 by ila · 0 comments
ila commented 2026-08-16 23:06:45 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：单元任务
  • 状态：已完成
  • 所属 Epic：无
  • 所属 MVP / 版本：无

依赖与并行

  • 前置工单：#11
  • 是否允许与前置工单并行：是
  • 原因：#11 的实现和归档已经完成、仅等待验收；本任务新增独立的存量项目接入指南，不改变 #11 的交付文档方案。

原始需求

  • 来源：用户与 Agent 对话
  • 提出时间：2026-08-10
  • 关键原话或脱敏摘要：“接受你的建议，建工单”
  • 已确认上下文：为经常将 DevHarness 接入已有项目的场景，增加专门的“已有项目接入 DevHarness 指南”。

要解决什么

现有“新项目文档初始化”主要面向从模板创建的新项目。已有项目通常已经存在代码、规则、文档、工单、Wiki、提交历史和未完成工作，不能直接套用新项目初始化中的清理或替换步骤。

目标：提供一份面向 Claude、Codex 等 Agent 的存量项目增量接入指南，让 Agent 能先盘点现状、识别冲突、等待方案确认，再通过单元工单安全接入 DevHarness。

做什么 / 不做什么

做

  • 在 Gitea Wiki 新增“已有项目接入 DevHarness 指南”。
  • 说明适用范围以及与“新项目文档初始化”的区别。
  • 给出接入前只读盘点清单。
  • 规定已有规则、���档、Git 历史和未提交改动的保留原则。
  • 规定 Gitea 工单、Wiki、docs/ 镜像和 Harness 工具的增量接入顺序。
  • 给出可以直接发送给其他 Agent 的“只分析”和“确认后实施”指令模板。
  • 给出冲突处理、停止条件、回退和最小验收清单。
  • 更新 Home 和相关入口，使已有项目接入指南可发现。
  • 将页面显式映射到本地 docs/，纳入 Harness 核心映射和章节检查。
  • 更新相关单元测试。
  • 按 Wiki-first 流程同步镜像、提交、归档并等待验收。

不做

  • 不创建自动迁移或批量复制脚本。
  • 不自动修改任何已有业务项目。
  • 不删除、覆盖、重命名已有项目的规则、文档、Wiki 页面或历史归档。
  • 不把 DevHarness 自身的任务归档复制到业务项目。
  • 不要求一次性迁移全部旧文档。
  • 不修改 DevHarness 的事实来源边界。
  • 不把新项目初始化和已有项目接入强行合并成一个复杂流程。

已确认方案

采用单独稳定主题页进行最小实现：

  1. 新增 Existing-Project-Adoption-Guide Wiki 页面。
  2. 推荐“盘点现状 → 确认差异方案 → 建单 → 增量接入规则和工单 → 迁移长期文档到 Wiki → 建立镜像映射 → 启用严格检查”的顺序。
  3. 明确必须保留已有 AGENTS.md、README、文档、Git 历史、任务状态和无关工作区改动，冲突内容由负责人确认后合并。
  4. 提供两段可复制指令：
    • 只读分析已有项目并输出接入方案；
    • 方案确认后建工单并实施。
  5. 新增 Home 入口、本地只读镜像、Harness 章节检查和相应测试。
  6. 不增加迁移自动化，不修改实际业务项目。

预计修改文件：

  • Gitea Wiki：Existing-Project-Adoption-Guide
  • Gitea Wiki：Home
  • wiki-docs.json
  • dev_scripts/check_harness.py
  • tests/test_harness_docs.py
  • Wiki 导出的对应 docs/ 镜像
  • 本任务 Wiki 归档及其镜像

需求变化记录

日期 变化内容 原因 用户确认
2026-08-10 首次确认，无变化 接受 Agent 建议 是

文档影响

  • 不影响长期文档，原因：
  • 更新项目档案或本地开发与验证
  • 更新架构与代码地图
  • 更新业务规则与术语
  • 更新常见修改或故障排查
  • 更新其他 Wiki 页面：新增 Existing-Project-Adoption-Guide，更新 Home

交付文档影响

  • 无交付文档影响，原因：[internal] 本任务只增加内部开发流程指南，不改变产品交付给客户或岗位人员的操作方法。
  • 更新已有交付文档，受众与页面：
  • 新增交付文档，受众与页面：
  • 需要目标岗位或客户代表验证：否；验证方式：由维护者检查指令可复制性和接入边界是否完整。

验收标准

  • Wiki 存在独立的已有项目接入指南。
  • 指南明确区分已有项目接入与新项目初始化。
  • 指南覆盖只读盘点、已有内容保护、冲突处理和停止条件。
  • 指南给出增量接入顺序，不要求一次性替换或迁移。
  • 指南包含可以直接发送给 Agent 的分析指令和实施指令。
  • 指南明确禁止复制 DevHarness 历史归档和覆盖已有项目内容。
  • Home 可以进入已有项目接入指南。
  • 页面具有显式 Wiki 镜像映射和有效 revision。
  • Harness 严格检查和单元测试通过。
  • 实现提交与归档提交已推送。
  • 工单已在用户明确验收通过后关闭。

验证方式

  • python dev_scripts/check_harness.py --strict
  • python -m unittest discover -s tests -v
  • python dev_scripts/sync_wiki_docs.py --check
  • git diff --check
  • git status --short --branch
  • 人工检查两段 Agent 指令能否直接复制，并且不授权覆盖、删除或自动迁移已有项目内容。

风险和回退

  • 风险：Agent 把“接���模板”理解为覆盖已有规则；通过只读盘点、冲突清单、方案确认和增量合并控制。
  • 风险：把旧项目任务归档或历史文档错误带入新事实来源；通过禁止复制归档、逐页确认迁移控制。
  • 风险：同时维护 Wiki 和原本地长期文档形成双事实源；指南必须为每类文档明确迁移状态和最终事实来源。
  • 回退：恢复 Home、映射和 Harness 检查到任务前版本；新增 Wiki 页的删除属于破坏性操作，回退时需另行确认。

实施结果与证据

  • 实施结果：与已确认方案一致；未创建迁移脚本，未修改实际业务项目。
  • 线上 Wiki：
    • Existing-Project-Adoption-Guide，revision cad12048c8aa6f54ec6d2595a79c814233e18285
    • Home，revision 55d89b7aec659f55a61e7ceef881ef34a62d9379
    • Task-12-已有项目接入DevHarness指南，revision 902c90884fd8902d8346365bf588183fdb6b00a3
  • 本地镜像：
    • docs/08-existing-project-adoption.md
    • docs/task/12-已有项目接入DevHarness指南.md
  • 验证：
    • python dev_scripts/check_harness.py --strict：通过
    • python -m unittest discover -s tests -v：23/23 通过
    • python dev_scripts/sync_wiki_docs.py --check：25/25 一致
    • git diff --check：通过
    • 人工检查两段 Agent 指令：未授权覆盖、删除、重命名或自动迁移已有内容
  • 提交：
    • 0271a3e docs: 新增已有项目接入指南 (#12)
    • eba8515 docs: archive task #12
  • 未验证部分：未在真实业务仓库执行完整接入，这是已确认非目标；首次实际接入时应另建项目专用工单验证。
  • 验收结果：用户于 2026-08-10 明确验收通过。
  • 验收状态提交：105328e docs: record task #12 acceptance。
## 基本信息 - 类型：单元任务 - 状态：已完成 - 所属 Epic：无 - 所属 MVP / 版本：无 ## 依赖与并行 - 前置工单：#11 - 是否允许与前置工单并行：是 - 原因：#11 的实现和归档已经完成、仅等待验收；本任务新增独立的存量项目接入指南，不改变 #11 的交付文档方案。 ## 原始需求 - 来源：用户与 Agent 对话 - 提出时间：2026-08-10 - 关键原话或脱敏摘要：“接受你的建议，建工单” - 已确认上下文：为经常将 DevHarness 接入已有项目的场景，增加专门的“已有项目接入 DevHarness 指南”。 ## 要解决什么 现有“新项目文档初始化”主要面向从模板创建的新项目。已有项目通常已经存在代码、规则、文档、工单、Wiki、提交历史和未完成工作，不能直接套用新项目初始化中的清理或替换步骤。 目标：提供一份面向 Claude、Codex 等 Agent 的存量项目增量接入指南，让 Agent 能先盘点现状、识别冲突、等待方案确认，再通过单元工单安全接入 DevHarness。 ## 做什么 / 不做什么 ### 做 - 在 Gitea Wiki 新增“已有项目接入 DevHarness 指南”。 - 说明适用范围以及与“新项目文档初始化”的区别。 - 给出接入前只读盘点清单。 - 规定已有规则、���档、Git 历史和未提交改动的保留原则。 - 规定 Gitea 工单、Wiki、`docs/` 镜像和 Harness 工具的增量接入顺序。 - 给出可以直接发送给其他 Agent 的“只分析”和“确认后实施”指令模板。 - 给出冲突处理、停止条件、回退和最小验收清单。 - 更新 Home 和相关入口，使已有项目接入指南可发现。 - 将页面显式映射到本地 `docs/`，纳入 Harness 核心映射和章节检查。 - 更新相关单元测试。 - 按 Wiki-first 流程同步镜像、提交、归档并等待验收。 ### 不做 - 不创建自动迁移或批量复制脚本。 - 不自动修改任何已有业务项目。 - 不删除、覆盖、重命名已有项目的规则、文档、Wiki 页面或历史归档。 - 不把 DevHarness 自身的任务归档复制到业务项目。 - 不要求一次性迁移全部旧文档。 - 不修改 DevHarness 的事实来源边界。 - 不把新项目初始化和已有项目接入强行合并成一个复杂流程。 ## 已确认方案 采用单独稳定主题页进行最小实现： 1. 新增 `Existing-Project-Adoption-Guide` Wiki 页面。 2. 推荐“盘点现状 → 确认差异方案 → 建单 → 增量接入规则和工单 → 迁移长期文档到 Wiki → 建立镜像映射 → 启用严格检查”的顺序。 3. 明确必须保留已有 `AGENTS.md`、README、文档、Git 历史、任务状态和无关工作区改动，冲突内容由负责人确认后合并。 4. 提供两段可复制指令： - 只读分析已有项目并输出接入方案； - 方案确认后建工单并实施。 5. 新增 Home 入口、本地只读镜像、Harness 章节检查和相应测试。 6. 不增加迁移自动化，不修改实际业务项目。 预计修改文件： - Gitea Wiki：`Existing-Project-Adoption-Guide` - Gitea Wiki：`Home` - `wiki-docs.json` - `dev_scripts/check_harness.py` - `tests/test_harness_docs.py` - Wiki 导出的对应 `docs/` 镜像 - 本任务 Wiki 归档及其镜像 ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-10 | 首次确认，无变化 | 接受 Agent 建议 | 是 | ## 文档影响 - [ ] 不影响长期文档，原因： - [ ] 更新项目档案或本地开发与验证 - [ ] 更新架构与代码地图 - [ ] 更新业务规则与术语 - [ ] 更新常见修改或故障排查 - [x] 更新其他 Wiki 页面：新增 Existing-Project-Adoption-Guide，更新 Home ## 交付文档影响 - [x] 无交付文档影响，原因：[internal] 本任务只增加内部开发流程指南，不改变产品交付给客户或岗位人员的操作方法。 - [ ] 更新已有交付文档，受众与页面： - [ ] 新增交付文档，受众与页面： - [x] 需要目标岗位或客户代表验证：否；验证方式：由维护者检查指令可复制性和接入边界是否完整。 ## 验收标准 - [x] Wiki 存在独立的已有项目接入指南。 - [x] 指南明确区分已有项目接入与新项目初始化。 - [x] 指南覆盖只读盘点、已有内容保护、冲突处理和停止条件。 - [x] 指南给出增量接入顺序，不要求一次性替换或迁移。 - [x] 指南包含可以直接发送给 Agent 的分析指令和实施指令。 - [x] 指南明确禁止复制 DevHarness 历史归档和覆盖已有项目内容。 - [x] Home 可以进入已有项目接入指南。 - [x] 页面具有显式 Wiki 镜像映射和有效 revision。 - [x] Harness 严格检查和单元测试通过。 - [x] 实现提交与归档提交已推送。 - [x] 工单已在用户明确验收通过后关闭。 ## 验证方式 - `python dev_scripts/check_harness.py --strict` - `python -m unittest discover -s tests -v` - `python dev_scripts/sync_wiki_docs.py --check` - `git diff --check` - `git status --short --branch` - 人工检查两段 Agent 指令能否直接复制，并且不授权覆盖、删除或自动迁移已有项目内容。 ## 风险和回退 - 风险：Agent 把“接���模板”理解为覆盖已有规则；通过只读盘点、冲突清单、方案确认和增量合并控制。 - 风险：把旧项目任务归档或历史文档错误带入新事实来源；通过禁止复制归档、逐页确认迁移控制。 - 风险：同时维护 Wiki 和原本地长期文档形成双事实源；指南必须为每类文档明确迁移状态和最终事实来源。 - 回退：恢复 Home、映射和 Harness 检查到任务前版本；新增 Wiki 页的删除属于破坏性操作，回退时需另行确认。 ## 实施结果与证据 - 实施结果：与已确认方案一致；未创建迁移脚本，未修改实际业务项目。 - 线上 Wiki： - Existing-Project-Adoption-Guide，revision `cad12048c8aa6f54ec6d2595a79c814233e18285` - Home，revision `55d89b7aec659f55a61e7ceef881ef34a62d9379` - Task-12-已有项目接入DevHarness指南，revision `902c90884fd8902d8346365bf588183fdb6b00a3` - 本地镜像： - `docs/08-existing-project-adoption.md` - `docs/task/12-已有项目接入DevHarness指南.md` - 验证： - `python dev_scripts/check_harness.py --strict`：通过 - `python -m unittest discover -s tests -v`：23/23 通过 - `python dev_scripts/sync_wiki_docs.py --check`：25/25 一致 - `git diff --check`：通过 - 人工检查两段 Agent 指令：未授权覆盖、删除、重命名或自动迁移已有内容 - 提交： - `0271a3e` `docs: 新增已有项目接入指南 (#12)` - `eba8515` `docs: archive task #12` - 未验证部分：未在真实业务仓库执行完整接入，这是已确认非目标；首次实际接入时应另建项目专用工单验证。 - 验收结果：用户于 2026-08-10 明确验收通过。 - 验收状态提交：`105328e` `docs: record task #12 acceptance`。
ila closed this issue 2026-08-16 23:06:45 +08:00
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#12