dev_harness/docs/08-existing-project-adoption.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Existing-Project-Adoption-Guide wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Existing-Project-Adoption-Guide.- wiki_revision: 3575ecb437d5a7eac4073b0ad3e162da8b5c1100 synchronized_at: 2026-08-24T08:55:55Z

已有项目接入 DevHarness 指南

本页用途

本页用于把 DevHarness 的文档模板和开发流程增量接入已经存在的项目。已有项目通常已经有代码、规则、文档、工单、Wiki、Git 历史和未完成工作，因此接入目标是补齐必要能力，不是把项目重置成 DevHarness 模板副本。

接入必须先只读盘点、确认差异方案，再建立单元任务工单实施。未经确认不得覆盖、删除、重命名或批量迁移已有内容。

与新项目初始化的区别

场景	新项目初始化	已有项目接入
项目事实	从代码骨架和负责人确认开始建立	优先保留并核对已有事实
规则文件	可以从模板建立第一版	必须合并已有规则，不能直接覆盖
文档	创建核心主题页	逐页判断保留、迁移、合并或停止维护
工单和 Wiki	新建并开始使用	先检查已有工单、Wiki 和状态体系
Git 历史	允许一次引导提交	保留全部历史，不使用引导提交例外
任务证据	Gitea 工单；任务快照仅显式按需创建	保留已有工单；不复制 DevHarness 或其他项目的历史归档
接入方式	一次建立最小骨架	分阶段增量接入并逐步验收

从模板创建全新仓库时使用新项目文档初始化；项目已有业务提交、用户或维护历史时使用本页。

接入前只读盘点

Agent 在提出方案前只读检查：

• 根目录和相关子目录中的 AGENTS.md、CLAUDE.md 及其他 Agent 规则；
• README、现有 docs/、Wiki 页面、工单模板和任务状态；
• Git 默认分支、远端、提交历史、未提交修改和忽略规则；
• 语言、框架、依赖、启动入口、主要模块和目录职责；
• 格式检查、静态检查、单元测试和必要集成测试命令；
• 配置、日志、接口、数据模型、权限、安全、部署和发布边界；
• 已完成、进行中、阻塞和待验收任务；
• 现有长期文档的事实来源、负责人和更新方式。

输出时区分：

1. 从代码、配置或现有系统确认的事实；
2. 项目负责人确认的业务规则；
3. 尚待确认的假设；
4. DevHarness 与现有规则的冲突；
5. 与接入无关、必须保留的工作区改动。

只读盘点不授权修改文件、创建 Wiki、迁移文档或改变工单状态。

已有内容保护原则

• 保留 Git 历史、分支、标签和当前任务状态。
• 保留已有 AGENTS.md、README、规则和项目专用红线；DevHarness 规则按冲突结果增量合并。
• 保留与接入无关的未提交改动，不重置、不覆盖、不混入提交。
• 不复制 DevHarness 的 docs/task/、任务归档映射和历史工单。
• 不因采用 Wiki-first 就立即删除原本地文档；先逐页确认事实来源和迁移状态。
• 不把模板占位值当成项目事实，不臆造技术栈、命令、业务规则、凭据或环境。
• 不把密码、令牌、Cookie、私钥、个人数据或生产数据带入工单、Wiki和镜像。
• 页面删除、重命名、历史清理和事实来源切换必须单独确认。

多应用单仓库判断

一个 Git 仓库可以包含多个技术栈不同、能够独立构建和发布的应用或终端。技术栈不同本身不是拆仓理由；先把每个子项目和交付单元记录到 Project-Profile，再根据实际协作边界判断。

适合继续单仓库

• 多个应用共同完成一条产品或业务链路；
• 由同一团队维护，仓库权限基本一致；
• 接口变更需要在一个工单中同步修改或验证多端；
• 共享契约和业务规则由同一项目维护并指定唯一事实来源；
• 仓库体积、测试时间和工具性能尚未明显影响开发；
• 初级维护者和 Agent 能通过目录、子目录 AGENTS.md 和文档入口清楚定位。

可以考虑拆仓

