前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

一、面向 skill 编程

1、理解核心理念与架构

在复杂商业项目中，传统的 Prompt 注入或直接挂载云文档（如 MCP 接入）容易导致 Token 撑爆、准确率低或知识过时。本教程采用 Skill（专家手册） 方案，核心特征是渐进式披露原则。

1）Code Agent 有什么问题

日常开发中使用 Code Agent。一些问题修复、小需求确实完成不错，。但庞大复杂的项目中，复杂一些的需求，只靠 Code Agent 自己检索分析基本无法完成任务。原因有三个：

• 历史逻辑噪声污染：各种业务迭代留下的废弃逻辑和噪声代码散落在流程中，严重干扰 Code Agent 对核心流程的理解
• 多线业务耦合：多条独立运转的产品线的业务逻辑交错在同一套架构链路中，且各自还在持续迭代——梳理任何一条线都必须同时理解另外两条，改动任何一处都可能影响其他产品线
• 代码量大但热代码少：项目有 20w+ 行代码，但日常核心变动局限在 2w 行左右，剩下 18w 行基本都是噪声

2）诊断问题——上下文爆炸与信息噪声

在开始构建之前，请自检你的团队是否面临以下症状：

3）解决思路：结构化知识库 + 渐进式加载

┌─────────────────────────────────────────┐
│           用户意图识别                   │
│     （确定需要哪些知识维度）              │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           知识分层加载                   │
│  领域 → 流程 → 服务 → 接口 → 存储       │
│  （每层按需加载，无关知识隔离）           │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           精准上下文注入                 │
│     （高信噪比的知识供给）                │
└─────────────────────────────────────────┘

3）核心观点： “Skills 编程”

Skills 编程的核心是：将复杂的业务知识、架构逻辑、以及“代码映射”转化为标准化的结构化文档（Skills）。它遵循渐进式披露原则，只在 AI 需要时加载对应的知识，从而将 AI Coding 复杂需求的准确率由“撞墙”提升至 90% 以上

• 知识库是 AI Coding 落地的先决条件
  1. 没有结构化知识支撑，AI 只能在通用层面生成代码
  2. 企业级规范、业务逻辑必须显式编码于知识库中
• 渐进式加载是解决上下文爆炸的唯一路径
  1. 全量知识投喂在工程上不可持续
  2. 基于任务类型的动态组装是规模化应用的基础
• Skills 化维护是知识库可持续的关键
  1. 手工维护知识库成本过高，难以持续
  2. 自动化录入、更新、校验形成正向循环

4）落地路径：四步构建你的 Skill 体系

面向 Skills 编程的核心思想是：将”人写代码”转变为”人写 Skills，LLM 基于 Skills 写代码”。 程序员向更高一层抽象——从”实现逻辑”上升为”定义 Skills“，基于 Skills 将个人经验转化为可复用的 AI 能力单元。

5）为什么没选择 SDD

1. 流程执行成本高：SDD 要求严格遵循”提案（Proposal）→ 实施（Apply）→ 归档（Archive）”三个环节顺序执行，且过程中涉及多轮需求澄清和方案迭代，单个 Spec 从编写到定稿往往需要 3-5轮人工交互，流程本身的投入不可忽视

2. 强依赖个人经验，无法规模化：Spec 的编写质量高度依赖编写者对领域知识的掌握程度——如 SPU/SKU 模型理解、推拉模式选择、字段映射方向等关键决策，仍然散落在个人脑中，缺乏标准化的知识载体。新人面对同一份客户文档，写出的 Spec 质量与老手差距悬殊，无法通过简单培训弥合

3. 领域知识未固化：SPU/SKU混淆、IDv 字段混淆等问题跨项目反复出现，说明领域经验没有沉淀为可复用的约束规则，每次仍需人工记忆和校验

2、知识体系的三层架构

整套知识体系采用三层架构，对应 Code Agent 的认知路径——从全局定位到模块理解再到细节展开：

按照 Agent 的认知路径（全局 → 模块 → 细节）建立以下三层文档：

1）第一层：全局索引与约束（AGENTS.md & Rule）

这是 Agent 接收需求后读取的第一个文档，负责高效率的路由决策，消耗极少 Token。

• 项目概述：说明系统干什么的、架构分层是什么（如三层架构、微服务布局）。

• 全局术语表：消除歧义。例如明确规定“在业务上叫 Creative（创意），但在底层代码库里对应 ad_group_v2 结构”。

