在现存项目中使用 RunLogos

很多团队不是从零开始做一个新项目，而是已经有了正在运行的业务系统、历史代码、接口、数据库、线上部署和一批需要继续迭代的功能。这个时候接入 RunLogos，不是为了推翻已有工程，也不是为了把所有代码重新生成一遍，而是为了给现存项目补上一条清晰、可追溯、可验证的规格链。

RunLogos 基于 OpenLogos 方法论，把需求、设计、场景、API、数据库、测试、代码、验收和变更管理串成一条链。对已有项目来说，它最重要的价值是让团队重新说清楚三件事：

1. 当前系统为什么这样设计。
2. 这次改动到底要改什么、影响哪里。
3. 代码改完后，怎样证明它满足需求且没有破坏关键链路。

为什么要给现存项目提供这个能力

既有项目最大的问题通常不是“不会写代码”，而是上下文不稳定：

• 需求背景散落在会议纪要、聊天记录和个人记忆里。
• 代码已经存在，但很多设计意图没有留下文档。
• 新人接手时只能从代码反推业务规则。
• 每次改动都担心影响已有功能。
• API、数据库、测试和验收条件之间缺少稳定追溯关系。
• AI 编程工具能快速写代码，但如果缺少项目上下文，很容易改偏。

RunLogos 给现存项目提供的是一套“先补上下文，再做改动”的工作方式。它不会覆盖你的业务代码，而是在仓库根目录维护一个 logos/ 目录，用来保存需求、设计、时序图、OpenAPI、数据库设计、测试用例、验收报告和变更提案。

这样做以后，AI 或工程师开始修改代码时，面对的不再是零散 prompt，而是一条完整的规格链。

适合什么时候接入

你可以在这些场景中把 RunLogos 接入现存项目：

• 准备重构一个旧模块。
• 要新增一个边界复杂的功能。
• 线上功能经常因为小改动产生回归。
• 希望为核心接口补齐测试和验收报告。
• 希望让 AI 编程工具更稳定地理解项目上下文。
• 希望每次发布前都有可审计的变更记录。

第一次接入时，不建议直接覆盖整个系统。更好的方式是选择一个边界清楚的小功能做试点，例如后台列表筛选、一个 API 错误码修复、一个发布流程优化，或者一条支付 / 下载 / 登录链路的测试补齐。

接入方式：使用 adopt，而不是 init

现存项目接入 RunLogos 时，使用的是 OpenLogos 的 adopt 模式，而不是新项目初始化的 init 模式。

• openlogos init：适合从零创建一个新的 OpenLogos 项目，要求从初始需求、设计、技术方案开始推进。
• openlogos adopt：适合已有代码仓库，先把 OpenLogos 基础设施接进来，跳过 Initial 文档基线门禁，让项目直接进入可迭代状态。

在 RunLogos 里，你通常不需要手动敲 openlogos adopt。当 RunLogos 检测到当前目录是代码目录、但还没有接入 OpenLogos 时，会在侧边栏显示 接入 OpenLogos 存量项目 按钮。点击按钮、填写接入面板后，RunLogos 会在后台调用 openlogos adopt 完成接入。

第 1 步：用 RunLogos 打开现有项目

启动 RunLogos，打开你已经存在的代码仓库。这个目录通常已经包含 package.json、src/、app/、backend/、pom.xml、go.mod、Cargo.toml、pyproject.toml 或其它业务代码入口。

如果这个项目还没有 logos/logos.config.json，RunLogos 会显示“当前项目未初始化 OpenLogos”，并提供两个入口：

• 初始化项目：用于新项目。
• 接入 OpenLogos 存量项目：用于已有项目。

这里选择 接入 OpenLogos 存量项目。

完成效果：

• RunLogos 确认这是一个已有代码目录。
• 你不需要离开 RunLogos 到终端手动初始化。
• 接下来会进入存量项目接入面板。

第 2 步：填写接入面板

点击 接入 OpenLogos 存量项目 后，RunLogos 会弹出接入面板。面板的作用不是让你补完整需求，而是确认这次接入所需的基础配置。

通常需要确认这些内容：

完成效果：

• RunLogos 拿到接入所需的最小信息。
• 后台可以生成等价的 openlogos adopt 命令。
• 项目还没有被改动，只有确认后才会执行接入。

第 3 步：确认接入

确认后，RunLogos 会在当前项目根目录中调用 openlogos adopt。如果用终端表达，它等价于类似下面的命令：

