references/:海量文档的正确打包

references 的三种主要用途

核心原则:让 Claude 能 grep 到

Claude 执行"查资料"的真实动作,是 read 文件 → 自己 grep。你组织 references 的唯一目标,就是让 Claude 的 grep 能准确命中。

如果文件组织混乱,Claude 就会 read INDEX.md → grep 不到 → read 很多无关文件 → tokens 爆炸 → 答案飘忽。

目录组织的三种模式

模式 1: 按主题扁平化(小型 Skill)

references/
├── auth.md
├── billing.md
├── users.md
└── webhooks.md

适合 < 10 个文档。SKILL.md 直接说"认证相关看 auth.md",Claude 一次命中。

模式 2: 按领域分层(中型 Skill)

references/
├── INDEX.md               ← 总目录,每个文档一行描述
├── api/
│   ├── rest.md
│   ├── graphql.md
│   └── webhooks.md
├── data/
│   ├── schema.md
│   └── metrics.md
└── guidelines/
    ├── error-handling.md
    └── rate-limits.md

适合 10-50 个文档。INDEX.md 是灯塔——Claude 第一次进来读它,知道去哪找。

模式 3: 索引驱动(大型 Skill)

references/
├── INDEX.md
├── tables/
│   ├── INDEX.md           ← 200 张表的一行描述
│   ├── users.md
│   ├── orders.md
│   └── ...
└── dictionaries/
    ├── business-terms.md
    └── ...

适合 50+ 文档、文档之间有强引用关系。每个子目录有自己的 INDEX,做两级检索。

INDEX.md 怎么写

关键:每行一个资源 + 用途描述,让 Claude grep 关键词就能找到文件。

# References 总目录

## API

- `api/rest.md` — REST API 端点清单,包含 auth、billing、users 模块
- `api/graphql.md` — GraphQL schema,查询类型与 mutation
- `api/webhooks.md` — Webhook 事件类型与 payload

## 数据

- `data/schema.md` — 数据仓库主表 schema (orders, users, events)
- `data/metrics.md` — 核心业务指标口径(DAU、MRR、Retention)

## 编码规范

- `guidelines/error-handling.md` — 异常处理模板
- `guidelines/rate-limits.md` — 各 API 的限流策略

单个 reference 文件的结构

每份 reference 开头用标准结构,帮 Claude 快速判断是否读完。

# <文档标题>

> 本文涵盖:xxx。不涵盖:yyy,见 zzz.md。

Keywords: DAU, daily active users, 日活, 活跃用户

## 快速查阅

| 指标 | 口径 | 来源表 |
|------|------|--------|
| DAU  | COUNT(DISTINCT user_id WHERE event_date=today) | events |
| ...  |      |        |

## 详细定义

(长篇解释)

处理超大文档的技巧

技巧 1: 按语义切片

一份 3 万行的 API 文档,别当一个文件。按 module / resource 切片:

references/api/
├── INDEX.md
├── auth/
│   ├── login.md
│   ├── oauth.md
│   └── tokens.md
├── billing/
│   ├── subscriptions.md
│   └── invoices.md
└── users/
    ├── profile.md
    └── roles.md

每个文件一个 endpoint 或 resource,通常 < 500 行。

技巧 2: 把极长字段表做成 JSON

200 个字段的数据字典,与其写成 markdown 表,不如写成 JSON:

{
  "orders": {
    "columns": {
      "order_id": {"type": "bigint", "pk": true},
      "user_id": {"type": "bigint", "fk": "users.id"},
      "amount": {"type": "decimal(10,2)", "nullable": false}
    }
  }
}

好处:Claude 可以用 jq 精确查询字段,或者自己写 Python 读。比 markdown 表稳定。

技巧 3: 带示例优于纯规范

"这个字段最多 120 个字符" × 1

"这个字段最多 120 个字符,超长示例 → 截断示例" × 好用 10 倍

## title 字段

最多 120 字符,超过自动截断并加省略号。

### 示例

- 正常: "秋冬新款羊毛大衣,限时 7 折"(16 字,通过)
- 截断: "冬季新品 × 100+ 款精选!全场满 199 减 50,...
          (第 121 字)剩下的被截断" → 保留 117 字 + "..."

版本与更新

references 会随业务变化:新 API、新指标、新规则。

推荐做法:

1. references 目录独立子 repo 或 submodule,由数据/平台团队维护
2. 脚本自动生成:scripts/sync_schema.py 从 information_schema 拉最新表结构,写到 references/data/schema.md
3. CI 里跑"Skill 回归测试":用典型场景查询,比较新旧 SKILL + references 的 Claude 输出,有变化要 review
4. 文件顶部放 <!-- last-synced: 2026-04-15 -->,超过 30 天 CI 报警

隐私与敏感信息

references 会被加载进 Claude 的上下文,然后发到 Anthropic 服务器。不要放:

• 真实用户数据 / PII(姓名、手机号、身份证)
• 生产环境 credentials、API key、内网密码
• 未公开的合同、财报、战略文件

可以放:脱敏的 schema、公开 API 文档、业务规范描述(不含具体数据)、内部工具的使用手册。

本章小结