Documentation Index
Fetch the complete documentation index at: https://adonis-til.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
前置阅读：让 LLM 持续维护你的知识库：Karpathy LLM Wiki 模式精读与落地指南
那篇讲的是”一个人 + 个人知识库”。这篇专门讲”一个团队 + 一个代码仓库”下这套模式长什么样。不重复原理，只讲落地差异。
一句话结论（读不下去就只看这一句）
在代码项目里，LLM Wiki 的最高价值不是”自动生成文档”——那是 TypeScript、Prisma、Storybook 这些工具已经干掉的场景——而是沉淀那些目前只存在于 Slack、脑子里、PR 讨论里的”为什么”和”历史脉络”，并让它们不会过期。
用一句更直白的话：LLM Wiki 替代的不是 Storybook，而是团队那份三个月没人更新的 Notion。
一、场景迁移：从”个人 KB”到”代码项目”，三件事根本改变
Karpathy 原文的默认场景是：一个人读外部文章，LLM 帮他写一份个人 wiki。迁到代码项目，下面三件事会变，而且变得很深：
| 维度 | 个人 KB | 代码项目 |
|---|
| Raw sources 是什么 | 外部文章、播客、论文、书 | 代码本身 + PR 讨论 + bug 报告 + 会议纪要 + RFC + Slack 讨论 |
| Wiki 的用户 | 你一个人 | 团队 + 半年后的你 + 下周入职的同事 |
| 维护触发点 | ”我刚读了一篇新文章" | "我刚 push 了一个 PR” / “我刚升级了一个依赖” / “线上刚出了一个 incident” |
二、怎么判断一个场景值不值得用 LLM Wiki
在讲具体场景之前，先给一条判断准则，这条准则会贯穿全文：
如果这份文档可以从代码里用工具自动生成，就不要用 LLM Wiki 做——让工具做。
LLM Wiki 适合的是：代码里不存在、只存在于人脑和讨论记录里的那些信息——决策理由、历史脉络、跨模块的叙事、“为什么这么做”、“当初放弃了什么方案”。
这条准则下，可以画出一张很清楚的图：
代码里的确定性信息 代码里没有、人脑里有的信息
───────────────── ───────────────────────
API schema 为什么选了这个方案
TS 类型 这个 bug 的根因叙述
DB schema 这个 feature 的时间线
组件 props 依赖升级踩过的坑
测试用例 团队约定的隐性规则
↓ ↓
用 OpenAPI / Prisma / 用 LLM Wiki
Storybook / Typedoc
（零维护成本，永远准） （LLM 维护成本近零）
三、5 个真正值得做的落地场景
每个场景我会给你：
- 是什么 —— 一句话
- Raw sources —— 原始素材从哪里来
- Wiki 长什么样 —— 实际的目录/文件结构
- 触发时机 —— 什么事件让 LLM 去更新
- LLM 的独特价值 —— 为什么人做不好这件事
- ROI —— 收益评估
场景 1：ADR 决策档案（杀手级场景）
是什么：把”为什么我们选了 A 而不是 B”这种决策，从 Slack / PR 讨论 / 会议纪要里打捞出来，变成一份会随时间演化的持久文档。
Raw sources：
- PR 讨论串（特别是 review 里的设计争论）
- Slack 里的架构讨论串
- 会议纪要、白板截图
- RFC 草稿
Wiki 长什么样：
docs/wiki/decisions/
├── index.md # 所有决策的索引
├── 2026-01-why-zustand-over-redux.md
├── 2026-02-why-trpc-over-rest.md
├── 2026-03-why-better-auth.md
└── 2026-04-why-turborepo-over-nx.md
# 为什么选 Zustand 而不是 Redux
- **决策时间**：2026-01-15
- **决策者**：@alice / @bob
- **影响范围**：整个前端状态管理层
- **状态**：active（尚未被挑战）
## 背景
...
## 考虑过的方案
- Redux + RTK: 优点 ... / 缺点 ...
- Zustand: 优点 ... / 缺点 ...
- Jotai: 优点 ... / 缺点 ...
## 最终选择
Zustand，因为 ...
## 放弃 Redux 的核心理由
...
## 未来什么情况下应该重新评估这个决策
- 如果团队规模超过 20 人
- 如果需要 time-travel debugging
- 如果出现超过 3 个全局复杂状态机
## 相关讨论
- [PR #234 的 review 讨论](https://github.com/...)
- [Slack 讨论串 2026-01-12](slack://...)
- PR description 或 commit message 里出现
ADR: 前缀 → agent 自动起一份新 ADR
- 出现”我们为什么不用 X”这类问题时 → agent 查是否已有 ADR，没有就起一份
LLM 的独特价值：
做 ADR 这件事本身人是会的，但保持 ADR 最新人是做不到的。
举个例子：你 2026-01 写了”为什么选 Zustand”，2026-03 团队讨论到是不是要加 Redux DevTools 的能力——这个讨论在 Slack 里发生了，没人会想起来回头去更新那份 ADR。半年后，新同事来问同样的问题，前半年那段重要的讨论就丢了。
LLM Wiki 模式的 agent 会做这件事：每次发生架构讨论，它主动打开相关 ADR，判断是不是要追加一条：
> ⚠️ **2026-03-12 — 该决策被部分挑战**
>
> 在 [PR #456](...) 的 review 里，@carol 提出因为新加的 feature X，需要 time-travel debug 能力。
> 当前结论：在 Zustand 上自己手写 devtools middleware，暂不迁移。
> 重新评估阈值：如果再出现类似需求 2 次，就考虑迁移。
场景 2：Feature 总图（“一个 feature 一张页”）
是什么：项目里每个 user-facing feature 都有一张 wiki 页，一页浓缩该 feature 的所有信息——用户流程、涉及的代码路径、相关 API、DB 表、known bugs、owner、metrics dashboard 链接。
Raw sources：
- PRD 文档、Figma 链接
app/(features)/<feature>/ 目录下的所有代码- 相关 API routes（
app/api/...）
- 相关的 Prisma schema 片段
- Sentry / PostHog 相关 events 的 dashboard
- 曾经的 bug 修复记录
Wiki 长什么样：
docs/wiki/features/
├── index.md
├── checkout.md
├── search.md
├── user-profile.md
└── payment-webhook.md
checkout.md 可能长这样：
# Checkout（结账流）
- **PM Owner**: @dave
- **Tech Owner**: @alice
- **Last Major Change**: 2026-03 (添加 Apple Pay 支持)
- **Metrics Dashboard**: [link](...)
## 一句话说明
用户从购物车到支付完成的完整流程，支持信用卡 / Apple Pay / 微信支付。
## 用户流程
1. `/cart` → 用户点击 "Checkout"
2. `/checkout/shipping` → 填写收货地址
3. `/checkout/payment` → 选择支付方式
4. POST `/api/orders` → 创建订单
5. 根据支付方式分发到对应 webhook
6. `/checkout/success` → 订单确认页
## 涉及的代码
### 页面
- `app/checkout/shipping/page.tsx`
- `app/checkout/payment/page.tsx`
- `app/checkout/success/page.tsx`
### API Routes
- `app/api/orders/route.ts` (POST: 创建订单)
- `app/api/payments/stripe/webhook/route.ts`
- `app/api/payments/apple-pay/webhook/route.ts`
### 组件
- `components/checkout/ShippingForm.tsx`
- `components/checkout/PaymentSelector.tsx`
- `components/checkout/OrderSummary.tsx`
### 涉及的 Prisma 模型
- `Order`
- `OrderItem`
- `Payment`
- `ShippingAddress`
## 历史 Bug
- [2026-02](link) 优惠券并发使用导致超发 → 用 DB constraint 修掉
- [2026-03](link) Apple Pay 退款未触发库存回滚 → 在 webhook 里补了 transaction
## 已知的技术债
- Payment webhook 重试逻辑在三个文件里重复了
- Order status 转换没有 state machine 校验
## 相关 ADR
- [2026-02 why-we-use-db-constraints-for-coupons](../decisions/2026-02-why-db-constraints-for-coupons.md)
- PR merge 到
app/checkout/** 或 components/checkout/** → agent 更新 checkout.md
- 新的 Sentry error 频繁出现在这个 feature 的文件里 → agent 主动追加到”历史 Bug”
- PR description 里明确提到”影响 checkout” → 也触发更新
LLM 的独特价值：
你接手一个 feature 想改一个 bug，要花 2 小时从 app/ 翻路由、从 prisma/schema.prisma 找表、从 Sentry 找错误、从 Figma 找设计……
这些信息本来应该在一个地方，而不是散落在 6 个工具里。
Feature Page 的价值是提供一个入口页，让你不用记得每个工具在哪。更强的是：PR bot 可以在 review 里自动贴一句：
⚠️ 你这次改动触及了 checkout feature。根据 checkout.md 的 Feature Page，相关的技术债包括 “Payment webhook 重试逻辑重复”，你要不要一起处理？
这就让 wiki 从”被动文档”变成了主动的 review 助手。
ROI：⭐️⭐️⭐️⭐️
尤其适合所有权频繁交接的团队（每次新人接手一个 feature 都要花一两天理解现状）。
场景 3：依赖情报页（Dependency Intel）
是什么：每个非平凡的依赖（react-hook-form、zustand、better-auth 这种）都有一页，包含：我们用了哪些子能力、踩过哪些坑、为什么当初选它、升级注意事项。
Raw sources：
package.json- 各库的 CHANGELOG（upstream）
- 你项目里实际的 import 调用点
- 历史上的 workaround PR
Wiki 长什么样：
docs/wiki/deps/
├── index.md
├── react-hook-form.md
├── zustand.md
├── better-auth.md
├── tanstack-query.md
└── prisma.md
react-hook-form.md 的样子：
# react-hook-form
- **当前版本**：7.52.0
- **上次升级**：2026-02-20 (from 7.48.0)
- **引入时间**：2025-09
- **替代了**：原来的 formik + yup 方案
## 我们实际用到的子能力
- `useForm` + `register`
- `Controller`（配合 Radix Select / DatePicker）
- `zodResolver`（all schemas in `lib/schemas/`）
- ❌ 没用 `useFieldArray`（有嵌套表单时考虑）
- ❌ 没用 `useWatch`（目前都用 form.watch()）
## 项目里主要的调用点
- `components/checkout/ShippingForm.tsx`
- `components/auth/LoginForm.tsx`
- `components/settings/ProfileForm.tsx`
- （共 12 个文件，grep: `from "react-hook-form"`)
## 当初为什么选它而不是 formik
见 [ADR 2025-09-why-rhf-over-formik](../decisions/2025-09-why-rhf-over-formik.md)
## 踩过的坑
### 坑 1：Controller 和 Radix Select 的 onValueChange
Radix Select 的 `onValueChange` 签名和 RHF 的 `field.onChange` 签名不完全兼容。
修复：`components/ui/select.tsx:45` 做了 adapter。
### 坑 2：zodResolver 的 async 校验
当 zod schema 里有 `.refine(async ...)` 时，默认的 zodResolver 不会等待 promise。
修复：需要用 `zodResolver(schema, { async: true })`。
## 升级注意事项
- 7.52 → 7.53 的 breaking change：`useController` 的返回类型收窄了 ...
- 7.53 → 8.0 的 breaking change：预计 deprecate `Controller`，改用 `createFormHook`
package.json 的 dependencies 改动 → agent 重读对应页的”当前版本”和”升级注意事项”- 新加一个依赖 → agent 起一份新页（但只对”非平凡”依赖起，
lodash 不用）
- 每周 lint 时，agent 抓一次 upstream CHANGELOG，主动更新”升级注意事项”
LLM 的独特价值：
npm outdated 告诉你有 30 个包可以升，但不告诉你每个升级对你代码的实际影响。
LLM 的独特价值在于：它能读 upstream CHANGELOG + grep 你的项目，得出一个针对性的影响评估：
📦 react-hook-form 7.52 → 7.53 升级建议
upstream CHANGELOG 说 useController 的返回类型收窄了 field.ref 为 RefCallback 而不是 MutableRefObject。
在你的项目里，我 grep 到以下文件用了 field.ref.current：
components/ui/select.tsx:52components/forms/PhoneInput.tsx:33
这两处升级后会编译报错，建议升级前先改成 useImperativeHandle 或 useEffect + callbackRef 的写法。
这是人做不了的——人读 CHANGELOG 能读懂变化，但不会去 grep 整个项目找受影响的调用点。LLM 会。
ROI：⭐️⭐️⭐️⭐️⭐️
你会发现自己突然敢升级以前不敢碰的依赖了。
场景 4：Bug 档案（Incident Wiki）
是什么：每个线上 bug 一页，包含：表象、根因、修复、涉及文件、关联的 incident。重点是让 LLM 主动做归纳——把表象不同但根因相同的 bug 连起来。
Raw sources：
- Sentry / PostHog 事件详情
- git commit（特别是
fix: 前缀的）
- Post-mortem 文档
- 客诉工单
Wiki 长什么样：
docs/wiki/bugs/
├── index.md
├── 2026-03-12-coupon-overuse.md
├── 2026-04-01-apple-pay-refund-stock.md
├── 2026-04-05-server-component-usestate.md
└── concepts/ # LLM 归纳出的"根因概念"
├── race-conditions-in-db.md
└── server-vs-client-boundary.md
# [2026-04-05] server component 里用 useState 导致首页空白
- **严重度**: P1
- **发现时间**: 2026-04-05 14:32 via Sentry
- **修复时间**: 2026-04-05 15:10
- **修复 PR**: [#789](link)
- **根因分类**: [server-vs-client-boundary](../concepts/server-vs-client-boundary.md)
## 表象
首页用户随机 10% 遇到空白页。Console 里是 "useState is not a function"。
## 根因
`app/page.tsx` 意外引入了 `components/PromoBanner.tsx`，后者是 client component
但没加 `"use client"` 指令。Next.js 把它当 server component 处理，useState 就 crash 了。
## 为什么类型检查没抓到
TS 不区分 server/client component，这是一个运行时才发现的 boundary 问题。
## 修复
在 `components/PromoBanner.tsx` 第一行加 `"use client"`。
## 后续预防
- 加了一个 ESLint rule 检测 hooks 在没有 `"use client"` 的文件里被使用
- 相关规则在 `eslint.config.mjs:87`
🔍 Wiki Lint 发现
bug-2026-03-12、bug-2026-04-01、bug-2026-04-05 这三个表象完全不同的 bug，
根因可以归纳为同一个概念：“server/client component 边界识别不准”。
建议新建一个概念页 docs/wiki/bugs/concepts/server-vs-client-boundary.md，
把三个 bug 作为该概念的实例连接起来，
并在里面沉淀”怎么预防这类 bug”的通用做法。
这是 LLM Wiki 相对传统 bug tracker 的质变：它不只是记录，它主动做归纳，把”一次性 fix”变成”沉淀为团队规范”。
ROI：⭐️⭐️⭐️⭐️
中型及以上团队特别有价值。小团队 bug 少时意义有限。
场景 5：Onboarding Wiki（自维护的”代码库导览”）
是什么：给新人的”从零到能改第一个 PR”的导览，但它是自维护的——每次 PR 合并会自动检查 onboarding 里引用的路径、命令、环境变量还在不在，过期了自动打 stale 标记。
Raw sources：
- 整个 repo
package.json scripts.env.example- 当前的 CI 配置
Wiki 长什么样：
docs/wiki/onboarding/
├── 00-start-here.md
├── 01-local-setup.md
├── 02-codebase-tour.md
├── 03-your-first-pr.md
└── troubleshooting.md
- 每次 PR merge → agent 跑一次 onboarding lint：
- onboarding 里引用的所有文件路径还存在吗？
- 提到的
pnpm xxx 命令在 package.json 里还有吗？
- 说的环境变量在
.env.example 里还在吗？
- 失败的项自动加
> ⚠️ STALE: 这行引用的 xxx 已经不存在，需要更新
LLM 的独特价值：
传统 onboarding 文档写完就开始腐烂。代码改了文档没跟上，新人读到过时的东西，第二天得找老同事救命。
LLM Wiki 的区别不是”写得更好”，而是**“每次 PR 合并时它会自动检查自己是不是还准确”。检查不过就打 stale 标记。这让 onboarding 文档有了被动更新**机制——哪怕没人主动去改，它也不会默默腐烂。
ROI：⭐️⭐️⭐️
高度取决于团队新人频率。每个月来一个新人的团队 ROI 高；一年不招一个人的团队意义有限。
四、反面清单：哪些事不要用 LLM Wiki 做
下面这些场景每一个都能套 LLM Wiki，但都不该套，因为有更好的工具：
| 想做的事 | 为什么不适合 LLM Wiki | 该用什么 |
|---|
| API 文档 | schema + 类型已经可以自动生成 | @trpc/openapi / Swagger / Orval |
| DB schema 文档 | Prisma 自动生成 ERD 和类型 | Prisma Studio / Atlas / dbdocs |
| 组件 props 文档 | TS 类型 + Storybook Controls 已经是事实标准 | Storybook / Typedoc |
| 代码行级注释 | 这是代码本身的责任 | JSDoc / 好的命名 |
| Test coverage 报告 | 已经有成熟工具 | Vitest / Jest --coverage |
| 部署拓扑图 | 基础设施即代码本身就是描述 | Terraform / Pulumi 自己的 graph 命令 |
如果一份文档可以从代码里用工具自动生成，就不要用 LLM Wiki 做——让工具做。
LLM Wiki 只做”代码里不存在、只存在于人脑和讨论里”的信息。
五、最小起步方案：今天就能在项目里试一下
别一开始就上 5 个场景。按下面的顺序来：
Step 1：起最小骨架（10 分钟）
<your-nextjs-project>/
├── CLAUDE.md # schema 层
├── docs/
│ └── wiki/
│ ├── index.md # content-oriented 索引
│ ├── log.md # chronological 操作日志
│ └── decisions/ # 先只做 ADR
│ └── .gitkeep
Step 2：在 CLAUDE.md 加三条规则
## Wiki 维护约定
当发生以下事件时，自动维护 `docs/wiki/`:
1. **ADR 触发**：当 PR description 或 commit message 里包含 `ADR:` 前缀时，
在 `docs/wiki/decisions/` 下新建一份决策档案，文件名格式 `YYYY-MM-<slug>.md`，
并在 `index.md` 里追加一行入口。
2. **ADR 挑战**：当出现明显挑战已有决策的讨论时（例如新 PR 提到
"as discussed, we're moving away from X"），打开相关 ADR，
在末尾追加一条 `> ⚠️ YYYY-MM-DD — 该决策被部分挑战：...`。
3. **Log 记录**：所有操作（创建 / 更新 / lint）都追加一行到 `log.md`，
格式 `## [YYYY-MM-DD HH:MM] <action> | <target>`。
Step 3：只做场景 1（ADR），跑两周
别急着上 Feature Page、Dependency Intel 那些。先只跑 ADR，两周之后看感觉对不对：
- 有没有 ADR 真的被写出来？
- 写出来的 ADR 自己回头读起来有没有价值？
- 挑战记录有没有真的发生？
跑对了再加第二个场景。跑不对先问”为什么不对”，大概率是 schema 里的规则写得太抽象 / 太死板，需要修。
Step 4：什么时候加更多场景
以下信号出现时，再加对应场景：
- 你发现 PR review 里反复问”为什么这样写” → 加 ADR 持续维护（场景 1 的进阶）
- 你接手一个不熟悉的 feature 花了 2 小时摸索 → 加 Feature 总图（场景 2）
- 你升级一个依赖时心里发虚 → 加 依赖情报页（场景 3）
- 连续两三个 bug 看起来根因相似 → 加 Bug 档案（场景 4）
- 团队来了新人且没人愿意带 → 加 Onboarding Wiki（场景 5）
六、一些常见的合理化，和为什么要挑战它们
| 你可能想 | 但实际上 |
|---|
| ”这不就是 README.md 吗？“ | README 是静态的，写完就没人维护。LLM Wiki 是事件驱动的、自动维护的。这是质的差别。 |
| “我们已经有 Notion / Confluence 了” | 对，且没人更新。LLM Wiki 的目的不是替 Notion，是解决”没人更新”这件事本身。 |
| “让 LLM 自动写文档风险太大，会瞎编” | 所以永远要人 review。LLM 提出变更 → 人批准 → 合入 wiki。和 PR review 是一个流程。 |
| “我们项目太小，不值得搞这个” | 小项目的起步成本也小——只做场景 1 十分钟就搞定了。别做 5 个。 |
| “写 schema（CLAUDE.md）好麻烦” | 一开始不要追求完美 schema。写一份能跑的最小版，跑出问题再改。schema 是被使用养大的。 |
七、行动清单
读完这篇你可以立刻做的事：
写在最后
前一篇 til 我们聊了 LLM Wiki 模式的原理，结尾说它最大的优势是”LLM 不会无聊”。
这一篇我们聊了搬到代码项目里能干什么——答案是：它能替你做团队里所有”没人愿意做但又必须做”的那些维护工作。
- ADR 写完就没人回头更新？LLM 会。
- Feature Page 写完就腐烂？LLM 会自动检查过期。
- 依赖升级没人敢碰？LLM 会读 CHANGELOG + grep 你的代码，给你针对性的影响评估。
- Bug 一个一个修、从不归纳？LLM 会主动做跨 bug 的根因归纳。
- Onboarding 文档写完就烂？LLM 会每次 PR 合并时 lint 一次自己。
你的团队里那份没人更新的 Notion，换成一份 agent 维护的 wiki，会成为团队真正的”制度记忆”。
这是 LLM Wiki 模式在代码项目里最朴素、也最有价值的一件事。
延伸阅读
