Retaintive

    AI 工具栈 — 我们用什么、为什么

    目标:让 AI 在我们多个 repo 里找对信息、写代码前知道「这个东西已经有了」、不重复造轮子。 这页是结论(用哪个、为什么)。每个工具的详细好坏见 工具调研清单。

    一句话结论

    AI 出错不只是「找不到信息」一种,所以没有一个工具能全解决。「找不到/找错信息」这类(大概占 AI 失误的三分之一)按下面四层处理;另外三分之二(理解错你的意思、把代码语法写坏)工具买不到,靠规则和习惯。

    实测后的关键发现(2026-05-29,2026-06 迁移后更新):四层里真正要装工具的只有 ② 导航。现在由 Rspress 内置 llms: true 生成 llms.txt / llms-full.txt。③ 打包平时用不上,④ 搜索(原以为是主角)实测下来不装工具反而更好——AI 自带的 grep/Read 比语义搜索准,「防重复」靠 CLAUDE.md 写清 helper 位置即可。

    四类工具,各管一件事

    把 AI 找信息想成一条流水线,四个环节各管一件事:

    这一层管什么大白话我们用什么现在状态
    ① 规则告诉 AI「该怎么干活」就用 CLAUDE.md(主要用 CC,先不碰 AGENTS.md)已定
    ② 导航告诉 AI「东西在哪个文件」Rspress llms: true✅ 已采用
    ③ 打包把一个小项目整个塞给 AI 看全貌Repomix需要时才用
    ④ 搜索让 AI 按需在所有代码里搜都不用(语义搜索实测不对症;AI 自带 grep 已够)实测后划掉

    我们的核心需求(写代码防重复)主角是第 ④ 层「搜索」,不是文档工具。但实测后发现:这个需求不需要单独的语义搜索工具——详见 §④。

    每一层为什么这么选

    ① 规则 —— 就用 CLAUDE.md,先不碰 AGENTS.md

    结论:你主要用 Claude Code,就专心维护 CLAUDE.md,不用搞 AGENTS.md。

    调研依据(2026 多个来源一致):

    • Claude Code 只读 CLAUDE.md,不读 AGENTS.md。如果只用 CC,加 AGENTS.md = 凭空多维护一个文件。
    • 两个文件都维护会重复 + 漂移(你的担心对)。
    • 真要多工具共享时,不是复制两份:把内容放 AGENTS.md,CLAUDE.md 用一行 @AGENTS.md 导入它 + 加几条 Claude 专属。只维护一份。
    • 所以现在:只用 CLAUDE.md。等哪天真的重度用 Codex/Gemini 干同样的活,再按上面的 import 方式加,不复制。

    注意一个反常识的点:规则文件不是越长越好。研究发现塞太多规则反而让 AI 表现更差。所以要精简。

    ② 导航 —— Rspress llms（已采用）

    这解决你最明确的痛点:llms.txt(告诉 AI 东西在哪的导航文件)手写会过期。Rspress 在 rspress.config.ts 里开启 llms: true 后,每次 build 网站时自动重新生成这份导航,不用手动维护。

    我们自己实测(2026-05-29 VitePress 插件,2026-06 Rspress 内置 llms)+ websearch 核实,原本担心的坑都有解:

    • ✅ 中文没问题 —— 生成的中文 llms.txt 标题/分类/层级正常,中英混排能用。
    • ⚠️ 目录默认只有标题,没描述 —— 但有解:给文档 frontmatter 加 description: 字段,生成的目录就会带描述(变成 - [标题](/x.md): 描述)。我们手写版最值钱的就是 keyword 描述,这样能保住。
    • ⚠️ 生成在 .rspress/dist(部署目录),不在 docs/ 源码 —— AI 读本地 repo 读的是源码那份,读不到 dist。我们的方案:不复制回源码(避免两份 drift),而是在 CLAUDE.md 让 AI 直接读 .rspress/dist/llms.txt,没有就先 npm run docs:build 生成。单一来源。

    关键:sidebar 和 llms 都由 rspress.config.ts 自动化 —— sidebar 自动扫 docs/ 顶级目录生成,代码动态生成不硬编码;Rspress build 自动生成 llms.txt。两个都自动化,加文档自动进导航 + llms.txt。llms 目录想带描述就给文档 frontmatter 加 description:(渐进)。

    ③ 打包 —— Repomix（实测后:划掉,不是你的菜）

    这是个「打包工」:把一个 repo 的所有代码塞进一个文件,让 AI 一口气读懂整个项目。它打包时会压缩(只留代码骨架删细节),还顺手检查有没有把密码打包进去。

    实测后结论:对你日常用处不大,划掉。 三个原因:

    • 会过期:它是一次性命令,代码改了不自动更新。挂 commit hook 能解决过期,但又带来「每次开工吃几万 token 全量 context」的浪费(研究证据:塞太多前置 context 反而让 AI 表现更差)。
    • 你主要用 CC,CC 自己能读本地文件 —— 不需要「打包成一个文件再喂」。Repomix 主要是给网页版 AI(没法直接读你文件的)用的。
    • 不解决跨 repo:一次只打包一个 repo + 会过期,fundamentally 不碰你「跨 9 repo 防重复」的核心需求。

    它什么时候还值得用一次(一次性场景):用网页版 ChatGPT/Gemini 看某个小 repo、让 AI 做一次性整体架构 review、打包发给同事或别的 AI。平时用不上。

    实测数字(2026-05-29):代码 repo(lead-tracking)压缩省 41%、37K token 能喂进 AI;docs repo 打包爆到 1734 万 token(一半是 SVG 图)喂不进。详见 调研清单。

    ④ 搜索 —— 实测后:两个语义搜索工具都不用

    结论:cocoindex-code 和 claude-context 都不推荐引入。不是工具差,是需求和工具范式不匹配。「写代码防重复」这个需求,AI 自带的 grep/Read 已经够用,加一个语义搜索 MCP 是叠床架屋。(实测记录:callytics-infrastructure/.claude/specs/2026-05-29-code-search-mcp-hands-on-test.md)

    实测怎么测的(2026-05-29,3 个真实 repo)

    先用 grep 拿到每个问题的标准答案,再让 cocoindex-code 搜同样的问题,看谁更对。指向 callytics-infrastructure / callytics-common / lead-tracking 三个 repo(372 文件)。

    问题grep 结果cocoindex 结果谁赢
    找 resolvePhoneIdentity 定义(已知函数名)一行精确命中top 8 全是 changelog + 调用方,定义没排进前 8grep
    谁在用 resolvePhoneIdentity(改它影响谁)精确:13 / 9 / 0 个文件漏掉 8 个调用方,分不清定义/调用方,无法表达「0 个」grep
    lead-tracking 写入逻辑在哪(模糊概念)关键词组合唯一命中命中了但排第 2,夹 CDK 定义 + docs 噪音grep 略胜
    「normalize phone 能力存在吗」(不知道叫什么)要会拼正则才抓全自动找到 canonical + 2 个重复实现,跨 2 repococoindex 略胜

    总比分 grep 赢 3、cocoindex 赢 1,坐实了前面那条研究提醒(语义搜索对「找对文件」不一定比 grep 强)。

    为什么不对症 —— 需求拆成两半,两半都不是语义搜索的强项

    这是个「内容本来就不对等」的结构,所以分两条说,不强行对称:

    1. 「helper 已存在吗」这一半 —— AI 自己 grep 就够。 你的 AI(Claude Code)本来就会 grep + Read,实测它 grep 比 cocoindex 准。语义搜索唯一补位的是「不知道函数叫什么、各 repo 命名还不一致时按意图召回」(上表最后一行),但这个场景窄,grep 用对正则也能覆盖。

    2. 「改 X 影响哪些 repo」这一半 —— 语义搜索 fundamentally 做不到。 这是引用追踪(找调用图),是另一类工具(「按关系搜」)的活。语义搜索的输出是「相似度排前 N 的片段」,这个形式装不下「完整引用列表」:它会漏(截断真实调用方)、会混(把定义/调用方/无关配置都算进来)、还没法说「这个 repo 一个都没有」。上表第 2 行实测漏了 8 个、答不出「0」。

    两个工具各自的实测/核实情况(补充,不影响「都不用」的结论)

    • cocoindex-code:开箱即本地(自带本地 embedding + SQLite,代码零外流,这点对 retaintive 代码很重要),装起来轻。坑:本机 Python 3.14 超出它支持范围(要指定 3.13)、装了会起一个常驻后台 daemon、跨 repo 要靠「指向共同父目录 + 圈定 pattern」的 hack(所有 repo 得在同一父目录下)。不支持 Gemini。
    • claude-context:没实测检索质量(本地化要额外装 Ollama + Docker 起 Milvus,官方本地文档还残缺,投入产出不值)。但核实了两个关键事实:它的「锁当前目录」问题(issue #245)至今 OPEN、官方零回应 —— 索引了别的 repo,但人不在那个目录就查不了,对「跨 9 repo」是直接硬伤;完全离线安装指南还是社区用户自己补的(issue #162 未收录)。它支持 Gemini(唯一比 cocoindex 强的点),但不足以翻盘。

    真要解决这两个需求,对症的方向是

    • 「防重复」:CLAUDE.md 里写清 canonical helper 在哪(callytics-infrastructure 的「🔧 Shared Resources」表就是这个思路)+ AI 自带 grep。零成本、零外流、零运维,实测比语义搜索准。
    • 「改 X 影响谁」(真要工具):IDE 的「Find All References」(LSP,本地精确免费,但单 repo)/ Augment(付费 $20/月,跨 repo 引用追踪,但用户骂贵烧钱)/ Sourcegraph 自托管(免费但要自己编译冻结版)。这些是「按关系搜」,不是本次测的「按意思搜」。

    实测进度(因为宣传不算数,跑起来才算)

    • ✅ Rspress llms(2026-06 迁移后实测)—— 中文导航能用、frontmatter 加 description: 可带描述,已采用。详见 §②。
    • ✅ Repomix(2026-05-29 实测)—— 代码 repo 能压、docs repo 爆 token,划掉,只在一次性场景用。详见 §③。
    • ✅ cocoindex-code(2026-05-29 实测)+ claude-context(文档/issue 核实)—— grep 4 场景赢 3,需求不对症,两个都不用。详见 §④。

    搜索这层结论已定:不引入语义搜索工具,「防重复」靠 CLAUDE.md 写清 helper 位置 + AI 自带 grep。

    为什么不换 Mintlify(文档网站平台)

    换网站平台解决不了核心问题。Mintlify 的自动导航功能绑死在它自己的托管上(搬不走)、只管搬进它平台的页面、多 repo 还只能合并成一个网站(不是真正跨 repo 搜)。而且换过去要放弃我们现在的 Rspress + Cloudflare。我们的真痛点是「AI 找信息 + 跨 repo + 写代码防重复」,换网站一个都不解决。