• 长期由不同团队独立负责并需要不同访问权限；
• 发布周期、版本策略和验收负责人已经完全独立；
• 某个应用被多个产品复用或需要单独对外提供；
• 仓库体积、检出、索引或测试耗时已经持续影响效率；
• 共享接口已经版本化、兼容周期明确，并有跨仓契约测试；
• 跨应用任务很少，拆仓后的协调成本低于继续共仓。

不满足这些条件时，优先保持单仓库并完善边界，不为了目录整洁或技术栈不同而拆仓。

保持单仓库时的最小规则

• 根目录 AGENTS.md 只放共同流程、安全和跨项目规则，技术栈专用规则写入子目录 AGENTS.md。
• 每个交付单元拥有自己的构建、测试、版本和发布方式，不强制统一版本。
• 单元任务必须声明只影响哪个子项目、是否跨子项目、是否修改共享接口，以及各端需要执行的验证。
• 共享接口或契约只能指定一个事实来源；其他文档引用它，不复制一个“差不多”的版本。
• 跨子项目契约变更在同一工单中更新事实来源，并验证所有受影响端。
• 拆仓属于事实来源、任务和发布边界变化，必须另建工单、确认迁移和回退方案后实施。

增量接入顺序

1. 确认差异方案

根据盘点结果列出目标、非目标、复用项、改写项、冲突项、影响范围、风险、回退、验证和文档影响。方案得到用户明确确认前不实施。

2. 建立单元任务工单

使用目标项目的 Gitea 建立接入工单，记录原始需求、范围、依赖、方案和验收标准。目标项目没有可用 Gitea 时，先提交完整工单草稿并说明阻塞，不默认绕过。

3. 接入共同规则和工单流程

优先增量合并根规则、Claude 入口和单元任务模板。项目专用安全、业务和目录规则继续有效；冲突时由负责人决定最终表述。

4. 确定长期文档事实来源

为每份已有文档标记：

• 保留在 Git：与特定代码版本强绑定；
• 迁移到 Wiki：长期架构、业务规则、开发规范或操作说明；
• 合并：内容重复但各有有效事实；
• 暂不迁移：事实未确认或当前不影响接入；
• 停止维护：必须由负责人确认，不能由 Agent 自行删除。

切换到 Wiki-first 的页面必须先在线上创建或更新、读取确认，再建立 wiki-docs.json 映射并导出本地镜像。避免 Wiki 和手写本地文档长期形成双事实源。

5. 接入 Harness 工具

仅复制当前项目实际需要的 dev_scripts/ 工具、配置和测试。业务脚本使用独立目录。根据目标项目调整核心页面、路径、命令和结构检查，不照搬 DevHarness 项目值。

6. 分阶段验证

先验证工单和规则入口，再验证 Wiki 映射，最后启用严格检查。每阶段采用“执行 → 首个真实错误 → 最小修复 → 继续”的闭环，不用一次接入全部旧文档。

7. 提交和验收

提交只包含当前接入工单相关文件。在工单评论集中记录测试、未验证部分、提交哈希，以及真实变化的 Wiki revision 或“无长期文档影响”；保持工单“待验收”，等待用户明确验收后再关闭。默认不创建任务归档。

后续升级

已接入的项目必须以 Project-Profile 中记录的 DevHarness 来源和当前基线为起点升级，不得重新复制整个模板，也不得用“最新版本”代替可复现的目标提交。

升级步骤

