我做了一个 RepoMind：让 AI 写架构前，先去看看真实开源项目

最近我一直在用 AI 编程工具写项目。Codex、Claude Code 这类工具确实很强，尤其是改代码、补测试、读上下文这些事情，体验已经非常接近一个认真干活的协作者了。

但我用得越多，越感觉有一个地方不太踏实：一旦问题上升到架构设计，AI 很容易给出一套"听起来很完整"的方案。

比如我问：

text 复制代码

帮我设计一个多 Agent 任务调度系统，要支持优先级、重试、持久化状态和多种执行后端。

它通常马上就能回答：控制面、任务队列、worker、状态机、retry policy、executor abstraction、插件化后端。看起来没毛病，甚至挺专业。

但是，我时常会想到一个问题：它到底是真的参考了成熟工程实践，还是只是把常见架构词拼得很顺？

很多时候我们不是缺一个"看起来合理"的架构图。我们真正想知道的是：

成熟项目里类似问题通常怎么拆模块？调度、执行、状态持久化之间的边界应该怎么放？哪些模式是真的在项目里跑过，哪些只是文档里很好看？如果我要借鉴某个项目，它的哪些前提条件不能忽略？

这几个问题，靠 AI 原地生成很难让我完全放心。因为架构判断这件事，本来就应该带一点"考古"味道：去看真实项目，看目录结构，看核心模块，看接口，看 README 里没有写但代码里藏着的取舍。

于是我做了一个东西，叫 RepoMind。

它的想法很朴素：

在让 AI 帮我设计架构之前，先让它去找一批相似的开源项目，读一读，再把可迁移的架构经验整理出来。

我不想让它帮我抄代码。我更想让它帮我回答：开源世界里，类似的问题通常是怎么被解决的？

RepoMind 是什么

RepoMind 是一个给 coding agent 用的架构调研 Skill。

现在它可以作为 Codex plugin、Claude Code plugin，也可以作为 standalone Agent Skill 使用。

它做的事情大概是这样：

你给它一个架构问题，它先判断这个问题是不是适合做架构调研。如果是，它会结合当前项目上下文，去 GitHub 上找相似的开源仓库，然后评估这些仓库和你的问题到底有多相关。最后，它会把有价值的部分整理成结构化的 code cards。

听起来有点绕，换成人话就是：

搜索"对我这个架构问题真的有参考价值的项目"，参考它，保存它，记下来。

比如你正在设计一个任务调度系统、插件系统、事件驱动的数据处理管线，或者一个 webhook ingestion 服务。这时直接问 AI "怎么设计"当然可以。但我更希望 AI 先去看几个真实项目，再回来跟我说：这些项目是怎么拆模块的，数据流怎么走，状态在哪里落，核心接口怎么定义，哪些设计值得借鉴，哪些设计不适合直接照搬。

RepoMind 就是为这个流程做的。

我为什么不满足于普通 GitHub 搜索

一开始我也想过：这是不是直接用 GitHub 搜索就够了？

后来发现不太够。

GitHub 搜索解决的是"找到项目"的问题，但它不解决"这个项目对我的架构问题有什么用"的问题。

举个例子，你搜 scheduler、task queue、workflow engine，可能会搜到一堆 star 很高的项目。但 star 高不代表它适合参考：

有些项目只是一个库，没有完整系统边界。有些项目名词很相关，但代码结构其实帮不上忙。有些项目规模太大，直接借鉴会把自己项目拖重。还有些项目 README 写得很漂亮，但真正的架构信息其实藏在源码里。

我想要的不是"热门仓库列表"，而是更细一点的判断：

这个项目为什么相关？它解决的是不是同一个层面的问题？它的模块边界能不能迁移？它有哪些限制？如果我照着学，会不会把不该引入的复杂度也带进来？

所以 RepoMind 的排序重点不是 popularity，而是 architectural relevance。

这是我写这个工具时最在意的一点。

大模型不是已经学过这些了吗？

这个问题我自己也想过。

大模型训练时确实见过大量代码，也肯定学到了很多架构模式。比如分层架构、插件系统、任务队列、状态机、事件驱动、worker pool，这些东西它大概率都懂。

所以 RepoMind 的价值不是"告诉模型一个它完全不知道的新概念"。

