AI Agent盘活多仓库遗留项目：OpenCode+SpecKit实战

我们是如何借助 AI 的帮助，将一个 brownfield 多仓库项目改造成 agentic 开发工作流的——无需强制迁移到 monorepo。

借助 AI 辅助改造遗留软件项目（"brownfield"）如今已是一个可实现的目标——即便代码分布在多个仓库中。本文将带你了解我们如何将一个经典的多仓库 Git 项目演进为使用 OpenCode 和 GitHub SpecKit 的 AI 辅助开发工作流。过程中，我们将把这种方案与其他 coding AI 助手（如 GitHub Copilot、Amazon CodeWhisperer 和 Sourcegraph Cody）进行对比，并分享一些实践中的经验教训。

我们的目标很明确：

✅ 对多仓库应用（frontend、backend、共享组件）提供统一且一致的视图 ✅ 技术文档的自动生成与维护 "as-is"（现状文档） ✅ 可重复的操作流程，用于分析、feature 开发及本地执行

这一探索是我正在记录的更广泛研究的一部分。如果你对这种方案的架构基础感兴趣，推荐阅读我之前的一篇文章：👉 https://medium.com/p/627795029809

🧩 多仓库 Brownfield 的挑战

在典型的企业架构中，一个应用往往会跨越多个 Git 仓库——例如，一个前端 UI、一个或多个后端服务、共享类库以及基础设施代码。每个仓库都有独立的历史和独立的部署周期。这种分离是刻意为之的，对团队的自主性有益，但当 coding AI 助手需要理解全局时就会产生问题。

Brownfield 项目进一步放大了这一挑战：代码库庞大、成熟，由多年的决策和约定塑造而成。将 AI agent 引入这个环境，意味着它必须学习项目的模式且不能破坏任何东西。AI 需要对系统有全景视图才能真正发挥作用——否则它可能会提出忽略其他仓库依赖关系的修改，或者提出不符合现有约定的代码。

为什么不直接迁移到 monorepo？将所有代码迁移到单一仓库可以为 AI 提供完整的上下文，但对于成熟系统来说通常不切实际。迁移到 monorepo 会带来大量开销（CI/CD 变更、工具链、团队流程中断）和重大风险，且没有立竿见影的好处。除非从零开始或者仓库已经高度耦合，否则为了这个目的而进行 monorepo 迁移很少值得。相反，我们寻求的是一种非破坏性的方案：保持仓库分离，但让 AI 能够看到它们并像处理统一代码库一样工作。

🛠️ 逐步实现

Step 1: 在本地整合仓库

我们创建了一个本地 workspace 并将所有相关的 Git 仓库（frontend、backend、共享组件）克隆到子文件夹中。这为分析提供了统一的文件系统结构。📎 关于这个设置及其原理的深入说明，参见我的文章：https://medium.com/p/627795029809

mkdir workspace
cd workspace
git clone <repo-frontend-url> frontend
git clone <repo-backend-url> backend
git clone <repo-shared-url> shared

Step 2: 验证干净的基线

git -C frontend status
git -C backend status
git -C shared status

git -C frontend remote -v
git -C backend remote -v
git -C shared remote -v

Step 3: 创建一个专门存储规范的仓库

mkdir spec
cd spec
git init
git branch -M main
git remote add origin <repo-spec-url>

Step 4: 初始化 OpenCode 和 SpecKit

opencode init
speckit init

Step 5: 生成 AS-IS 文档

speckit scan --source ../workspace
speckit generate as-is
speckit export --format md --out ./docs/as-is

Step 6: 提交并验证

git add .
git commit -m "chore(spec): initial AS-IS baseline"
git push -u origin main

然后验证本地执行：

cd ../workspace/frontend
npm install
npm start
cd ../backend
npm install
npm run dev

🤖 在 Brownfield 系统上使用 AI Agents

跨仓库理解

当所有仓库加载到上下文中后，AI 能够对涉及 frontend、backend 和共享代码的修改进行推理。它能正确识别应该在哪里放置修改，并让我们确认要修改哪个仓库。

文档自动更新

实现修改后，我们会重新运行：

speckit scan --source ../workspace
speckit generate as-is
speckit export --format md --out ./docs/as-is

迭代式开发，Spec-First

我们遵循 SpecKit 的方法论：

1. 编写或更新规范
2. 用 /plan 生成计划
3. 用 /tasks 拆分任务
4. 用 OpenCode 实现

用规则引导 AI

我们不断完善我们的"宪法"（Costituzione）以：

• 防止代码重复
• 强制执行架构分层
• 禁止反模式（例如在 UI 组件中使用 try/catch）

📎 我在一篇专门的文章中更深入地探讨了这个话题：https://medium.com/p/da4204b3286a

📚 为什么将规范和文档放在独立的仓库中？

我们选择将所有规范和文档存储在专用的 Git 仓库（spec）中，而不是混入应用代码。这样做的好处包括：

• 独立的版本控制和历史记录
• 专用的 review 工作流
• 代码仓库中更少的干扰
• 更好的跨仓库文档治理

诸如将规范嵌入每个仓库或将其存储在未版本化的文件夹中这类替代方案，因碎片化、缺乏版本控制和难以审查而被放弃。

⚖️ 工具对比：Brownfield 项目的 AI 助手

我们评估的一个关键方面是不同 AI 辅助工具之间的对比。GitHub Copilot 在 IDE 内提供内联代码补全方面表现出色，但其上下文仅限于当前文件或打开的小段代码。Amazon CodeWhisperer 和 Sourcegraph Cody 提供了更广的仓库理解，但在协调多个独立仓库上的一致修改方面仍有困难。OpenCode 与 SpecKit 的组合因其能够在整合的 workspace 上操作、应用架构规则并保持文档同步——且无需迁移到 monorepo——而脱颖而出。

对于复杂的 brownfield 项目，工具的选择不仅仅是代码补全质量问题，更是变更治理问题：AI 能多大程度理解你的系统规则并在扩展修改中尊重它们。

将 brownfield 多仓库项目转变为 AI 辅助工作流不仅是可能的——而且是强大的。通过将我们的仓库联邦到一个 AI 上下文中，并采用 spec-first 的开发流程，我们获得了：

• 仓库之间的一致性
• 始终保持更新的文档
• 更快的迭代和更少的手动开销

我们无需重构项目或强制迁移到 monorepo。相反，我们以补充现有流程的方式引入了 AI 工具链。在每次迭代中，AI 都更好地对齐了我们的架构和约定。

这种方法适合所有人吗？如果你管理的是分布在多个仓库上的大型复杂代码库，我认为它值得认真考虑。有了正确的设置和治理，AI agents 可以成为强大的协作者——它们从不睡觉，从不遗忘，始终遵循你定义的规则。

https://medium.com/p/627795029809 — 架构基础

https://medium.com/p/da4204b3286a — 宪法与护栏

OpenCode: https://opencode.dev

SpecKit: https://speckit.dev

GitHub Copilot、Amazon CodeWhisperer、Sourcegraph Cody

Andrea Schiona — AI Breakfast / Software Architecture