• 硬性约束：团队的编程规范、自定义 Linter 校验规则、禁用的函数或依赖。

  • AGENTS.md：指导 Agent 决策“该去读哪个模块的知识”。包含项目架构分层、全局术语表（消除业务词与代码命名的歧义）。

  • Rule 文件：侧重通用的编程规范和软件工程原则（可多仓库共用）。

2）第二层：Skill 主文件（模块核心知识）

每一个独立的业务模块（如：用户认证模块、支付网关、创意渲染流程）对应一个 .md 格式的 Skill 主文件。

❗ 黄金法则：禁止知识与代码脱节。必须将业务领域知识与实际代码流程进行“显式映射”。

每个模块的 Skill 主文件必须包含以下 4 个小节：

1. 路由判定：明确写出“什么需求该读此文件，什么需求不该读”。
2. 业务领域知识：核心概念、业务规则与不变量。
3. 核心代码流程：主流程概览，写清每个节点的职责、代码文件路径、核心函数名、输入输出。
4. 变更指南：修改时机判断、影响检查清单、常见变更模式与示例

3）第三层：引用详情文件（按需展开）

• 操作：链接或附上详细的接口文档、数据库表结构图、旧的需求文档。
• 提示：保持精简，只放最权威的源头信息。

3、建立四层“防腐”机制（确保知识不过期）

知识最大的敌人是腐化（即文档与代码不一致）。如果 AI 读了过时的文档，会产生灾难性的错误。请务必建立以下自动化校验流程：

1）反向校验（让 Agent 在使用知识时自己发现问题）

• 机制：当 AI 使用 Skill 知识去生成代码时，让它同时对比“知识描述的流程”与“实际代码现状”。
• 操作：如果发现不一致，AI 应该暂停生成代码，并输出一份“校验报告”，提示“文档描述 A->B，但代码是 A->C，请人工确认”。
• 流程：知识指导 Code Agent → Agent 读实际代码 → 发现不一致 → 生成修正建议 → 人确认 → 更新知识
• 价值：它几乎没有额外成本。Agent 本来就要读知识、读代码，交叉比对只是顺带完成的动作。而且它直接解决的是存量腐化问题——那些之前没被发现的知识偏差，在每次真实使用中被逐步暴露和修正。

2）缺失知识沟通补充（在需求开发中生长知识）

• 机制：知识腐化是一类问题，知识缺失是另一类。在开发新需求时，遇到 Skill 里没有覆盖的知识盲区时，开发者会与 AI 沟通，提供所缺失的业务背景、规则、约束。这个沟通过程本身就在产生新知识
• 操作：沟通结束后，让 AI 自动总结这次对话的新知识，并更新到对应的 Skill 文件中。这样，知识库会随着业务迭代自动生长。
• 流程：知识缺失 → 人与 Code Agent 反复沟通补充 → Agent 总结后自行更新 Skill → 知识完善
• 价值：这个环节解决的是知识体系的”生长”问题。传统做法是开发完成后由人整理文档，但实际中这一步几乎不会发生——需求做完就做下一个了，谁还会回头补文档？把知识沉淀嵌入开发沟通过程本身，让它成为自然副产品而不是额外负担，才能真正持续运转。

3）Commit 前校验（堵住增量腐化的入口）

• 机制：前两个环节偏被动——用到时才发现问题、聊到时才补充缺失。Commit 前的校验则是一个主动的防线。在代码提交前，自动分析本次代码 diff 是否命中知识更新的触发规则
• 操作：分析代码Diff, Agent 自动分析变更对知识体系的影响，生成结构化的更新建议——精确到哪个业务模块、哪个核心流程的知识需要同步修改。Review 无问题后，自动更新到对应的 Skill 模块
• 流程：触发 Commit 提交 → 提交前强制进入知识 Diff-Check → 不一致则自更新 → 知识与业务代码保持一致
• 价值：这个环节是 Commit 前的必经环节。这样做的好处是将知识更新与代码变更绑定在同一个工作流中——代码改了，知识的检查和更新就在当下完成，不会被拖延到”下次有空再说”。

4）基线全量巡检（兜底防线）

• 机制：即使有了前三层，仍然会有遗漏逐渐积累。每次合并到基线发布结束时，执行全量健康巡检，。

• 操作：全量扫描所有 Skill 文件中的代码锚点（Anchors），检查是否仍然有效，接口定义是否与最新代码一致。