我更愿意把它理解成：让模型在当前问题上重新建立一条证据链。

一个模型可以知道"任务调度系统通常会有 scheduler、queue、worker、retry"。但我真正想知道的是：

哪些真实项目就是这么做的？它们具体把 scheduler 和 executor 怎么拆？状态是存在数据库、内存、事件日志，还是 workflow engine 里？这个判断能不能追到某个源码文件或文档？原项目的限制条件和我的项目是不是一样？

这些东西不是一句"模型训练时见过很多代码"就能解决的。

而且模型记住的东西通常是混在参数里的。它可能见过某个仓库，也可能没见过；可能见过旧版本，也可能把几个项目的模式揉在一起。你没法要求它说清楚：这个架构判断来自哪里、现在还准不准、能不能检查。

RepoMind 做的事情更像是让一个很有经验的工程师在开设计会之前先去做功课。

这个工程师脑子里当然已经有很多经验，但如果要做一个重要设计，他还是会去翻几个现成项目，看看别人到底怎么做，顺手记下哪些地方能学、哪些地方别学。

所以我觉得 RepoMind 不是给 AI 补常识，而是让 AI 少一点拍脑袋，多一点当下可检查的依据。

一个实际使用场景

假设我在 Codex 里问：

text 复制代码

Use RepoMind to research an architecture for a multi-agent task scheduler with priorities, retries, persistent state, and pluggable execution backends.

RepoMind 大概会走这样一个流程：

它会先判断这个问题是不是架构研究问题，然后看当前项目，提取技术栈、目录结构和关键词。接着它会查本地 .repomind 缓存，看以前有没有相关 code cards。如果本地证据不够，再用 GitHub CLI 搜索候选仓库。

搜索出来的仓库不会直接进入结果。RepoMind 会过滤掉 archived、太久没维护、README 没什么架构信息的项目，再根据领域匹配、模式相关性、技术重合度、架构深度这些维度打分。通过筛选的仓库会被进一步分析，最后整理成 code cards。

code card 大概长这样：

markdown 复制代码

<repo-card
  repo="example/scheduler"
  dimension="architecture"
  relevance="4.5">

### architecture

#### Overview
Uses a small control plane to persist task state and dispatch work to pluggable executors.

#### Transferable Patterns
- Keep scheduling decisions separate from execution backends.
- Model retries as explicit task-state transitions.

#### Source References
- `internal/scheduler/state.go`
- `internal/executor/registry.go`

#### Limitations
The worker model assumes a single-region deployment and should be adapted for distributed coordination.
</repo-card>

这个格式看起来有点"机器友好"，是故意的。

因为 RepoMind 的输出不只是给人看的，也要给后续 coding agent 继续用。比如我可以接着问：

text 复制代码

Using the RepoMind cards, propose a scheduler architecture for this project.
Separate the control plane from execution, define the task state machine, and explain which patterns should not be copied.

这时 AI 再给方案，就不是完全从空白处开始了。它至少有了一批可检查的参考项目、源码路径和限制条件。

我觉得这比"直接让 AI 发挥"靠谱很多。

它不是干什么的

我特意给 RepoMind 加了一个 scope gate。

如果你问：

text 复制代码

Python 里 priority queue 怎么写？

这不该走 RepoMind。直接让 AI 回答，或者看文档就行。

如果你问：

text 复制代码

帮我设计一个后端。

这也太泛了。RepoMind 应该让你先缩小问题，比如你到底想研究模块边界、事件流、权限模型、任务调度，还是插件系统。

它不是一个"更慢的搜索引擎"。它只应该在架构调研这类问题上启动（个人认为这也是做 Skill 时很容易忽略的一点：一个工具不光要知道自己能干什么，也要知道什么时候不该干）。

技术上怎么做的

RepoMind 的实现我尽量保持简单。

它的核心是一份可移植的 Skill：

text 复制代码

plugins/repomind/
├── .claude-plugin/plugin.json
├── .codex-plugin/plugin.json
└── skills/repomind/
    ├── SKILL.md
    ├── agents/openai.yaml
    ├── config/defaults.json
    ├── references/
    └── scripts/search.py

Claude Code 和 Codex 共享同一份 SKILL.md、同一个 Python helper、同一份配置和分析参考文档。不同平台的差异主要放在 plugin manifest 里。