1. 读取目标项目的 Project-Profile，确认 DevHarness 来源仓库、当前基线完整提交、最后升级日期和项目适配说明；字段缺失时先补齐可验证事实，无法确认则停止。
2. 选择一个明确、已审阅的 DevHarness 目标提交，记录旧基线和新基线。先比较两个上游提交之间的变化，再判断这些变化如何作用于目标项目。
3. 只读比较与 Harness 有关的 AGENTS.md、CLAUDE.md、工单模板、dev_scripts/、Harness 测试和核心 Wiki 结构，把差异分为“直接采用、按项目改写、冲突待确认、不采用”。不得把 DevHarness 的项目事实、工单或任务归档带入目标项目。
4. 在目标项目建立单元任务工单，写明升级范围、差异分类、项目专用规则、风险、回退、验证和文档影响。会改变产品行为的内容必须拆成独立任务。
5. 按工单最小合并，保留目标项目更具体的业务、安全、权限和目录规则，以及 Git 历史和无关工作区修改。无法判断哪一方规则有效时停止并等待负责人确认。
6. 长期文档先更新目标项目 Wiki，读取确认后再同步目标项目的核心 docs/ 镜像；不得用 DevHarness 的本地镜像覆盖目标项目文档。
7. 执行目标项目规定的必要检查和受影响测试，提交并回写证据。工单保持“待验收”。
8. 用户验收通过后，确认目标项目 Project-Profile 已记录新 DevHarness 基线完整提交和升级日期，再关闭工单。升级失败或回退时保留旧基线。

升级停止条件

除本页已有的冲突停止条件外，来源仓库与记录不一致、旧基线不存在、目标提交未明确、差异跨越过大而无法可靠分类，或升级需要覆盖项目专用安全规则时，都必须停止并请求确认。可以把升级拆成多个单元任务，但每个任务都要声明最终采用的同一目标基线。

可复制升级指令

请把当前项目从 Project-Profile 记录的 DevHarness 基线升级到
<DevHarness 目标完整提交哈希>。

先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目
适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及
风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git
历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在
当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。
工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。

路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。

冲突处理和停止条件

出现以下情况时停止实施并请求负责人确认：

• 现有规则与 DevHarness 的安全、权限、事实来源或验收规则冲突；
• 无法判断某份文档应该保留、迁移、合并还是停止维护；
• 需要删除、重命名 Wiki 页面、覆盖已有文件或清理历史归档；
• 需要改变接口、数据库、权限、部署、发布或其他产品行为；
• 工作区存在可能与接入文件重叠的未知修改；
• Gitea、Wiki、凭据或远端权限不可用；
• 真实命令、环境或业务规则无法从证据或负责人确认。

相邻问题最多提示或另建工单，不混入接入任务。

可复制 Agent 指令

只分析

请把 <DevHarness 路径> 的文档模板和开发流程接入当前已有项目。

先只分析，不修改文件、工单或 Wiki：

1. 阅读 DevHarness 的 AGENTS.md、README.md、项目档案、开发工作流、
   新项目文档初始化和已有项目接入指南。
2. 阅读当前项目已有的 Agent 规则、README、docs、Gitea 工单模板、
   Wiki 配置、代码入口、测试命令和目录结构。
3. 列出已有规则、文档、任务状态、Git 历史和未提交改动。
4. 对比后列出可复用项、必须改写项、冲突项、旧文档处理方式、
   最小接入范围、风险、回退、验证和文档影响。
5. 不复制 DevHarness 任务归档，不覆盖、删除或重命名已有内容，
   不把模板占位值当成项目事实。
6. 输出方案后停止，等待我确认。

方案确认后实施

按照已确认方案建工单并做。

严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、
任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出
本地 docs 镜像。执行必要测试，提交实现并把最终证据回写工单，然后
保持“待验收”；默认不创建任务归档，未经我明确验收不关闭工单。

路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。

最小验收清单

• 已盘点规则、文档、任务、Git 历史和未提交改动。
• 已识别所有子项目和独立交付单元。
• 跨子项目共享契约已经指定唯一事实来源。
• 已明确复用、改写、冲突和暂不处理内容。
• 已保留项目专用规则、历史和无关改动。
• 未复制 DevHarness 历史归档或模板项目事实。
• 已为每类长期文档明确事实来源和迁移状态。
• Wiki-first 页面已经读取确认并具有显式镜像映射。
• Harness 检查已按目标项目调整并通过。
• 必要测试、未验证部分、提交和归档证据已记录。
• 工单处于待验收，未提前关闭。

回退原则

接入应拆成可回退的小提交。普通回退恢复本次新增或修改的规则、配置、检查和镜像映射，不触碰原有业务提交。Wiki 页面删除、重命名、历史清理或事实来源反向切换不是普通回退，必须另行建单并等待确认。