• 流程：合并 master 基线后 → 全量巡检对比 → Code Agent 给出更新报告 → 人 Review 后 Agent 自更新

• 价值：这个环节解决的是”漏网之鱼”问题。前三层各有盲区：反向校验只覆盖被使用到的模块、沟通补充只覆盖当前需求涉及的知识、Commit 校验可能因触发规则不够全面而遗漏。全量巡检作为兜底，确保知识体系的最终一致。

4、实施建议与避坑指南

• 落地建议：不要全面铺开：先找一个业务闭环、近期有需求迭代的模块试点。写完 Skill 后，用真实的需求来验证效果，再决定是否推广。

  阶段	重点任务	预期产出
  第一阶段	建立领域知识层	统一业务术语体系
  第二阶段	构建服务-接口知识	实现服务调用代码生成
  第三阶段	完善存储知识	实现数据访问层生成
  第四阶段	Skills 化维护体系	知识自更新、自校验

• 命名规范统一：同一个业务动作（如“下单”），在所有 Skill 文件中必须使用相同的术语。这能防止 AI 在跨模块推理时产生混淆。

• 知识防腐。防腐机制比知识本身更重要，知识体系建起来不难，难的是在持续迭代中不腐化。优先建立反向校验和 ommit 前校验，让知识更新成为开发流程的自然组成部分。

二、skill 知识库架构设计

1、skill 的结构

Skill 是将领域专业知识、工作流程转化为模型可理解的规范文档，用于扩展模型的边界能力。可以将它理解为特定领域的”专家手册”——不是给人读的文档，而是给 Code Agent 读的结构化领域知识。

Skill 的设计遵循渐进式披露原则，分三级加载来高效管理上下文：这个设计的价值在于：相比把所有知识一股脑塞进 Prompt，渐进式披露让模型在合适的时机获取正确的知识，既节省 Token，又避免信息过载导致的注意力分散。

1）元数据（名称 + 描述）——始终可见，约 100 字，用于路由判断

2）主文件正文——Skill 被触发时加载，控制在 3000 字以内

3）引用资源——模型判断需要时才读取，不浪费上下文窗口

2、skill 知识库架构设计：五层模型

• 纵向：稳定性分层——底层知识变化频率低，上层知识随业务演进
• 横向：场景化加载——不同任务加载不同组合，避免全量传输

1）渐进式加载

Level 5 ┌─────────────────────────────────────┐
        │  存储知识 (Storage)                  │
        │  表结构、索引、约束、生命周期         │
        └─────────────────────────────────────┘
Level 4 ┌─────────────────────────────────────┐
        │  接口知识 (API)                      │
        │  协议定义、字段语义、调用规范         │
        └─────────────────────────────────────┘
Level 3 ┌─────────────────────────────────────┐
        │  服务知识 (Service)                  │
        │  服务边界、能力清单、依赖拓扑         │
        └─────────────────────────────────────┘
Level 2 ┌─────────────────────────────────────┐
        │  流程知识 (Process)                  │
        │  业务流程、步骤编排、参与方           │
        └─────────────────────────────────────┘
Level 1 ┌─────────────────────────────────────┐
        │  领域知识 (Domain)                   │
        │  核心概念、术语体系、边界划分         │
        └─────────────────────────────────────┘
              ↑ 越底层越稳定

2）各层级定位

3）渐进式加载机制：精准上下文供给

输入：用户意图（调用XX服务查询订单）
  ↓
[Stage 1] 领域层加载
  - 识别业务域：订单域
  - 加载核心概念：订单、履约单、状态机
  ↓
[Stage 2] 服务层加载
  - 定位目标服务：订单服务
  - 获取服务元数据：职责、接口列表
  ↓
[Stage 3] 接口层加载
  - 确定具体接口：查询订单详情
  - 获取协议定义：参数、响应、错误处理
  ↓
[Stage 4] 代码生成
  - 基于上述三层知识生成调用代码
  - 无需加载：流程知识、存储知识（避免干扰）

三、实战：claude code +openSpec