这么做主要是为了避免维护两套逻辑，保持在 codex 和 claude code 场景的一致性。

Python helper 只用标准库，不引入额外 Python 包。GitHub 搜索走用户本机已经登录的 gh CLI。运行数据存在当前项目下面：

text 复制代码

<project>/.repomind/repomind.db

这个本地缓存很重要。架构调研不是一次性的，同一个项目后面可能会反复问相近问题。之前分析过的仓库可以复用，也可以避免每次都从 GitHub 重新搜一遍。

整体流程大概是：

text 复制代码

Architecture question
        |
        v
Intent and project-context analysis
        |
        v
Project-local card search
        |
        v
GitHub candidate discovery
        |
        v
Metadata and README relevance filtering
        |
        v
Repository analysis
        |
        v
Deduplication and SQLite persistence
        |
        v
Code-card assembly

里面我比较看重三件事。

第一，相关性评估不能只看 star。

一个 star 很高的项目，不一定和你当前的架构问题有关。RepoMind 会看 domain fit、pattern relevance、technology overlap、architectural depth 这些维度。

第二，输出里必须有 source references。

如果一个 card 说"这个项目把调度控制面和执行后端分开"，那它最好能指出相关源码路径或文档位置。否则这句话就很容易变成又一个 AI 结论。

第三，必须写 limitations。

很多开源项目的设计是有上下文的。公司规模、部署方式、语言生态、历史包袱、性能要求，都会影响架构选择。一个模式在原项目里成立，不代表在你的项目里也应该原样照搬。

所以 RepoMind 不只是提取"可以学什么"，也要提醒"哪里不要直接学"。

安装

如果你用 Codex：

bash 复制代码

codex plugin marketplace add gynnash/RepoMind --ref main
codex plugin add repomind@repomind

装完之后新开一个 Codex thread，然后直接问：

text 复制代码

Use RepoMind to find reusable architectures for a multi-agent task scheduler.

如果你用 Claude Code：

bash 复制代码

claude plugin marketplace add gynnash/RepoMind
claude plugin install repomind@repomind

然后这样调用：

text 复制代码

/repomind:repomind design an agent scheduling layer with priority queues

也可以作为 standalone skill 使用：

bash 复制代码

git clone https://github.com/gynnash/RepoMind.git
cd RepoMind

# Claude Code
cp -R plugins/repomind/skills/repomind ~/.claude/skills/

# Codex
cp -R plugins/repomind/skills/repomind ~/.codex/skills/

项目地址：github.com/gynnash/Rep...

我希望它带来的变化

我不是想证明 AI 不会设计架构。相反，我觉得 AI 很适合参与架构讨论。它整理信息快，能帮你列 trade-off，也能把粗糙想法变成比较完整的方案。

但我不希望它一上来就"开始发挥"。

至少在我自己的工作流里，我更想要的是：先找相似项目，看真实实现，提取可迁移模式，标出限制条件，然后再回到当前项目做设计。

这其实就是人类工程师做技术调研的方式。只是过去这个过程比较散：自己搜 GitHub、开几个 repo、翻 README、看目录、记笔记、再回头问 AI。

RepoMind 想把这部分变成 coding agent 可以稳定执行的流程。

它不保证每次都给出完美答案，但它至少把问题从"AI 觉得这样不错"往"这些真实项目里出现过这些设计，我们来判断哪些适合当前项目"推进了一步。

对我来说，这一步挺重要。

写在最后

如果你也经常用 Codex、Claude Code 或类似工具做系统设计，不妨试一下 RepoMind。

我更希望你拿真实问题来试，而不是只问一个很抽象的 demo。比如"我要做一个 webhook 投递系统，如何设计 retry 和 delivery log？"或者"我要做一个多租户任务调度器，状态机和 worker 边界怎么放？"再比如"我要做一个插件化数据处理管线，有哪些开源项目值得参考？"。这些问题比"帮我设计一个系统"更适合 RepoMind。

项目还很早期，欢迎提 issue、提 PR，也欢迎直接拿你的场景来挑战它：

github.com/gynnash/Rep...

我现在最想把它打磨成一个习惯：当我们让 AI 设计架构时，不是先问"你觉得怎么做"，而是先问：

开源世界里，类似的问题是怎么被解决的？