generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Existing-Project-Adoption-Guide wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Existing-Project-Adoption-Guide.- wiki_revision: 2ef3d7cd26874f652e9bfab2a5c2f6c8273ab7ac synchronized_at: 2026-08-16T11:50:18Z # 已有项目接入 DevHarness 指南 ## 本页用途 本页用于把 DevHarness 的文档模板和开发流程增量接入已经存在的项目。已有项目通常已经有代码、规则、文档、工单、Wiki、Git 历史和未完成工作，因此接入目标是补齐必要能力，不是把项目重置成 DevHarness 模板副本。 接入必须先只读盘点、确认差异方案，再建立单元任务工单实施。未经确认不得覆盖、删除、重命名或批量迁移已有内容。 ## 与新项目初始化的区别 | 场景 | 新项目初始化 | 已有项目接入 | |---|---|---| | 项目事实 | 从代码骨架和负责人确认开始建立 | 优先保留并核对已有事实 | | 规则文件 | 可以从模板建立第一版 | 必须合并已有规则，不能直接覆盖 | | 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 | | 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 | | Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 | | 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 | | 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 | 从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。 ## 接入前只读盘点 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 基线完整提交和升级日期，再关闭工单。升级失败或回退时保留旧基线。 ### 升级停止条件 除本页已有的冲突停止条件外，来源仓库与记录不一致、旧基线不存在、目标提交未明确、差异跨越过大而无法可靠分类，或升级需要覆盖项目专用安全规则时，都必须停止并请求确认。可以把升级拆成多个单元任务，但每个任务都要声明最终采用的同一目标基线。 ### 可复制升级指令 ```text 请把当前项目从 Project-Profile 记录的 DevHarness 基线升级到 。 先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目 适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及 风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git 历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在 当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。 工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。 ``` 路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。 ## 冲突处理和停止条件 出现以下情况时停止实施并请求负责人确认： - 现有规则与 DevHarness 的安全、权限、事实来源或验收规则冲突； - 无法判断某份文档应该保留、迁移、合并还是停止维护； - 需要删除、重命名 Wiki 页面、覆盖已有文件或清理历史归档； - 需要改变接口、数据库、权限、部署、发布或其他产品行为； - 工作区存在可能与接入文件重叠的未知修改； - Gitea、Wiki、凭据或远端权限不可用； - 真实命令、环境或业务规则无法从证据或负责人确认。 相邻问题最多提示或另建工单，不混入接入任务。 ## 可复制 Agent 指令 ### 只分析 ```text 请把 的文档模板和开发流程接入当前已有项目。 先只分析，不修改文件、工单或 Wiki： 1. 阅读 DevHarness 的 AGENTS.md、README.md、项目档案、开发工作流、 新项目文档初始化和已有项目接入指南。 2. 阅读当前项目已有的 Agent 规则、README、docs、Gitea 工单模板、 Wiki 配置、代码入口、测试命令和目录结构。 3. 列出已有规则、文档、任务状态、Git 历史和未提交改动。 4. 对比后列出可复用项、必须改写项、冲突项、旧文档处理方式、 最小接入范围、风险、回退、验证和文档影响。 5. 不复制 DevHarness 任务归档，不覆盖、删除或重命名已有内容， 不把模板占位值当成项目事实。 6. 输出方案后停止，等待我确认。 ``` ### 方案确认后实施 ```text 按照已确认方案建工单并做。 严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、 任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出 本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持 为“待验收”；未经我明确验收，不关闭工单。 ``` 路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。 ## 最小验收清单 - [ ] 已盘点规则、文档、任务、Git 历史和未提交改动。 - [ ] 已识别所有子项目和独立交付单元。 - [ ] 跨子项目共享契约已经指定唯一事实来源。 - [ ] 已明确复用、改写、冲突和暂不处理内容。 - [ ] 已保留项目专用规则、历史和无关改动。 - [ ] 未复制 DevHarness 历史归档或模板项目事实。 - [ ] 已为每类长期文档明确事实来源和迁移状态。 - [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。 - [ ] Harness 检查已按目标项目调整并通过。 - [ ] 必要测试、未验证部分、提交和归档证据已记录。 - [ ] 工单处于待验收，未提前关闭。 ## 回退原则 接入应拆成可回退的小提交。普通回退恢复本次新增或修改的规则、配置、检查和镜像映射，不触碰原有业务提交。Wiki 页面删除、重命名、历史清理或事实来源反向切换不是普通回退，必须另行建单并等待确认。