Thariq 的 Claude Code 四篇长文总览
这 4 篇不是 4 个孤立话题，而是一条连续金线：先解决 agent 怎么跑得起，再解决能力怎么组织，最后讨论组织如何被这种新交付方式改写。
怎么读这张图
- 左到右：从系统约束到能力组织
- 上到下：从 Claude Code 产品机制到人类团队分工
- 中央金线：实现越来越便宜，判断、评审与上下文治理越来越贵
四篇合起来真正讲的是一件事
prompt caching让长会话 agent 在成本和延迟上可持续action space与skills决定能力如何扩展而不把上下文搞崩- 当 prototype 变得极便宜，组织瓶颈自然从 implementation 迁移到 review、intent 与 system thinking
先别谈能力，先谈物理
Claude Code 先要解决两个硬约束：
- 长会话太贵：必须保护稳定前缀
- 工具菜单太重：每加一个常驻能力，都在增加 token 税与选择负担
所以它不是先问“还能不能再加功能”，而是先问“这个功能会不会破坏 cache-friendly 的前缀结构”。
Prompt Caching 给出的 5 条硬规则
static first, dynamic last- 用 message 追加，不重写前缀
- 不在 session 中途切模型 / 换工具
- plan mode 要做成状态转换，而不是换工具集
- fork / compaction 必须复用父会话前缀
这篇文章真正的判断是：缓存不是 infra 小优化，而是 agent 产品的底层宪法。
两对核心张力
- 更多工具 vs 更高缓存命中
- 更多结构化能力 vs 更重的选择负担
Claude Code 的解法不是二选一，而是：保持少量稳定底座，把复杂能力延迟到真正需要时再展开。
Action Space 的设计法
Seeing like an Agent 给出的关键方法：
- 工具形状要匹配模型能力，不匹配工程师想象
- plain text 不稳时，才把能力工具化
- 模型变强后，旧脚手架要及时拆掉
- 能让模型自己建上下文，就别替它塞满上下文
所以 AskUserQuestion、Task Tool、Grep 都不是“功能更多”，而是更贴合模型能力曲线。
Skills 真正是什么
Skills 不是 markdown，而是一个可探索的目录：
- gotchas
- references
- examples
- scripts
- hooks
- memory
它的价值不是“又多了一个说明书”，而是把知识 + 工作流 + 脚本打包成 progressive disclosure。Claude 不必一开始全读，只要在需要时递归发现。
不必什么都做成新 tool
Claude Code Guide subagent 是关键例子：
- 不把全部 docs 塞进 system prompt
- 不再给主 agent 增加一个常驻工具
- 而是让主 agent 在特定问题上调用一个专职检索 / 压缩 docs 的 subagent
这说明：扩 action space，不等于膨胀主菜单。
第二层的总原则
稳定前缀保护的是成本与速度； 渐进披露保护的是上下文质量； 结构化工具与 subagent 保护的是交互稳定性； skills / scripts / hooks 保护的是可复用工作流。
四者叠加，Claude Code 才从“会写代码的模型”变成“可持续交付的工作系统”。
Skills 文章里最值得重投的，不是知识型，而是验证型
Anthropic 明示高价值 skill 类型集中在：
- product verification
- code quality / review
- runbooks
- deployment / operations
原因很简单：agent 时代真正稀缺的不是第一版代码，而是“它真的靠谱吗、能不能进入生产”。
组织瓶颈开始迁移
第四篇把后果说透了：
- 老的
PRD -> mock -> code瀑布死了 - prototype abundance 成了新常态
- 瓶颈从 implementation 迁到 review
现在最稀缺的不是“把东西做出来”，而是判断：
- 值不值得做
- 做得对不对
- 能不能进生产
新分工：Builder vs Reviewer
Builder：能用 coding agents 把想法快速变成可运行原型Reviewer：能从 engineering / product / design 三个维度审查“它是否足够好”
这和 Claude Code 自己的演化完全同构： 先让模型能做，再想办法让系统能评、能纠、能收敛。
Generalist 更值钱，Specialist 门槛更高
沟通成本没消失，只是从“跨职能协作写代码”变成“跨职能协作判断代码”。
所以：
- 会一点 design + product + engineering 的 builder 杠杆更大
- 只做单一专长的人仍然有价值，但必须在 review / judgment 上非常强
PRD 没死，老 PRD 流水线死了
“先写规格再交付”的老流程死了； “为 prototype 提供 intent 和 review 依据”的 companion document 反而更重要。
未来更像：
idea -> prototype -> review packet
而不是：
idea -> 长文档 -> 设计图 -> 开发排期
四篇合起来，真正改写的是同一件事
prompt caching让 agent 产品在成本和延迟上可持续action space / skills决定 agent 如何在不爆 context 的前提下扩能力verification / review技术栈决定这些原型能否进入生产- 于是组织价值从“谁会写更多代码”转向“谁能更快做对判断、组织上下文、完成评审闭环”
对这个 Obsidian 库最直接的 5 个启发
- 把
AGENTS.md / SOUL / USER / TOOLS / memory看成稳定前缀，而不是随手可改的提示词堆 - 高频工作流优先沉淀成
skills + scripts + gotchas，而不是长篇说明文 - 新增 skill / 工具前先问：plain text、搜索、现有 skill、subagent 能不能解决
- 把“验证”当成一级能力建设对象：不仅要能生成，还要能自查、留痕、复盘
- 以后写产品或工作流笔记时，更适合写
review companion / intent companion，而不是老式 PRD
本库已有的二次沉淀入口
如果想继续下钻，可以从这里往下：
- prompt caching 的中文重写
- action space 的中文拆解
- skills 的单篇 canvas
也就是说，这张总图负责“总结构”，现有笔记负责“细展开”。
Lessons from Building Claude Code: How We Use Skills
这篇文章的核心价值：把“Skill 只是 markdown”这个误解打掉，重新把 Skill 看成一种可组合的 agent extension point：它可以带脚本、数据、模板、hooks、记忆与分发机制。
文章在回答什么
- 什么样的 skill 值得做
- 好 skill 的秘密是什么
- 什么时候该共享给别人
- 怎么避免做出坏 skill
一个关键纠偏
Skill 不只是 markdown 文件。
更准确地说，它是一个文件夹：
- 可以带脚本
- 可以带 assets
- 可以带数据
- 可以带 hooks
- 可以让 agent 逐步探索和组合
作者的总判断
最好的 skills 通常：
- 类型清晰
- 目标明确
- 能补 Claude 的短板
- 能复用
- 能随着失败案例持续迭代
这篇文章的底层视角
Skill 本质上是一个 context + tooling + workflow 的封装单元。
它不是把知识堆给模型，而是把：
- 正确的上下文入口
- 正确的脚本 / 模板 / hooks
- 正确的触发时机 一起交给模型。
1. Library & API Reference
教 Claude 正确使用某个库、CLI、SDK。
典型内容：
- 示例代码
- 函数签名
- footguns / edge cases
- 组织内部约定
2. Product Verification
告诉 Claude 怎么验证产出真的能工作。
常与 Playwright、tmux 搭配，重点是：
- 可执行验证脚本
- 程序化断言
- 录屏 / 留证据
作者明确说：这是非常值得重投入的一类。
3. Data Fetching & Analysis
连接数据仓、监控栈、仪表盘。
本质是把：
- 凭据
- 数据源标识
- 常用查询模式
- 指标解释 封装成可复用工作流
4. Business Process & Team Automation
把重复团队流程压成一个命令。
例如：
- standup
- 建 ticket
- weekly recap
这类 skill 通常不复杂，但非常省时间。
5. Code Scaffolding & Templates
生成你组织里的标准脚手架。
适合处理：
- 模板化代码
- 自然语言需求
- 单纯脚本难覆盖的规范
6. Code Quality & Review
把代码质量和审查策略写进 skill。
例如：
- code style
- testing practices
- adversarial review
可和 hooks / GitHub Action 联动。
7. CI/CD & Deployment
帮助拉代码、发代码、部署代码。
典型是多步流程： build -> test -> smoke -> rollout -> compare -> rollback
8. Runbooks
给一个症状，按固定调查路径跑多工具诊断，再产出结构化报告。
适合：
- oncall
- alert triage
- request id 追踪
- 常见故障排查
9. Infrastructure Operations
把高风险运维流程加上 guardrails。
适合：
- 清理孤儿资源
- 依赖治理
- 成本调查
- 带确认与 soak period 的清理
9 类 Skill 的共同点
它们本质上都不是“写给人看的说明书”，而是“写给模型执行的工作单元”。
区别只在于：
- 补知识
- 补验证
- 补数据入口
- 补流程编排
- 补安全边界
作者的隐含建议
好的 skill 最好清晰落在某一类里。
一旦一个 skill 横跨太多类型，往往会：
- 触发条件模糊
- 内容臃肿
- 维护困难
- 复用性下降
1. 不要陈述显而易见的事
Claude 本来就懂很多编码常识。
Skill 应该优先写那些会把模型拉出默认思路的信息，而不是重复基础知识。
2. Build a Gotchas Section
最高信号密度的内容往往是 gotchas。
也就是：
- Claude 常犯什么错
- 这类工作里最容易踩什么坑
- 哪些边界条件必须提前说
3. 把文件系统当作 context engineering
Skill 是文件夹，不是单文件。
可以用：
references/examples/assets/scripts/做 progressive disclosure
4. Avoid Railroading Claude
别把 skill 写成死流程。
原则是：
- 给足信息
- 不要过度规定每一步
- 保留模型根据上下文自适应的空间
5. 认真设计 Setup
有些 skill 需要用户上下文，例如频道、环境、目标系统。
推荐把 setup 信息放在 skill 目录的 config.json，未配置时再问用户。
6. Description 字段是写给模型的
它不是“摘要”，而是触发描述。
Claude 会扫全部 skill 的 description 来判断： “这个请求有没有对应的 skill？”
7. Skill 也可以有记忆
可以存：
- append-only log
- JSON
- SQLite
但升级 skill 时目录内数据可能被删，所以稳定数据建议放 ${CLAUDE_PLUGIN_DATA}。
8. 把脚本和代码交给 Claude
给 helper functions、脚本库、模板后，Claude 的 token 就能花在“组合与决策”上，而不是重复造 boilerplate。
1. 两种分发方式
- 跟 repo 一起放进
./.claude/skills - 做成 plugin，进入 marketplace
前者简单，后者更适合规模化分发
2. Repo 分发的代价
每多一个 checked-in skill，都会给模型多一点上下文负担。
小团队问题不大，规模大了就需要更精细的安装与裁剪。
3. Marketplace 的价值
让技能变成按需安装，而不是全量塞给每个仓库。
这样团队可以：
- 更好分发
- 更好治理
- 更少上下文污染
4. 不要搞中心化审批
Anthropic 的做法是先有机扩散，再在 skill 有 traction 后进入 marketplace。
5. 需要策展
坏 skill 和重复 skill 很容易出现。
所以在正式发布前，必须有某种 curation 机制。
6. Skills 可以互相组合
虽然市场和依赖管理还不完善，但可以直接在 skill 里引用其他 skill 名称，让模型在安装后自行调用。
7. 要测量 skill
Anthropic 用 PreToolUse hook 记录使用情况，以识别：
- 哪些 skill 热门
- 哪些 undertrigger
- 哪些值得继续投资
A. 先别从“我想写个 skill”开始
更好的起点是：
- Claude 在什么地方反复犯错
- 哪个流程反复重复
- 哪个验证步骤总被忽略
- 哪种查询总靠老人记忆
B. 每个 Skill 的最小骨架
- 清晰类型
- 真正有用的 description
- gotchas
- references / examples / scripts
- 必要的 setup config
- 可选的记忆与 hooks
C. 优先级建议
如果资源有限，最值得先做的通常是：
- Product Verification
- Code Quality & Review
- Runbooks
- Data Fetching & Analysis
因为这些直接影响结果正确性与排障效率。
D. 团队 rollout 路线
- 先在 repo 内试验
- 用 usage / trigger 数据看 traction
- 逐步清理重复 skill
- 成熟后再进 marketplace
这是比一开始“大一统平台化”更稳的路径。
E. 这篇文章真正想让你记住的 3 件事
- Skill 是文件夹，不是 markdown。
- Gotchas、scripts、progressive disclosure 往往比长篇说明更有用。
- Skill 体系也需要分发、策展和度量。
9. On Demand Hooks
Skill 可以带只在调用时激活、并持续到会话结束的 hooks。
适合高 opinionated、但不该常开的约束：
- 阻止危险命令
- 限定编辑目录
- 进入 prod / debug 模式时增加额外护栏