> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

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

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

## 一句话结论

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 图)喂不进。详见 [调研清单](/tooling/research/ai-tooling-inventory.md)。

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

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

**总比分 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](https://github.com/zilliztech/claude-context/issues/245))至今 **OPEN、官方零回应** —— 索引了别的 repo,但人不在那个目录就查不了,**对「跨 9 repo」是直接硬伤**;完全离线安装指南还是社区用户自己补的([issue #162](https://github.com/zilliztech/claude-context/issues/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 + 写代码防重复」,换网站一个都不解决。