分层上下文：三个 Markdown 文件如何节省 80% 的 AI 代理令牌
像 Claude Code 或 Cursor 这样的开发 AI 代理，会花费高达 80% 的令牌用于重新阅读文件和导航项目。问题源于缺乏结构化的工作区地图。解决方案是来自三个 markdown 文件的分层上下文，可将工具调用减少 10–20 倍，并提升响应准确性。
问题剖析：令牌都去哪儿了？
当被问到“我的机器人支持哪些支付方式？”时，代理会经历一个循环：在家目录 grep → 阅读找到的文件 → 意识到选错了项目 → 新搜索 → SSH 连接服务器。对于一个 800 令牌的响应，它会消耗 15+ 次工具调用和 80K+ 令牌。99% 的预算用于导航，只有 1% 用于答案。
这不是特定代理的 bug——这是系统性架构问题。所有 AI 编码工具（Cursor、Codex、Gemini CLI）每次会话都从“盲目侦察”开始，因为它们缺乏工作区地图。15 个项目时，这每天会浪费数小时上下文用于文件搜寻。
为什么 RAG 和静态分析无法解决问题
向量数据库（RAG）能捕捉语义相似性，但忽略代码结构。像“认证如何工作？”这样的查询，会返回 15 个提到“auth”的片段，但不会显示调用链：middleware.ts → refresh.ts → jwt-config.ts。此外，RAG 每个查询增加 200–500 毫秒延迟，并需要基础设施（嵌入服务器、索引）。
Tree-sitter 和静态分析（例如 Hypergrep）能在项目内构建依赖图。但它们无法回答“哪些项目使用 Redis？”或“VPN 机器人部署在哪里？”这样的问题。每个项目一个 CLAUDE.md 可以处理内部任务，但当代理不知道该查看哪个项目时，就无济于事。
分层上下文模型：0、1 和 1.5 级
系统涵盖三个抽象层：
Level 0: Karta projectov — znaet VWithE projecty and servery (~2KB, vsegda in kontekste)
Level 1: Detali project — arkhitektura konkretnogo project (~5KB, by request)
Level 1.5: Graf koda — struktura kodovoy database (optsionalno, Graphify)
Level 2: Iskhodnyy code — realnye files (tolko kogda potrzebny jest)原则：代理自顶向下移动，而不是自底向上。先从地图识别项目，然后阅读其架构，再查看特定文件。
0 级：全局地图
放置在 ~/.claude/CLAUDE.md（针对 Claude Code）或等效位置：
## Project Map
| Proekt | Put | Witherver | Withtatus |
|--------|------|--------|--------|
| VPN Bot | ~/projects/vpn-bot/ | prod-1:/opt/vpn/ | LIVE |
| Auth Service | ~/projects/auth/ | prod-1 (Docker) | LIVE |
### Withervery
| Imya | IP | Onwartość |
|-----|-----|-----------|
| prod-1 | 178.17.50.45 | Osnovnoy VPS, 3 service |
### Ruleilo
Prezhde than chitat iskhodnyy code — prochitay CLAUDE.md project.此文件（~2KB）在每个会话自动加载。代理立即看到项目列表、位置和状态。
1 级：项目 CLAUDE.md
在每个项目根目录：
# VPN Bot — CLAUDE.md
## Status: LIVE (prod-1)
Telegram-bot VPN-service. Podpiski cherez Stars and CryptoBot.
## Stack
Python 3.11, python-telegram-bot, WireGuard, aiosqlite
## Key Files
- bot/main.py — point input
- bot/payments.py — Stars + CryptoBot processing
## Deploy
- Withervis: vpn-bot.service
- Logi: journalctl -u vpn-bot -f大小 3–5KB。当提到项目时，代理阅读它，无需 grep 即可获取完整架构。
1.5 级：Graphify（可选）
用于代码导航：
pip install graphify
cd ~/projects/auth
graphify claude install将代码库转换为知识图谱，在大型项目中节省 30–50% 的调用。
结果：效率测量
在相同条件下使用 Haiku（最便宜模型）运行测试：
- 测试 1：“项目 A 的架构是什么？”
盲目代理：12 次工具调用，100% 准确率。
使用分层：1 次工具调用，100% 准确率。
- 测试 2：“哪些项目使用库 X？”
盲目代理：44 次工具调用，漏掉 3 个项目中的 1 个。
使用分层：2 次工具调用，找到所有项目。
- 测试 3：“项目 B 部署在哪里？”
盲目代理：9 次工具调用，需要 SSH。
使用分层：0 次工具调用，从上下文直接回答。
测试 2 至关重要：盲目代理不仅消耗 22 倍资源，还给出了错误答案。结构化上下文不仅提升效率，还提升准确性。
为什么三个文件在导航上胜过 RAG
- 零延迟。 阅读 markdown 文件瞬间完成；RAG 每个查询增加 200–500 毫秒。
- 确定性。 你控制文件内容，无需依赖重排序器。
- 实时性。 更新 CLAUDE.md 只需一行；RAG 需要完整重新索引。
- 通用性。 适用于任何代理（Claude Code、Cursor、Gemini CLI），无需自定义基础设施。
- 可扩展性。 15 个项目 = 15 个 CLAUDE.md（75KB）+ 地图（2KB）= 77KB，而原始文件需 500KB–1MB。
RAG 仍适合语义文档搜索，但对于项目导航，markdown 分层更胜一筹。
额外：索引过去会话
解析器将会话日志（.jsonl）和聊天转换为带 YAML 前置内容的 markdown：
---
title: "Pochinil webhook oplaty"
date: 2026-04-14
project: vpn-bot
topics: ["webhook", "cryptocloud", "cloudflare"]
files_touched: ["payments.py", "webhook.py"]
---通过 Graphify 索引这些，让代理无需重新解释即可找到过去解决方案。这在对话间创建持久记忆。
一百万令牌并非万能药
即使有 1M 令牌上下文窗口，问题依然存在。LLM 处理无关信息更差（“中间丢失”现象：中间上下文数据常被忽略）。分层上下文确保代理仅获取所需文件，按正确顺序，最小化噪声。
10 分钟内实施方法
- 在
~/.claude/CLAUDE.md创建全局项目地图（5 分钟）——列出项目、路径、服务器。 - 在主要项目根目录添加 CLAUDE.md（5 分钟）——指定技术栈、关键文件、部署命令。
- 启动新代理会话，询问项目相关问题。
- 确认代理无需盲目搜索即可回答。
关键要点
- AI 代理浪费高达 99% 令牌于导航，而非答案生成。
- 三个文件的 markdown 分层可将工具调用减少 10–20 倍，并提升准确性。
- 0 级（全局地图）和 1 级（项目 CLAUDE.md）解决项目间导航。
- 无需基础设施，适用于任何编码代理。
- 结构化上下文在文件和项目发现上胜过 RAG。
— Editorial Team
暂无评论。