1、四份知识的分工（一图速览）

                    ┌─────────────────────────┐
                    │       CLAUDE.md         │  ← 唯一"常驻 + 总入口"
                    │   (根目录)              │    会话一启动就加载
                    │  项目简介/模块表/构建    │
                    │  + 两张"指路表":        │
                    │   · 规范 → .claude/rules/│
                    │   · 领域 → .claude/skills/│
                    └───────────┬─────────────┘
                                │ 它本身不含细节，只负责"把 AI 支去对的地方"
            ┌───────────────────┼────────────────────┐
            ▼                   ▼                    ▼
   ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
   │  .claude/rules/ │ │  .claude/skills/ │ │ openspec/config.yaml│
   │  编码规范.md     │ │  route-rule/     │ │  (schema:spec-driven)│
   │  命名约定.md     │ │  policy-statistics│ │                     │
   ├─────────────────┤ ├──────────────────┤ ├─────────────────────┤
   │ 性质: 代码硬约束 │ │ 性质: 业务地图    │ │ 性质: 产物文档规范   │
   │ 管: 怎么写代码   │ │ 管: 领域是什么    │ │ 管: change 怎么写    │
   │ (注解/异常/命名) │ │ (SKILL+L1~L5分层) │ │ (proposal/design/    │
   │                 │ │                  │ │  tasks/review 规则)  │
   │ 时机: 写代码时   │ │ 时机: 聊到该领域  │ │ 时机: 仅走openspec时  │
   │      常参考      │ │ 自动触发(渐进加载) │ │  生成产物文档时       │
   └─────────────────┘ └──────────────────┘ └─────────────────────┘
        HOW(代码)          WHAT(业务)            HOW(产物文档)

2、逐份详解

1）CLAUDE.md（根目录）— 枢纽，只指路不存细节

• 性质：会话启动即自动加载的常驻上下文，是整个体系唯一的入口。
• 管什么：项目简介、技术栈、七个模块的职责表、构建命令。
• 关键作用：内含两张”指路表”——
  • 「编码规范」一节 → 指向 .claude/rules/
  • 「领域知识库（Skill）」一节 → 列出 route-rule / policy-statistics 两个 skill 及其触发条件。
    • 注意：这张表是给人读的导航，不是 skill 自动加载的开关——
• 不该放进它的东西：具体的编码细则、领域业务细节、产物模板——这些各有归属，CLAUDE.md 只负责把人/AI 支到对的地方。

2） .claude/rules/ — 代码硬约束（HOW：怎么写代码）

• 文件：编码规范.md、命名约定.md
• 性质：写代码时的强制约定，是”代码长什么样”的标准。
• 管什么：
  • 注解：JSF 接口必标 @LogIndex、核心链路标 @Ump、DUCC 配置用 @LafValue
  • 异常：AppRuntimeException + ErrorCodeEnum
  • 工具：JSON 用 com.alibaba.fastjson.JSON、字符串用 StringUtils、集合用 CollectionUtils
  • 命名：类后缀、方法前缀、Redis Key 模式
• 何时激活：进入”写/改代码”动作时。

3） .claude/skills/领域skill — 业务地图（WHAT：领域是什么）

• 性质：领域知识库，原生 Skill，会根据对话场景自动加载，无需手动触发。