cd your-existing-project
openlogos adopt "your-project-name" --locale zh --ai-tool codex

实际命令中的项目名、语言和 AI 工具来自你在面板里填写的内容。正常使用时，你只需要在 RunLogos 中点击确认；命令执行、目录生成和项目刷新都由 RunLogos 完成。

完成效果：

• 现有项目被接入 OpenLogos。
• RunLogos 会刷新工作区，展示新生成的 logos/ 资源。
• 业务源码不会被重写，接入动作只增加 OpenLogos 工作区和 AI 协作文件。

adopt 命令内部做了什么

openlogos adopt 是专门为现存项目准备的接入命令。RunLogos 调用它时，内部会按下面的顺序执行：

1. 以当前打开的项目目录作为根目录。
2. 检查 logos/logos.config.json 是否已经存在；如果存在，说明项目已经接入过 OpenLogos，命令会停止，避免重复初始化。
3. 根据面板参数确定项目名称、文档语言和 AI 工具；如果没有显式传项目名，会从当前目录或项目清单文件中推断。
4. 创建 logos/ 标准目录结构，包括需求、设计、技术方案、API、数据库、测试、验收、变更提案和归档目录。
5. 写入 logos/logos.config.json，保存项目名称、语言、AI 工具和验收前置运行配置。
6. 写入 logos/logos-project.yaml，并把核心模块标记为 lifecycle: launched、bootstrap: adopted。
7. 为存量项目写入默认跳过项，例如 skip_phases: [api, database, scenario]，表示初次接入时不强制要求立刻补齐完整 Initial 文档基线。
8. 写入 AGENTS.md 和 CLAUDE.md，让 AI 工具知道这个项目遵循 OpenLogos 方法论、文档语言和变更规则。
9. 部署对应 AI 工具的 Skills 资产，并把 OpenLogos 方法论规格同步到 logos/spec/。
10. 输出建议的下一步，例如先创建 add-baseline-docs 变更提案，逐步补齐项目背景和规格基线。

所以，adopt 的重点不是扫描和改写你的业务源码，而是把 OpenLogos 的协作基础设施接入现有仓库。接入完成后，项目会直接进入存量项目模式，不需要先完整跑完新项目的 Phase 1 到 Phase 3。

接入成功后，OpenLogos 面板会显示“存量项目接入”状态，并给出建议的下一步命令。接入结果里的 openlogos change add-baseline-docs 表示接入完成后可以先补项目基线文档，而不是直接进入代码修改。

第 4 步：查看接入后的规格链工作区

接入完成后，RunLogos 会读取：

logos/logos-project.yaml

然后在工作区中展示 OpenLogos 资源。初次接入时，很多资源目录可能还是空的，这是正常的。adopt 模式的含义就是先把基础设施接进来，再用后续变更逐步补齐项目基线。

你可以重点检查：

• logos/logos.config.json 是否存在。
• logos/logos-project.yaml 中是否包含 bootstrap: adopted。
• logos/resources/ 是否已经创建。
• logos/changes/ 是否已经创建。
• AGENTS.md / CLAUDE.md 是否已经生成。

完成效果：

• RunLogos 已经能识别该项目。
• 项目进入存量项目接入模式。
• 后续可以在 RunLogos 中写需求、设计、测试、验收和变更提案。

其中最关键的是 logos/logos-project.yaml。它会记录项目已经进入存量项目接入模式：

第 5 步：用提案补齐项目背景

对现存项目来说，不要一开始就让 AI 改代码，也不要直接在 logos/resources/ 里零散补文档。接入完成后，应该先创建一个基线补齐提案：

openlogos change add-baseline-docs

这个提案的目标是补齐现有项目的背景和规格基线，不改变业务代码、接口、数据库或运行环境。你可以把它理解为“把已有系统说清楚”的第一次 OpenLogos 迭代。

在 add-baseline-docs 提案中，优先补这些背景信息：

• 这个项目解决什么业务问题？
• 当前用户是谁？
• 核心功能有哪些？
• 当前最痛的维护问题是什么？
• 这次准备改哪个模块？
• 会影响哪些页面、接口、数据库表或任务流程？

可以在 RunLogos 的 Markdown 编辑器中填写 proposal.md 和 tasks.md，再通过提案 delta 补齐需求文档、产品设计、部署说明和测试基线。这样后续每一份背景文档都有提案来源，归档后也能追溯“这些基线信息是什么时候补齐的、为什么这样描述”。

完成效果：

