# Token Context Economics

> 当用户希望在保证开发质量的前提下减少 token 消耗、降低无效上下文、避免全量阅读、控制改动半径、用更少的信息完成更稳定的实现时使用。适用于“怎么更省 token”“先别全量读文件”“搜索优先”“减少返工”“提高上下文利用率”“用更小成本做同样质量”等场景。

- Skill: `qiyang-job/token-context-economics` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add qiyang-job/token-context-economics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qiyang-job/token-context-economics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: qiyang-job (https://skillmd.com/u/qiyang-job)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/qiyang-job/token-context-economics

---


# Token Context Economics

## Skill Goal

把“省 token”从一句泛泛建议，升级成一套可执行的开发纪律：少读无关信息、少做无效解释、少引入返工，同时保持实现质量、验证强度和交付稳定性。

本 skill 的目标不是让 AI 变得更偷懒，而是让 AI 更像成熟工程团队：

- 先定位，再阅读
- 先读取最相关上下文，再按需扩展
- 先做最小安全改动，再决定是否扩圈
- 先验证，再长篇解释
- 先压缩结果，再沉淀记忆

## When To Use

在以下场景优先启用本 skill：

- 用户明确要求降低 token 消耗或提高上下文效率
- 项目文档较多、代码较多，担心每轮都读太重
- AI 容易重复阅读、重复解释、范围越做越大
- 需要在长项目里保持稳定产出但不想上下文持续膨胀
- 需要建立“搜索优先、验证优先、压缩输出”的工作流
- 想把省成本和保质量同时纳入项目协作规范

## When NOT To Use

以下场景不要强行启用：

- 只是一次纯概念讨论，没有代码或文档执行成本
- 任务极小，已经能一眼定位到唯一文件且无额外上下文负担
- 用户明确要求进行大范围审计、全量梳理或系统性评估

本 skill 的目标是 **减少无效成本**，不是机械地压缩一切信息。

## Token Economy Core Principles

### 1. Search Before Read

默认先搜索，再决定读哪些文件。

优先顺序：

1. 用户当前请求
2. 项目级规则文件，例如 `AGENTS.md`、`CLAUDE.md`
3. 当前状态文件，例如 `.ai-context/00-current-context.md`
4. 精准搜索结果
5. 目标文件的局部读取
6. 相邻依赖文件
7. 只有在证据不足时才扩大范围

不要因为“保险”而默认全量读仓库。

### 2. Read the Nearest Useful Context

优先读离任务最近、最可能改变决策的材料：

- 当前目录或当前功能附近的规则
- 任务相关的组件、接口、测试、样式
- 项目当前状态摘要，而不是历史全量记录
- 用户刚刚提出的新约束，而不是旧的泛化说明

近处有证据时，不要跳回去重读全局背景。

### 3. Prefer Small Safe Loops

默认先完成一个最小闭环：

- 一次只解决一个明确问题
- 一次只控制一个主要改动面
- 一次只引入一组新规则源
- 没有必要时，不顺手做大重构

返工是最贵的 token 消耗之一。

### 4. Verification Before Narration

改完先验证，再解释。

优先做：

- 最相关的 lint / type / targeted test / smoke check
- 与本次改动直接相关的手工验证说明
- 确认真实结果后再输出总结

不要在没有验证的情况下，先写长篇“我做了什么”。

### 5. Compression Over Replay

输出优先压缩，不要复读过程。

默认避免：

- 反复复述用户原话
- 大段转述已读文件内容
- 为了显得认真而写超长中间汇报
- 把整个思考过程重新讲一遍

向用户暴露的应该是 **关键结论、关键依据、关键改动、关键验证**。

## Default Working Workflow

### 1. 先判断任务类型

先把当前任务归类为以下类型之一：

- 局部 bug / 局部样式 / 小逻辑修复
- 现有功能的小迭代
- 需要跨多个文件理解的中等改动
- 需要结构化探索的复杂任务
- 需要全局审计或系统评估

任务越局部，默认上下文越轻。

### 2. 先建立最小上下文包

默认只收集以下最小信息：

- 用户的明确目标
- 当前工作区与项目规则
- 当前状态快照或设计基线（如果任务依赖它）
- 与目标相关的搜索命中
- 最少量的目标文件内容

如果这些信息已足够做决定，就不要继续扩大读取范围。

### 3. 用搜索决定阅读面

先做搜索，再决定读哪些文件：

- 找定义、调用链、处理入口时，先做语义搜索
- 找精确字符串、配置键、日志、命令时，先做精确搜索
- 找文件名、模式文件时，先做文件搜索
- 找到候选点后，再读具体文件和必要上下文

### 4. 控制改动半径

每次编码前，先回答：

- 这次最小闭环是什么
- 哪几个文件是必须改的
- 哪些潜在问题只是记录，不在本轮处理
- 哪种“顺手优化”会扩大范围

如果一次改动已经跨到第二个子系统，默认重新评估范围。

### 5. 分层验证

验证顺序优先如下：

1. 语法和类型层
2. 本次改动关联的 lint
3. 目标功能的局部验证
4. 必要时再做更大范围检查

不要对一个微小文案修复默认跑整仓重型验证，也不要对明显高风险变更只做表层检查。

### 6. 压缩结果并回写稳定记忆

收尾时只保留高价值信息：

- 做了什么
- 为什么这样做
- 跑了什么验证
- 还有什么未解决
- 哪些规则或经验值得进入长期记忆

过程型废话不要写进长期上下文。

## Hard Rules

默认遵守以下硬规则：

- 不默认全量读取 README、docs、源码和上下文包
- 不重复读取已经确认稳定且与当前决策无关的文件
- 不因为“显得稳妥”而跑明显过重的检查
- 不在未定位问题前就开始提出大改方案
- 不把大段过程汇报伪装成高质量工作
- 不把“顺手再改一点”当成免费行为
- 不为省 token 而跳过必要验证

## Required Output Contract

当本 skill 触发时，默认先给出以下简洁结构：

1. **任务类型判断**
2. **本轮最小上下文包**
3. **准备读取或已读取的关键依据**
4. **最小改动闭环**
5. **验证策略**
6. **哪些内容明确不在本轮处理**

完成后默认输出：

1. **关键改动**
2. **关键依据**
3. **关键验证**
4. **遗留风险或下一步**

## Project Contract: `execution-budget.md`

建议项目根目录维护一个 `execution-budget.md`，至少描述：

- 哪些文件必须优先读取
- 哪些目录默认不要全量读
- 常见任务的推荐搜索入口
- 不同类型改动对应的验证命令
- 哪些检查属于高成本操作
- 中间汇报应当多短
- 什么情况下必须先停下来收口范围

如果项目里还没有这个文件，优先使用 `scripts/init_execution_budget_md.py` 初始化一份。

## Optional Skill Stacking

在当前技能体系中，推荐这样叠加：

- 先用 `01-开发约束skill` 收敛范围
- 再用本 skill 控读取成本、改动半径和验证强度
- 涉及 UI 时叠加 `03-高质量UI体验skill`
- 收尾时用 `项目上下文守护skill` 压缩沉淀长期记忆

如果只是一次小修，不必强行叠满全部 skill。

## Success Criteria

如果本 skill 运作正确，应出现这些变化：

- 平均读取文件数下降
- 重复读取率下降
- 中间汇报更短但不失真
- 改动闭环更小、返工更少
- 验证更贴合风险，而不是一刀切
- 用户获得的结果更聚焦，而不是更啰嗦

## References

按需读取以下文件：

- `00-先读我.md`：如何把这个 skill 投放到项目中使用
- `references/01-Token治理目标与工作方式.md`：核心目标、原则与使用方式
- `references/02-上下文分层读取策略.md`：如何建立最小上下文包
- `references/03-搜索优先与最小阅读.md`：如何先搜索、后阅读
- `references/04-最小改动半径规则.md`：如何控制改动范围与返工成本
- `references/05-验证优先与检查分层.md`：如何做风险匹配的验证
- `references/06-输出压缩与汇报规范.md`：如何减少无效解释与冗长汇报
- `references/07-高耗token反模式.md`：高频耗 token 坑位清单
- `references/08-效果评估与验收.md`：如何判断这个 skill 是否真的有效
- `references/09-与其他skill协同方式.md`：如何与现有 3 个 skill 叠加使用
- `references/10-GitHub最佳实践对齐评估.md`：当前版本与 GitHub 公开实践的对照结果