Claude Code Best Practice
Claude Code 最佳实践

Practical patterns for Claude Claude Code

github.com/shanraisshan/claude-code-best-practice
Shayan Rais

Shayan Rais
夏扬·雷斯

Software Architect at (软件架构师 @ disrupt.com

Education
FAST NUCES logo
Master’s in Computer Science
FAST NUCES — 2019
NED University logo
Bachelor’s in Computer Information Systems
NED University — 2014
Claude mascot
Contributions
Creator of claude-code-best-practice
The most starred 🇵🇰 Pakistani AI repo GitHub with almost 50,000 stars ★
claude-code-best-practice GitHub stars growth

🚨 Problem Statement 问题陈述

Fetch weather of Karachi (获取卡拉奇天气)

  1. Single source of truth (单一事实来源)
  2. Repetitively (可重复执行)

By solving this problem statement, we’ll learn different concepts of agentic engineering along the way.
通过解决这个问题，我们将学习 智能体工程 的不同概念。

agentic engineering progressive disclosure orchestration dumb zone agentic workflows harness compaction context window ralph wiggum loop MCP hooks context rot prompt engineering AI slop inference hallucination context bloat one-shot prompting token burn vibe coding
scroll for glossary ↓

progressive disclosure — feeding the AI only what it needs right now, not everything upfront

orchestration — coordinating several AI agents like a conductor leads a band

dumb zone — the stretch where AI has too much context and starts thinking worse, not better

agentic workflows — AI that plans, acts, checks its work, and adapts — multi-step on its own

harness — the scaffolding around the model — files, terminal, tools — that turns a chatbot into a worker

compaction — auto-summarizing old chat so the AI keeps going without hitting its memory ceiling

context window — the AI’s working memory — how much it can “see” at once before older details fall off

ralph wiggum loop — when the AI repeats the same broken step in circles, like a confused kid who can’t stop

MCP — a universal adapter letting AI talk to your tools (GitHub, Slack, databases)

hooks — auto-triggers that run your rules before or after the AI does anything

context rot — quality decay as the conversation drags on and earlier details blur

prompt engineering — the craft of phrasing requests so the AI understands exactly what you mean

AI slop — low-effort, generic AI output that looks polished but says nothing

inference — the moment the model actually runs to produce an answer. Training is when the model learned (once, long ago). Inference is the model answering you, right now

hallucination — when AI confidently makes up facts that sound true but aren’t

context bloat — overstuffing the AI’s memory so it slows down and loses focus

one-shot prompting — giving the AI one example and asking it to follow the same pattern

token burn — wasting expensive AI “words” on unnecessary back-and-forth or bloated prompts

vibe coding — describing what you want in plain English and hoping the AI nails it

agentic engineering — building guardrails so AI acts like a reliable teammate, not a gamble

Difference between GPT and ChatGPT?
GPT 和 ChatGPT 的区别是什么？

discuss

Boris Cherny slides showing the spectrum of Claude Code usage styles
Boris Cherny (creator of Claude Code) — different teams use Claude Code completely differently.
There is no single “correct” way. But there are patterns worth understanding.

Source: Boris Cherny on X — tweet 1 · tweet 2 · tweet 3

What is Claude Code?
什么是 Claude Code？

Model (Brain 🧠 — e.g. Opus, GPT) + Harness (Body 💪 — e.g. tools, MCP, memory)
模型 (大脑) + 工具链 (身体)

A horse. A model.
一匹马。一个模型。

The model is the horse. Raw power, no direction.
模型就是那匹马。原始的力量，没有方向。

How an LLM generates text (autoregressive)
LLM 如何生成文本（自回归）

Animated diagram showing autoregressive generation: prompt feeds into LLM, which predicts one token, feeds it back, and repeats until the full answer is produced.
Each predicted token is appended to the input, then fed back into the LLM.
每个预测的 token 被追加到输入中，然后重新喂给 LLM。
Screenshot of the OpenAI tokenizer showing the sentence about BPE split into 32 tokens across 105 characters, with tabs for GPT-5.x, GPT-4, and GPT-3 tokenizers.

How an LLM tokenizes input
LLM 如何对输入进行分词

Animated diagram combining tokenization and autoregressive generation: the BPE-tokenized prompt feeds into the LLM, which generates the answer token-by-token using the same shared vocabulary.
BPE chops words into subword tokens — same color = same word, gray = punctuation.
BPE 将单词切分为子词 token — 同色=同词，灰色=标点。

What the LLM actually sees: integer token IDs
LLM 实际看到的是什么：整数 token ID

Animated diagram showing the 32 integer token IDs the model receives: e.g. 28133 for 'Does', 17554 for ' Chat', 162016 for 'GPT', 97481 for ' Claude'. Generated tokens are also shown as IDs. Vocab size V ≈ 200,000.
Notice the comma is always ID 11 — the same punctuation mark maps to the same integer, everywhere, every time.
注意逗号永远是 ID 11 — 同一个标点在任何地方、任何时候都映射到同一个整数。

💬 Models are stateless 模型是无状态的

User Model
“My name is Shayan.” ➜ to model
“Okay, your name is Shayan.” ➜ to user
“What is my name?” ➜ to model
“I don’t know your name — I have no memory of what you just said.” ➜ to user

Every turn is a fresh API call.
每一轮都是一次全新的 API 调用。

Memory only exists if the harness replays the transcript.
只有当工具链重放对话记录时，记忆才存在。

🦜 “Stochastic Parrots” 随机鹦鹉

Stochastic means random/probabilistic — models don’t know the answer, they sample from a probability distribution.
随机意味着概率性 — 模型不"知道"答案，它们从概率分布中采样。

Prompt:  “The sky is ___”

blue
62%
clear
14%
dark
8%
falling
0.3%

Each run the model samples — temperature controls how widely it samples.

stochastic sycophantic hallucinating stateless biased confident pattern-matching

Source: Bender, Gebru, McMillan-Major, Mitchell — On the Dangers of Stochastic Parrots (2021)

🌡️ Even temperature = 0 isn’t deterministic.
即使 temperature = 0 也不是确定性的

You set it to zero. You expect the same answer every time. You’re wrong.
你设为0。你期望每次得到相同答案。你错了。

The data point
Without fix
80
unique completions
out of 1,000 calls
→
With fix
1
unique completion
out of 1,000 calls

Qwen3-235B at temperature = 0 — first divergence at token 103 (“Queens, New York” vs “New York City”)

Why it happens

Server load varies → batch size varies → kernel reductions reorder → numerics shift. Not GPU randomness — arithmetic order.

The fix

Batch-invariant kernels → consistent reduction order → identical numerics every run.

Determinism is engineered in — at every layer.

Source: Thinking Machines — Defeating Nondeterminism in LLM Inference (2025)

🧠 Models — e.g. Opus, GPT, Gemini
模型 — 例如 Opus, GPT, Gemini

✅ Can answer (可以回答)

“What is the capital of Japan?”

“When did Pakistan gain independence?”

“Who wrote Romeo and Juliet?”

❌ Can’t answer (无法回答)

“Who won yesterday’s match?”

“What’s today’s USD → PKR rate?”

“What did Anthropic release yesterday?”

Every model — no matter how new — has a knowledge cut-off. Events after that date simply do not exist inside the model.
每个模型 — 无论多新 — 都有知识截止日期。该日期之后的事件在模型中根本不存在。

Opus 4.7 — Anthropic

Knowledge cut-off: January 2026

Released 2026-04-17

GPT-5.5 — OpenAI

Knowledge cut-off: December 1, 2025

Released 2026-04-23 — brand-new, but still has a cut-off.

Gemini 3.1 Pro — Google

Knowledge cut-off: January 2025

Released 2026-02-19

🧠 Limitations 局限性

The raw model has no real-time access — no internet, no files, no clock.
原始模型没有实时访问能力 — 没有互联网、没有文件、没有时钟。

Anthropic Workbench screenshot showing the model refusing a real-time weather query
Control loop decides the next call Reins Tool allowlist constrains what it can do Bit Context management narrows what it sees Blinders Evaluator decides when done Driver State persistence carries work forward Traces

A horse harness. A model harness.
马的缰绳。模型的工具链。

The model is the horse. Raw power, no direction. The harness is everything else.
模型就是那匹马。原始的力量，没有方向。工具链是一切其他。

The origin is Old French harneis — gear, equipment, armor.
源自古法语 harneis — 装备、器具、盔甲。

⚡ Tool Calling — how the harness reaches the world
工具调用 — 工具链如何接触外部世界

Diagram showing how Claude sends a tool-call request to the harness, the harness executes it against real-world systems, and the result flows back into Claude’s context

In the diagram above:  Turn × 1  ·  Inference × 2

Turn — one round from the user’s view: you ask, the assistant answers. The entire flow above — your request, the assistant’s tool calls, and the final reply — is one turn.
回合 — 从用户视角看的一轮：你提问，助手回答。上面的整个流程 — 你的请求、助手的工具调用、最终回复 — 是一个回合。

Inference — one call to the language model. The model wakes up, reads the input it was given, writes a reply, then forgets everything. Every arrow touching the “Language Model” column above is a separate inference. One turn can contain many inferences.
推理 — 一次对语言模型的调用。模型醒来，读取给定的输入，写出回复，然后忘掉一切。上面每个触碰"Language Model"列的箭头都是一次独立的推理。一个回合可以包含多次推理。

Source: Anthropic — Claude Code in Action: What is a coding assistant?

💪 Harness — the body around the brain
工具链 — 大脑周围的身体

🧑‍💼

Agents — the specialists (智能体 — 专家)

A dedicated Claude worker — own context, tools, focus.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。

✅ fresh working memory per run 每次运行都有全新的工作记忆

🎯

Skills — the know-how (技能 — 知识)

What the specialist (or Claude) can actually do.
专家（或 Claude）实际能做什么。

✅ progressive disclosure — loaded on demand 渐进式披露 — 按需加载

📘

Workflows — the instruction manual (工作流 — 操作手册)

Repeatable step-by-step recipes — like an AC install guide.
可重复的逐步配方 — 就像空调安装指南。

✅ reproducible recipes 可复现的配方

📝

CLAUDE.md — your memory (你的记忆)

Knowledge you provide to the model.
你提供给模型的知识。

⚠️ 200-line problem 200行问题

💭

Context — the working memory (上下文 — 工作记忆)

What Claude holds in his head now — fresh every new chat session.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。

20% of 1M tokens

⚠️ dumb-zone problem 盲区问题

💪 Harness — the body around the brain
工具链 — 大脑周围的身体

✋

Tools — the hands (工具 — 手)

Built-in: Read, Edit, Bash, WebSearch.
内置：读取、编辑、Bash、网页搜索。

🔌

MCP — the adapters (适配器)

USB-C for AI — plug in external tools (databases, browsers, APIs).
AI 的 USB-C — 插入外部工具（数据库、浏览器、API）。

e.g. 👁️ Claude in Chrome

🛡️

Permissions — the guardrails (权限 — 护栏)

Allow / ask / deny for tool use.
对工具使用的允许 / 询问 / 拒绝。

🪝

Hooks — the reflexes (钩子 — 反射)

Deterministic scripts that fire on events.
事件触发时执行的确定性脚本。

📝

System Prompt — Claude’s memory (系统提示词 — Claude 的记忆)

Knowledge Anthropic bakes in.
Anthropic 内置的知识。

e.g. identity · tone · safety
例如：身份 · 语调 · 安全

✅ always on 始终开启

🎉 Yayyyyy! Problem solved with harness
耶！用工具链解决了问题

The harness reaches out via WebSearch and fetches a real answer from live sources.
工具链通过网页搜索从实时来源获取真实答案。

Claude Code using Web Search across AccuWeather, Weather25, and TimeAndDate to answer "what is the weather in Karachi?"
?

Really?
真的吗？

💪 Non-determinism — Doesn’t always use its tools
非确定性 — 不总是使用工具

Similar prompt — but this time the model decided not to use the tool.
相似的提示词 — 但这一次模型决定不使用工具。

Claude Code refusing to check live weather and asking permission to use WebFetch

💪 Non-determinism — Tools can fail
非确定性 — 工具可能失败

The model first tried one source — it failed (403) — so it fell back to another.
模型先尝试了一个来源 — 它失败了(403) — 于是回退到另一个。

Claude Code showing a 403 error from timeanddate.com and falling back to wttr.in

🚨 Problem Statement 问题陈述

  1. ❌ Single source of truth (单一事实来源)

    The model does not always follow the same path.
    模型并不总是遵循相同的路径。

  2. ❌ Repetitively (可重复性)

    Model sometimes failed/forgot to use the tool.
    模型有时失败/忘记使用工具。

Vibe Coding — Andrej Karpathy
氛围编码 — Andrej Karpathy

Andrej Karpathy's Feb 3 2025 tweet coining 'vibe coding' — 'fully give in to the vibes, embrace exponentials, and forget that the code even exists'

Andrej Karpathy — OpenAI founding team · former Director of AI at Tesla · founder of Eureka Labs.

Source: Andrej Karpathy on X (Feb 3, 2025)

Vibe Coding — Robert C. “Uncle Bob” Martin
氛围编码 — Robert C. "Uncle Bob" Martin

Robert C. Martin (Uncle Bob) in his video critiquing vibe coding

Uncle Bob warns that “vibe coding” — generating code from prompts without understanding what the LLM produces — is hazardous for novices.
Uncle Bob 警告说，"氛围编码" — 从提示词生成代码而不理解 LLM 产出什么 — 对新手来说是危险的。 LLMs are mathematical functions that predict the next most likely token via matrix multiplications, trained on internet text and GitHub code. They are powerful tools — but, as he puts it, “novices using power tools lose fingers.”

Robert C. “Uncle Bob” Martin — author of Clean Code · Clean Architecture · co-author of the Agile Manifesto.

Source: Robert C. Martin on X

Vibe Coding vs Agentic Engineering
氛围编码 vs 智能体工程

# Plain TodoApp (普通待办应用) todoapp/ backend/ main.py routes/ todos.py users.py models/ todo.py user.py tests/ test_todos.py frontend/ components/ TodoList.tsx Sidebar.tsx pages/ index.tsx todos.tsx lib/ api.ts
# With Claude Code Best Practices (使用 Claude Code 最佳实践) todoapp/ .claude/ # Claude Code 配置 agents/ # 自定义子智能体 skills/ # 领域知识 commands/ # 斜杠命令 hooks/ # 生命周期脚本 rules/ # 模块化指令 settings.json # 团队设置 settings.local.json # 个人设置 backend/ main.py routes/ todos.py users.py models/ todo.py user.py tests/ test_todos.py CLAUDE.md # 后端指令 frontend/ components/ TodoList.tsx Sidebar.tsx pages/ index.tsx todos.tsx lib/ api.ts CLAUDE.md # 前端指令 .mcp.json # 托管 MCP 服务器 CLAUDE.md # 项目指令

👤 Agents 智能体

/agents

Examples: weather reporter, front-end engineer, QA engineer.
例如：天气播报员、前端工程师、QA 工程师。

✅ Fresh working memory per run 每次运行全新工作记忆 🎯 Scoped tools, model, permission 限定范围的工具、模型、权限 ⚡ Parallelizable 可并行化 
root/
├── .claude/
│   └── agents/
│       └── weather-agent.md
└── README.md
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

Create your first agent — /agents
创建你的第一个智能体

The Command (命令)

Type /agents.

Opens an interactive menu — pick "Create new agent" and the CLI drafts the agent file for you.
打开交互式菜单 — 选择"Create new agent"，CLI 会为你起草智能体文件。

Creates .claude/agents/<name>.md — a plain markdown file anyone can edit.
创建 .claude/agents/<name>.md — 任何人都可以编辑的纯 Markdown 文件。

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

Demo 演示

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

🎉 Yayyyyy! Problem solved with agents
耶！用智能体解决了问题

Agent created
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方
?

Not so fast...
别急...

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

🚨 Problem Statement 问题陈述

  1. ✅ Single source of truth (单一事实来源)

    The agent will always call the Open-Meteo API — no more source drift.
    智能体将始终调用 Open-Meteo API — 不再有来源漂移。

  2. ❌ Repetitively (可重复性)

    It’s not guaranteed that Claude will always call this agent.
    无法保证 Claude 始终会调用这个智能体。

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

Agent config fields with frontmatter
带 frontmatter 的智能体配置字段

Field 字段 Description 描述 Enforced by 执行者
name Recommended Unique identifier — e.g. weather-agent harness
description Required When to invoke. Use "PROACTIVELY" for auto-invocation prompt
model haiku, sonnet, opus, or inherit (default). weather-agent uses sonnet harness
tools Allowlist of tools. weather-agent allows WebFetch, Read, Write, etc. harness
skills Skills preloaded into agent context at startup — weather-agent preloads weather-fetcher harness
maxTurns Maximum agentic turns before the agent stops. weather-agent uses 5 harness
memory Persistent memory: user, project, or local. weather-agent uses project harness
color Visual color in task list. weather-agent uses green harness

The skills: field is what makes the agent special. It preloads any-skill directly into the agent’s brain at startup — before the agent has received a single instruction.

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

claude-code-best-practice Tips & Tricks
技巧与窍门

Claude Code tips and tricks — part 1
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

claude-code-best-practice Tips & Tricks
技巧与窍门

Claude Code tips and tricks — part 2
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

📝 CLAUDE.md 项目记忆文件

CLAUDE.md

Knowledge you provide to the model — read every session.
你提供给模型的知识 — 每次会话都会读取。

✅ Loaded into every session 每次会话都加载 👥 Team-shareable via git 可通过 git 团队共享 ⚠️ 200-line problem 200行问题 
root/
├── CLAUDE.md
└── README.md
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

Create your first CLAUDE.md — /init
创建你的第一个 CLAUDE.md

The Command (命令)

Type /init in Claude Code.

Claude scans your codebase and drafts a starter CLAUDE.md for you — project conventions, key patterns, common commands.
Claude 扫描你的代码库并为你起草一个初始的 CLAUDE.md — 项目约定、关键模式、常用命令。

Creates CLAUDE.md in your repo root — a plain markdown file you edit and commit.
在你的仓库根目录创建 CLAUDE.md — 一个你可以编辑并提交的纯 Markdown 文件。

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

📝 CLAUDE.md — the real thing
CLAUDE.md — 真实示例

A real CLAUDE.md file showing project rules and agent invocation instructions
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

claude-code-best-practice Tips & Tricks
技巧与窍门

Claude Code tips and tricks for CLAUDE.md
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

⚠️ CLAUDE.md problem — keep it under 200 lines
CLAUDE.md 问题 — 保持在200行以内

Illustration of the CLAUDE.md 200-line adherence problem
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

🎯 Skills 技能

.claude/skills/

Examples: weather fetching, sorting CSV rows, generating SVG cards.
例如：获取天气、排序 CSV 行、生成 SVG 卡片。

✅ Progressive disclosure — loaded on demand 渐进式披露 — 按需加载 ♻️ Reusable across agents 可在智能体间复用 
root/
├── .claude/
│   └── skills/
│       └── weather-fetcher/
│           └── SKILL.md
└── README.md
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

Create your first skill
创建你的第一个技能

Write it by prompting (通过提示词编写)

Just describe what you want Claude to do. It drafts the skill file for you.
只需描述你想让 Claude 做什么。它会为你起草技能文件。

"Create a skill that fetches weather from Open-Meteo for a given city."
"创建一个技能，为指定城市从 Open-Meteo 获取天气。"

Use Anthropic's skill-creator (使用 Anthropic 的 skill-creator)

Anthropic ships an official skill-creator skill. Invoke it and it walks you through generating a properly-structured skill.
Anthropic 提供了一个官方的 skill-creator 技能。调用它，它会引导你生成结构正确的技能。

Recommended — always produces the correct SKILL.md format.
推荐 — 始终生成正确的 SKILL.md 格式。

⚠️ Watch out (method 1) 注意（方法1）

The prompting method sometimes creates the wrong structure. Instead of generating a folder with SKILL.md inside (e.g. weather-fetcher/SKILL.md), it creates a plain weather-fetcher.md file. The wrong form isn’t recognized as a skill by Claude Code.
提示词方法有时会创建错误的结构。不是生成一个包含 SKILL.md 的文件夹（例如 weather-fetcher/SKILL.md），而是创建一个普通的 weather-fetcher.md 文件。错误的格式不会被 Claude Code 识别为技能。

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

🎯 Skills — a real one
技能 — 真实示例

A real skill file on disk — SKILL.md inside a named folder inside .claude/skills/
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

Skill config fields with frontmatter
带 frontmatter 的技能配置字段

Most fields control how and when the skill loads — enforced by the harness. Only description lives in prompt-land.
大多数字段控制技能如何以及何时加载 — 由工具链强制执行。只有 description 属于提示词层面。

Field 字段 Description 描述 Enforced by 执行者
name Recommended Display name and /slash-command (defaults to directory name) harness
description Required When to invoke — used for auto-discovery. Write it clearly. prompt
argument-hint Autocomplete hint shown in the / menu (e.g. [city-name]) harness
disable-model-invocation Set true to prevent Claude from invoking this skill automatically harness
user-invocable Set false to hide from / menu — background knowledge only harness
allowed-tools Tools allowed without permission prompts when this skill is active harness
model Model to use when skill is active: haiku, sonnet, opus harness
context Set to fork to run skill in an isolated subagent context harness

Small description, full body loaded on demand — this is progressive disclosure. Claude’s main context stays lean until the skill is actually needed.

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

💭 Context 上下文

/context

The model's working memory — what it can see in this moment.
模型的工作记忆 — 它此刻能看到的内容。

✅ Fresh every chat 每次对话都是全新的 ⚠️ Dumb-zone problem 盲区问题 ⚠️ /compact
20% of 1M tokens
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

🧠 Claude's Brain
Claude 的大脑

Think of it like this (这样理解)

Imagine Claude has a brain that holds everything it's aware of right now — your question, every file it's opened, every tool result, every word it's said back to you. If a thought isn't in the brain, Claude can't use it. Simple as that.
想象 Claude 有一个大脑，装着它此刻意识到的所有东西 — 你的问题、它打开的每个文件、每个工具结果、它对你说的每个字。如果一个想法不在大脑里，Claude 就无法使用它。就这么简单。

Context window diagram showing how the 1M token limit is divided across system prompt, tools, files, and conversation
💬
Your messages (你的消息) Every question, clarification, and follow-up (每个问题、澄清和追问)
📄
Every file Claude opens (Claude 打开的每个文件) Read a 500-page PDF? All of it is in the brain now. (读了一个500页的PDF？现在全部都在大脑里了。)
🔧
Every tool result (每个工具结果) Web searches, command output, screenshots — all held in memory (网页搜索、命令输出、截图 — 全部保存在记忆中)

Two Things to Know (需要知道的两件事)

1. The brain is finite. It can hold about 1 million tokens — roughly 750,000 words. Big, but not infinite. 2. The brain empties at the end of every chat. When you start a new conversation, Claude remembers nothing from the last one unless you tell it again.
1. 大脑是有限的。它大约能装100万个token — 约75万个词。很大，但不是无限的。2. 大脑在每次对话结束时清空。当你开始新对话时，Claude 对上一次对话什么都不记得，除非你重新告诉它。

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

What Loads at Session Start
会话启动时加载了什么

The moment you open Claude Code, certain things land in Claude's brain before you've typed a word. The rest waits in the wings — only loaded when you actually need it. This is called progressive disclosure.
当你打开 Claude Code 的那一刻，某些东西会在你还没打一个字之前就进入 Claude 的大脑。其余的在后台等待 — 只有当你真正需要时才加载。这就是渐进式披露。

Diagram showing what loads into Claude's context window at session start
📋
CLAUDE.md — full content (完整内容) Standing instructions, every line. Always pinned in the brain at startup. (常驻指令，每一行。启动时始终固定在大脑中。)
🎓
Skills — descriptions only (仅描述) Claude knows which skills exist and what each does — the full content loads when the skill is actually invoked. (Claude 知道有哪些技能以及每个技能是做什么的 — 完整内容在技能实际被调用时加载。)
👤
Agents — descriptions only (仅描述) The roster of specialists. The full system prompt loads when the agent is dispatched. (专家名册。完整的系统提示词在智能体被派遣时加载。)

The One-Liner (一句话总结)

Only descriptions of skills and agents are loaded at startup — the rest is fetched on-demand. That's progressive disclosure. It keeps the brain light.
只有技能和智能体的描述在启动时加载 — 其余按需获取。这就是渐进式披露。它让大脑保持轻盈。

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

📄 Lost in the Middle
迷失在中间

by Nelson F. Liu · Stanford University · 2023
作者：Nelson F. Liu · 斯坦福大学 · 2023

Lost in the Middle paper illustration showing U-shaped attention curve across context positions
  1. Primacy & recency work. (首因效应和近因效应有效。) Information at the start of the context (what Claude sees first) and at the end (what Claude saw most recently) gets strong attention. These are the safe zones.
    上下文开头的信息（Claude 首先看到的）和结尾的信息（Claude 最近看到的）获得强烈关注。这些是安全区。
  2. The middle is the dumb zone. (中间是盲区。) Content buried in the middle of a long context effectively disappears. The model has the tokens, but doesn't weight them strongly during generation. It's in the working memory — but not really read.
    埋在长上下文中间的内容实际上消失了。模型拥有这些 token，但在生成过程中不会强烈加权它们。它在工作记忆中 — 但并没有真正被阅读。
  3. Practical implication. (实际含义。) Keep critical instructions either at the very top (in CLAUDE.md) or near the user's most recent message. A bigger context window doesn't help if your payload lands in the middle.
    将关键指令放在最顶部（在 CLAUDE.md 中）或靠近用户最近的消息。如果你的内容落在中间，更大的上下文窗口也没有帮助。

This is the "dumb-zone problem" the deck has been warning about — now you know where it came from.
这就是这个演示文稿一直在警告的"盲区问题" — 现在你知道它从何而来。

Source: Liu et al. — Lost in the Middle: How Language Models Use Long Contexts (arXiv:2307.03172)

🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

📘 Workflow 工作流

.claude/commands/

Repeatable step-by-step recipes — the instruction manual that makes Claude run the same playbook every time.
可重复的逐步配方 — 让 Claude 每次运行相同剧本的操作手册。

✅ Reproducible recipes 可复现的配方 🔁 Same steps, every run 每次运行相同步骤 👥 Team-shareable via git 可通过 git 团队共享
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

📋 Orchestration Workflow
编排工作流

Command → Agent → Skill architecture flow
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

📹 Workflow in action
工作流实战

Claude running the weather orchestration workflow end-to-end
🧑‍💼 Agents 智能体 — the specialists 专家 A dedicated Claude worker — own context, own tools, own focus. Each runs in isolation.
一个专属的 Claude 工作者 — 独立的上下文、工具、关注点。每个都独立运行。 ✅ fresh working memory per run 每次运行全新工作记忆
📝 CLAUDE.md 项目记忆 — your memory 你的记忆 Knowledge you provide to the model. Read every session. Keep it under 200 lines.
你提供给模型的知识。每次会话都读取。保持在200行以内。 ⚠️ 200-line problem 200行问题
🎯 Skills 技能 — the know-how 知识 What the specialist (or Claude) can actually do. Loaded on demand — only when needed.
专家（或 Claude）实际能做什么。按需加载 — 只在需要时。 ✅ progressive disclosure 渐进式披露
💭 Context 上下文 — the working memory 工作记忆 What Claude holds in his head now — fresh every new chat. Finite budget; compact at ~50%.
Claude 现在脑子里装的东西 — 每次新对话都是全新的。有限预算；在约50%时压缩。 ⚠️ dumb-zone problem 盲区问题
📘 Workflows 工作流 — the instruction manual 操作手册 Repeatable step-by-step recipes — like an AC install guide. Deterministic, reproducible.
可重复的逐步配方 — 就像空调安装指南。确定性的、可复现的。 ✅ reproducible recipes 可复现的配方

🙏 Thank you!
谢谢！

Thank you

Questions? Feedback?
有问题？想反馈？

GitHub github.com/shanraisshan
1 / --
← → 或 Space 导航 (切换幻灯片)