qiyang-job 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
默认先搜索，再决定读哪些文件。
优先顺序：
- 用户当前请求
- 项目级规则文件，例如
AGENTS.md、CLAUDE.md - 当前状态文件，例如
.ai-context/00-current-context.md - 精准搜索结果
- 目标文件的局部读取
- 相邻依赖文件
- 只有在证据不足时才扩大范围
不要因为“保险”而默认全量读仓库。
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. 分层验证
验证顺序优先如下：
- 语法和类型层
- 本次改动关联的 lint
- 目标功能的局部验证
- 必要时再做更大范围检查
不要对一个微小文案修复默认跑整仓重型验证，也不要对明显高风险变更只做表层检查。
6. 压缩结果并回写稳定记忆
收尾时只保留高价值信息：
- 做了什么
- 为什么这样做
- 跑了什么验证
- 还有什么未解决
- 哪些规则或经验值得进入长期记忆
过程型废话不要写进长期上下文。
Hard Rules
默认遵守以下硬规则：
- 不默认全量读取 README、docs、源码和上下文包
- 不重复读取已经确认稳定且与当前决策无关的文件
- 不因为“显得稳妥”而跑明显过重的检查
- 不在未定位问题前就开始提出大改方案
- 不把大段过程汇报伪装成高质量工作
- 不把“顺手再改一点”当成免费行为
- 不为省 token 而跳过必要验证
Required Output Contract
当本 skill 触发时，默认先给出以下简洁结构：
- 任务类型判断
- 本轮最小上下文包
- 准备读取或已读取的关键依据
- 最小改动闭环
- 验证策略
- 哪些内容明确不在本轮处理
完成后默认输出：
- 关键改动
- 关键依据
- 关键验证
- 遗留风险或下一步
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 公开实践的对照结果