• 团队对“为什么做”形成统一理解。
• AI 工具有稳定上下文，不再只根据一两句话猜测。
• 后续设计、测试和代码实现都有明确来源。
• add-baseline-docs 归档后，项目拥有第一版可追溯的存量项目背景基线。

第 6 步：选择一个小功能作为试点

第一次接入 RunLogos，建议选择一个低风险、边界清楚的小功能。不要直接把整个系统都纳入改造。

适合作为试点的任务包括：

• 修复一个后台管理页面问题。
• 新增一个列表筛选条件。
• 调整一个 API 的错误返回。
• 为已有业务流程补一组测试。
• 优化一条发布、支付、登录或下载链路。

完成效果：

• 团队可以低风险熟悉 RunLogos 的工作方式。
• 可以完整跑通需求、设计、测试、实现、验收流程。
• 如果试点效果好，再逐步扩大到更多模块。

第 7 步：为这次改动创建变更提案

如果项目已经进入迭代阶段，每次改动都应该先创建变更提案：

openlogos change your-change-name

变更提案会记录：

• 为什么要改。
• 改动范围是什么。
• 影响哪些需求、页面、API、数据库和测试。
• 是否需要部署。
• 是否需要 smoke 验证。

完成效果：

• 每次改动都有清晰边界。
• AI 和工程师都能知道哪些文件可以改、哪些文件不应该碰。
• 后续归档时可以追溯完整决策过程。

第 8 步：按规格链推进，而不是直接改代码

RunLogos 推荐的顺序是：

Why → What → How

也就是先说明需求背景，再定义功能行为，然后设计场景、API、数据库和测试，最后才实现代码。

对现存项目来说，这一步不是要求你重写系统，而是把“本次改动”放进规格链：

1. 更新需求或变更提案，说明为什么要改。
2. 更新功能规格，说明页面或接口行为。
3. 更新场景或时序图，说明关键流程和异常分支。
4. 更新 API / 数据库设计，如果本次改动涉及接口或表结构。
5. 更新测试用例，明确怎么验证。
6. 再进入代码实现。

完成效果：

• 代码实现有明确规格依据。
• 测试用例能追溯到需求和验收条件。
• Review 不再只看代码，而是检查代码是否符合规格链。

第 9 步：实现代码并运行验收

代码完成后，运行：

openlogos verify

RunLogos / OpenLogos 会读取测试用例和测试结果，生成验收报告。

完成效果：

• 可以看到定义了多少测试、执行了多少、通过多少。
• 可以确认验收条件是否都被测试覆盖。
• 团队获得一份可追溯的交付证明。

第 10 步：部署后运行 smoke 并归档

如果这次改动需要部署，部署完成后运行：

openlogos smoke

smoke 用来确认生产环境的基础入口是否可达，例如公开页面、下载页、登录保护入口和关键 API 的基础响应。

当 verify 和 smoke 都通过后，归档本次变更：

openlogos archive your-change-name

完成效果：

• 当前变更从 active 状态进入 archive。
• 需求、设计、测试、代码实现、验收、部署和 smoke 结果都被保留下来。
• 后续如果要追溯“这个功能为什么这么改”，可以直接查看归档目录。

推荐的第一次接入路径

第一次在现存项目里使用 RunLogos，可以按这个顺序执行：

1. 用 RunLogos 打开已有代码仓库
2. 点击“接入 OpenLogos 存量项目”
3. 在面板中确认项目名称、文档语言和 AI 工具
4. 由 RunLogos 调用 openlogos adopt 完成接入
5. 检查 logos/、AGENTS.md、CLAUDE.md 是否生成
6. 创建 openlogos change add-baseline-docs 提案
7. 在 add-baseline-docs 提案内补齐项目背景和当前痛点
8. 验收并归档 add-baseline-docs 基线提案
9. 选择一个小功能作为试点
10. 为试点功能创建新的变更提案
11. 按规格链补齐需求、设计、测试
12. 实现代码并运行 openlogos verify
13. 部署后运行 openlogos smoke
14. 归档变更

总结

在现存项目中使用 RunLogos，不是替代你的代码仓库，也不是强制重写已有系统。它的作用是把原本分散的需求、设计、接口、数据库、测试和验收结果组织成一条可追溯的规格链。

最好的接入方式是从一个小改动开始，先跑通完整流程，再逐步扩大到更多模块。这样既不会打断现有研发节奏，又能让团队逐步获得更清晰的上下文、更稳定的 AI 协作和更可靠的交付验证。