• 自动识别的真正来源：每个 SKILL.md frontmatter 的 name + description 字段。Claude Code 启动时扫描 .claude/skills/*/SKILL.md，把这两个字段注入上下文当作”何时该用我”的信号；用户聊到匹配场景即自动加载。

  • 这一步独立于 CLAUDE.md——CLAUDE.md 那张表不写，识别照样发生；决定识别准不准的，是 description 写得好不好。

• 结构：每个 skill 一份 SKILL.md（领域全貌）+ references/L1~L5 五层渐进式细节：

  层	认知目标	路径
  L1 业务概念	这个领域做什么业务	references/L1_Domain/
  L2 业务流程	业务怎么流转、有哪些状态	references/L2_Process/
  L3 服务设计	代码怎么组织、职责怎么分	references/L3_Service/
  L4 接口契约	接口/MQ/Job 怎么调	references/L4_API/
  L5 数据存储	数据存哪、怎么查	references/L5_Storage/

• 加载策略（关键）：SKILL.md 本身已足够回答概览问题；仅当需要深入时按需只读对应层，不要一次性加载全部 references。不确定深度时从 L2 起步。涉及改代码时，先查 SKILL.md 第四节「代码→知识映射（反向索引）」用类名定位关联层级。

4）openspec/config.yaml — 产物文档规范（HOW：change 怎么写）

• 性质：schema: spec-driven，规定走 OpenSpec 流程时各类产物文档怎么写。注意它管的是文档，不是代码。

• 管什么（rules 段，按产物类型分）：

  • proposal：必含背景/目标/非目标/方案概要/影响范围；
  • design：必含当前/目标架构、接口设计(读写分离)、数据模型、缓存设计、异常处理
  • tasks：必须遵循分层依赖顺序 domain/common → dao → manager → service → rpc → web；禁止跨层调用
  • change：关联 design 编号、按模块列受影响文件、标变更类型、含回归测试要点

3、一次完整协作流程

每份知识在不同阶段被激活，串起来是这样：

 阶段              激活哪份知识                            产出
──────────────────────────────────────────────────────────────────────
①会话启动      CLAUDE.md(自动常驻)                      知道项目长啥样、
               └─读到"指路表"                            去哪找规范和领域

②聊需求/定位   触发 route-rule SKILL.md(领域全貌)        知道要动 findSupplier、
 (explore)     └─只读够用的那层，默认从L2；改代码先查      AbstractRouteRuleService、
                 SKILL第四节"代码→知识映射"反向索引       RouteRuleV0~V2、缓存刷新
                 ⚠跨到赔付率→再补 policy-statistics

③写提案/设计   openspec/config.yaml 的 rules 段生效       proposal.md(800字内/标模块/
 (propose/new) ·proposal: 必标模块/JSF契约/缓存/MQ影响    JSF契约/缓存/MQ)
               ·design: "新增路由策略必须继承            design.md(继承抽象类的扩展点)
                 AbstractRouteRuleService,实现           tasks.md(按 domain→dao→manager
                 doCreateRouteRelation()" ←直接规定       →service→rpc→web 分层排序)
                 了你这个需求的设计骨架!

④写代码        .claude/rules/ 硬约束 + 领域 L3/L4/L5      代码:策略类标@Ump、Redis走
 (apply)       ·命名:RouteRuleV3? find/refresh前缀       RedisService、Key用枚举、
               ·注解:JSF标@LogIndex、核心标@Ump          异常用AppRuntimeException
               ·config.yaml review段同时是验收清单

⑤验证/归档     config.yaml review 段 + 领域状态机         对照检查→delta合入 specs/
 (verify/      ·检查分层/Key枚举/@Ump/MapStruct/异常       (注:目前 specs/ 为空，
  archive)     ·领域知识里的状态流转校验生效顺序           这会是第一次产生主 spec)

1）工作流

/openspec-explore 给你一个需求，比如我要增加一个路由策略，你的工作流是什么 ，简单说下你的工作流就行了，不用你详细介绍，                                            

⏺ 以"新增一个路由策略"为例，我的工作流大致是这样：

  1. 探索 (现在这步)        →  搞清楚需求：新策略的分配逻辑是什么？
     /openspec-explore         触发条件、与 V0~V2 现有策略的关系、降级兜底
                               ──> 不写代码，只对齐问题

  2. 提案 (Proposal)        →  落成 OpenSpec change：为什么做、范围、影响面
     /openspec-new 或 ff        specs(改了什么规则) + design(策略选型/扩展点)
                                                    + tasks(拆解到可执行)

  3. 实现 (Apply)           →  按 tasks 逐条改代码
     /openspec-apply           参照 route-rule 领域：findSupplier 分配主链路、
     /openspec-explore         触发条件、与 V0~V2 现有策略的关系、降级兜底
                               ──> 不写代码，只对齐问题

  2. 提案 (Proposal)        →  落成 OpenSpec change：为什么做、范围、影响面
     /openspec-new 或 ff        specs(改了什么规则) + design(策略选型/扩展点)
                                                    + tasks(拆解到可执行)

  3. 实现 (Apply)           →  按 tasks 逐条改代码
     /openspec-apply           参照 route-rule 领域：findSupplier 分配主链路、
                               RouteRuleVx 策略类、缓存刷新、规则状态流转

  4. 验证 (Verify)          →  跑测试 + 对照 change 检查实现是否完整一致
     /openspec-verify

  5. 归档 (Archive)         →  把 delta spec 合入主 spec，change 收尾
     /openspec-archive

  核心就一句：先把"要改哪条规则、怎么扩展策略"想清楚并写成 change，再动代码，最后验证归档。

  要不要我现在就以你脑子里那个具体策略为例，往下走第 1 步——聊聊它的分配逻辑和触发条件？

✻ Sautéed for 19s

2）定位代码

需求关键词:"路由策略"
          │
          ▼
  ① 先读领域知识库 (这个项目最快的入口)
     route-rule 这个 Skill 的 SKILL.md = 领域全貌
     └─ 它直接告诉我:分配主链路 findSupplier、策略类 RouteRuleV0~V2、
        规则生效定时任务、缓存刷新 —— 不用我瞎找
          │
          ▼
  ② 命名约定兜底 (.claude/rules/命名约定.md)
     知道"策略选型"→ 找 RouteRuleVx;"查找/路由"→ find{对象};
     "刷新缓存"→ refresh{对象}ToCache
     └─ 命名规律让我能猜到符号名,直接 grep
          │
          ▼
  ③ grep/glob 验证 + 找全引用
     grep "RouteRuleV2" / "findSupplier" → 定位实现 + 所有调用方
          │
          ▼
  ④ 需要广度时才上 Explore agent
     比如"这个策略在哪些链路被复用""降级兜底在哪" 这种跨文件的

  所以核心顺序是:先 Skill 拿领域地图 → 再用命名约定缩小符号范围 → grep 精确定位 → 真不清楚才 Explore 广搜。

  这个项目的特殊性在于第①步——route-rule / policy-statistics 
  两个 Skill 已经把"概念→流程→服务→接口→存储"分好层了,所以我定位时不是从零
  grep,而是先看领域知识库的索引,省掉大量盲找。

四、AI Coding Agent 的 Token 成本控制

https://news.qq.com/rain/a/20260615A07IIV00?suid=&media_id=

1、 先搞懂你的 Token 花在了哪里

很多人优化 Token 第一反应是 “把问题写短点”，但这往往抓错了重点 —— 在 AI Coding Agent 中，你输入的提问通常只占单次请求 Token 的 1% 不到，真正的成本大头是系统自动携带的上下文。

1）单次请求的 Token 构成

总成本 ≈ 固定前缀 + 会话历史 + 运行时检索 + 工具往返 + 模型输出

这里面有三层东西：

• 固定前缀：System Prompt、Skill 定义、Tool / MCP 定义、稳定背景文档
• 半固定上下文：项目说明、Repo Map、Memory、长期约束
• 动态上下文：聊天历史、代码片段、检索结果、工具返回、你这轮新问题

2）“记忆” 的真相：每轮都在重复搬运

大模型本身是无状态的，你觉得 “它记得之前的对话”，本质是 Agent 层在每一轮请求前，都会把历史对话、规则、工具、代码重新拼接好，再发给模型。

这带来三个直接的成本影响：

1. 会话越长，后续每一轮越贵。因为历史不是“存在那里等模型自己想起来”，而是很可能在每轮都要重新带过去。
2. 工具越多，常驻的定义文本越重，每轮请求都要携带
3. 工具调用会形成多轮链路：读上下文→调用工具→返回结果→结果回上下文→再推理，一次任务对应多次计费

3）五类成本，不止是输入字数

不要把 Token 简单等同于 “字数”，Agent 场景至少有五类开销：

最容易被低估的，往往是后两项。

1. 工具往返成本的问题在于：你以为自己只是“让它查个文件”，但模型其实经历的是：理解工具定义 → 生成参数 → 接收返回值 → 再结合返回值继续思考。对人来说只是一个动作，对系统来说可能是多段上下文交换。

2. 重试成本更隐蔽。真正烧钱的，常常不是第一次调用太长，而是第一次不合格——格式不对、结构错、找错文件、推理过度——于是又来一轮。

4）Prompt Cache：所有优化的基础

Prompt Cache 不是缓存答案，而是缓存稳定前缀的处理结果—— 如果两次请求的前半段内容一致，服务端就不需要重复处理这部分内容，直接复用计算结果。

最容易被缓存的内容：System Prompt、工具定义、Skill 定义、长文档背景、固定的 few-shot 示例。

三个关键结论：

1. 第一，Prompt Cache 省的不是首次成本，而是重复成本。 第一次发送长前缀时，通常还是要正常付费；价值在第二次、第三次、后续很多次复用时才会体现出来。

2. 第二，缓存不是“写短”，而是“写稳”。 你天天改系统提示词、天天调 Skill Prompt，那缓存理论上存在，实践里也很难命中。

3. 第三，缓存优化和上下文治理是一回事。 减少前缀抖动、把稳定内容前置、把变化内容后置，本质都在提升“可复用比例”。

5）五层优化框架

成本优化是一条从易到难、从低成本到高投入的升级路径：

2、使用习惯：最便宜也是最被低估的优化

这一层不需要任何工程改造，只需要调整使用习惯，往往就能拿到第一波最大的成本收益。

1）一个 Session，一件事

很多人把 AI Agent 当成永不关闭的长会话：上午修 Bug，下午写文档，晚上聊架构，第二天接着来。

做法：修 Bug 开一个会话，做重构开一个会话，写文档、查问题分别开新会话，不要在一个窗口里混着做不同的事。

原理：会话越长，继承的历史越多，每一轮的基础成本越高。按主题拆分会话，是最便宜的上下文管理方式。

2）长会话不压缩，就是负债

很多人舍不得清历史，觉得“越完整越稳”。模型不需要你的完整试错过程。它需要的是：现在要干什么

做法：对话轮次变多后，使用 /compact 指令压缩上下文，只保留当前任务的核心状态（目标、已完成内容、卡点、下一步）。

原理：模型不需要完整的试错过程，未压缩的长对话是负债，会让后续每一轮都背着越来越重的历史包袱。

3）长期信息外置，不把聊天当数据库

很多人把背景、决策、约束全挂在会话里，指望 Agent 一路记到底，结果会话越来越长，状态越来越难提炼，成本越来越高。

做法：把项目规则、决策结论、待办清单、长期约束等内容，放到项目文档、Summary 文件、Repo Map 里，不要全堆在会话里。

原理：会话只应该承载 “当前工作状态”，用会话保存全部项目历史，只会让上下文越来越臃肿，关键信息也难提取。

4）少说废话，也是省 Token

很多人优化只盯输入，忘了输出一样贵。编码场景最浪费的回答不是“错”，是“废”：先复述一遍问题，再讲一段众所周知的背景，然后一堆礼貌性铺垫，最后才给结论。

做法：只需要 diff、步骤、结论、表格、JSON 时，直接指令要求，比如加上 “直接给结论，不要复述问题，必要时再展开”。

原理：同时节省输出 Token 和重试成本 —— 输出更短，且结果更可用，减少修正轮次。

5）Skill 按需加载，不盲目堆砌

Skill 有价值，但也背成本。每个 Skill 都带着 Description、Instructions、Examples、触发逻辑。如果常驻，就会进上下文。

做法：只把高频、通用、稳定的 Skill 设为常驻，低频、长说明、低复用的 Skill 按需触发，不要全量挂载。

原理：每个 Skill 都带着说明、指令、示例，常驻就会每轮都进入上下文，和后端服务治理同理，常驻能力要少而精。

6）MCP 精简治理，只留高频工具

MCP 的最大诱惑是让 Agent “什么都能接”。但从成本看，每多一个 MCP，就多一份 Tool Definition、多一层选择成本。

做法：清点已安装的 MCP 工具，卸载低频使用的，只保留日常高频用到的 2-3 个。

原理：每多一个 MCP，就多一份工具定义，同时会增大模型的选择空间，提升错误调用概率和决策成本。

7） 优先 CLI，少用 MCP

已有成熟命令链路时，不要为了看起来高级而过度工具化。

做法：已有成熟命令行工具的操作（git、kubectl、docker 等），优先让 Agent 走 CLI 命令，不要为了 “高级” 强行套 MCP。

原理：CLI 不需要额外携带一整套工具说明文档，Token 消耗远低于 MCP。针对内部研发平台，也可优先选用专为 Agent 优化的 CLI 工具（如 tapd-ai-cli、gongfeng-cli）。

8）引用文件带完整路径，省去搜索开销

这是一个极其容易忽视的小习惯，但省的 Token 实实在在。

做法：引用文件时用 @完整路径，比如 看一下 @src/config/config.go 的问题，不要只写文件名。

原理：只写文件名时，Agent 需要先全局搜索定位文件，甚至可能多次确认，搜索过程的工具调用和返回结果全部计入 Token。完整路径可以让 Agent 直接读取，省去整条搜索链路。

9）指令一次说清，避免碎片化沟通

越具体、越完整的指令，浪费的轮次越少。这和程序员提 Issue 的逻辑是一样的：把背景、期望、验收条件都写清楚，沟通成本才不会比写代码还贵。

做法：一次把任务目标、背景、要求说完整，比如 “看 @src/order/service.go 的 CreateOrder 函数，找出潜在 bug，修复，并为修复后的函数写单测”，不要拆成多轮碎片化提问。

原理：每一轮对话都要重新组装上下文、带入历史，碎片化对话的成本往往是一次完整表达的好几倍。指令越完整，浪费的轮次越少。

3、进阶级优化：模型路由，别让贵模型干便宜活

习惯优化做好后，下一步收益最高的是模型路由 —— 不要所有任务都默认用最强、最贵的模型，按任务复杂度匹配档位。

1）核心原则：匹配优先，不是便宜优先

• 复杂任务 → 强模型
• 简单任务 → 便宜模型
• 重复任务 → 稳定模型

2）级联路由： 先过便宜模型，再升级

不要一上来就用最贵模型，可以设计升级链路：

1. 先用便宜模型做分类、初筛、摘要
2. 判断任务复杂度，确有必要再升级到强模型

比如先让便宜模型分类 PR 风险、做代码摘要，再交给强模型做深度推理，既省钱又能让贵模型的算力花在刀刃上。

3）调节推理预算，匹配任务深度

不是所有任务都要深度思考，也不是所有任务都要长答案。 高推理档位做简单任务，本质是 “拿推土机扫地”，属于典型算力浪费。

现在很多模型提供成本旋钮，它们影响的，其实是同一组东西：想多深、答多长、花多少钱

• reasoning effort
• thinking budget
• verbosity
• max output tokens

4）Skill / Agent / Command 都应该绑定模型

不要只靠人工切换模型，要把路由规则固化到执行单元里：

• Skill 绑定模型：写单测、生成 commit、格式化这类固定任务，在 Skill 定义里直接指定便宜模型

• Agent 绑定模型：规划 Agent 用中高档，编码 Agent 用中档 / 便宜，评审 Agent 用强模型

• 命令绑定模型：斜杠命令（如 /commit、/gen-ut）预设对应模型

4、代码图谱，让 AI 告别盲搜

项目越大，AI 越容易陷入 “搜索→读文件→发现漏了→再搜索” 的盲搜循环，这个过程会消耗大量工具调用和上下文 Token。代码图谱的价值，就是让 AI 在动手读文件之前，就精准知道该读哪里。

5、架构级优化：多 Agent 协作，拆分上下文边界

单 Agent 处理复杂任务时，会把规划、编码、测试、评审的所有上下文都塞进一个会话，越跑越臃肿。多 Agent 协作的核心，是拆分任务边界，让每个 Agent 只携带和当前步骤相关的内容。

1）subagent：轻量级任务隔离

优势：子任务独立上下文，不继承主会话的全部历史，且可以单独绑定便宜模型，进一步降本。

典型分工模式：

• 主会话：负责规划、决策、汇总（强模型）
• subagent A：影响范围分析（只看图谱，不读源码）
• subagent B：代码实现（只看相关文件）
• subagent C：测试执行 + 报告生成

2）Orchestrator-Worker 模式

这是更系统化的多 Agent 架构，核心是把一个臃肿的长任务拆成流水线：

• Orchestrator（协调器）：负责任务拆解、调度、汇总，不读大量文件，只用强模型做决策

• Worker（执行器）：每个 Worker 只做一件具体事，只看自己需要的上下文，用便宜模型执行

降本原理：单 Agent 要全程携带所有背景，而每个 Worker 只带当前步骤的相关内容，单轮成本可以压缩 5-10 倍。

3）多 Agent 数据流转：文件共享替代会话传递

上下文隔离后，Agent 之间通过共享外置文件传递信息，而不是靠会话历史：

1. Agent A 完成工作，把结果写入 .agent/xxx.json
2. Agent B 读取该文件获取信息，完成自己的任务后写入新文件
3. Orchestrator 只读取进度和结果文件，不需要回放任何历史

四个设计原则：

1. 输出结构化：用 JSON 格式传递结果，比自然语言更紧凑、无歧义，下游只读取需要的字段
2. 进度文件追踪：用 progress.json 统一管理任务状态、步骤、完成情况，协调器一眼掌握全局
3. 上下文精准裁剪：给 Worker 的指令明确指定 “只读哪些文件”，不要让 Worker 自由探索
4. 临时文件及时清理：任务完成后归档或删除 .agent/ 目录，避免污染新任务

4）并行执行：时间和成本双下降

• 适合并行：不同模块的 Bug 修复、代码 + 测试 + 文档生成、无依赖的多文件重构、影响分析 + 方案设计

• 不适合并行：有顺序依赖的步骤、修改同一个文件的任务、依赖上一步输出的任务