一、核心心智模型
Claude Code 的本质不是“更会聊天的 IDE 插件”，而是一个由模型驱动、由 Harness 约束和增强的工程执行循环。
1. Model 不是系统，Harness 才是系统
模型负责推理、规划、生成文本和调用工具。但真正决定可靠性的，往往是模型外面的那层工程结构：它给模型什么上下文、允许它用什么工具、什么时候拦截、如何验证、失败后如何反馈。
这层结构就是 Harness。它像一套安全带、仪表盘、方向盘和刹车系统，把“会思考的模型”变成“能在工程现场工作的代理”。
2. Agentic Loop 是基本运行节奏
Claude Code 接到任务后，通常会经历：理解目标、读取上下文、选择工具、执行操作、观察结果、修正计划、继续执行、最后交付。这不是一次性问答，而是循环。
Harness 工程的目标，就是让这个循环在复杂项目里仍然安全、便宜、可控、可复用。
点击图中的节点，可以查看每个环节在 Claude Code 中对应的工程机制。
同事视角：给它背景、边界和验收标准
如果你把 Claude Code 当作新人同事，它需要知道项目结构、编码约定、风险区域、测试方法、交付格式。`CLAUDE.md`、Skills 和 SubAgents 就是它的入职材料、岗位手册和专家协作网络。
编译器视角：输入越结构化，输出越稳定
命令、Skill、SDK 的价值，是把自然语言任务变成更稳定的工程输入。好的 Prompt 不是花哨语气，而是约束明确、数据充分、输出可验证。
流水线视角：让 AI 输出进入检查、审计和回滚机制
Hooks、CI/CD、权限和审计日志让 AI 的每一步都可以被观察、拦截、复核。工程团队真正需要的不是“AI 看起来聪明”，而是“AI 出错时系统知道怎么兜住”。
二、四层架构
可以把 Claude Code 的能力分成四层：记忆层、扩展层、集成层、编程层。每一层解决不同类型的问题。
层 1：记忆层
代表机制：CLAUDE.md、项目说明、团队规范。
解决问题：让 Claude Code 每次进入项目时都知道“这里怎么做事”。比如代码风格、目录职责、禁止修改的文件、测试命令、PR 规范。
层 2：扩展层
代表机制：Skills、SubAgents、Slash Commands、Hooks。
解决问题：把重复任务、专家能力和自动化检查沉淀下来，不再依赖每次手动提示。
层 3：集成层
代表机制：MCP servers、外部 API、数据库、GitHub/Jira/Slack 等工具。
解决问题：让 Claude Code 不只读写本地文件，也能接入团队真实工作流和业务系统。
层 4：编程层
代表机制：Headless CLI、Agent SDK、结构化输出。
解决问题：把 Claude Code 变成可编程组件，嵌进 CI、后台服务、内部平台和自动化脚本。
什么时候该用哪一层？
如果问题是“Claude 老忘记项目规则”，用记忆层。如果问题是“同类任务每次都要重新教”，用 Skills 或 Commands。如果问题是“上下文太大、任务太杂”，用 SubAgents。如果问题是“AI 的操作需要被拦截或自动验证”，用 Hooks。如果问题是“Claude 需要访问外部系统”，用 MCP。如果问题是“我要让 AI 在无人值守流程里跑”，用 Headless 或 SDK。
三、记忆系统：CLAUDE.md
记忆不是让模型“永远记住一切”，而是给每次会话一个高质量、可维护的起点。
CLAUDE.md 应该写什么
- 项目是什么，主要用户和核心目标是什么。
- 目录结构如何分工，哪些目录不能随便改。
- 开发、测试、构建、格式化命令。
- 编码风格、命名习惯、错误处理原则。
- 安全边界：密钥、生产配置、迁移脚本、数据文件。
- 交付格式：修改说明、验证结果、风险提示。
npm test -- api”才有用。
# Project Guide
## What this project is
This repository contains a multi-tenant billing service.
The critical path is invoice generation, payment reconciliation, and audit logs.
## Development commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
## Engineering rules
- Do not edit generated files under `src/generated/`.
- Do not change database migrations unless the user explicitly asks.
- Prefer small, reversible patches.
- Add tests for bug fixes and behavior changes.
## Delivery format
When done, summarize:
1. Files changed
2. Behavior changed
3. Commands run
4. Remaining risks一个好 CLAUDE.md 的自检清单
- 新人读完能在十分钟内知道项目怎么跑起来。
- Claude 读完能知道哪些操作需要谨慎。
- 每条规则都能被执行或验证。
- 没有把大量业务文档、API 手册、历史讨论塞进去。
- 有明确的“完成后汇报格式”。
四、Skills：把专业能力打包
Skill 是“按需加载的能力包”。它不是把所有知识塞进主上下文，而是让 Claude 在任务相关时加载专门说明、脚本和参考资料。
参考型 Skill
像一本薄手册，告诉 Claude 某个领域的规则。适合代码审查、安全检查、写作风格、财务分析口径。
任务型 Skill
像一个操作流程，指导 Claude 完成一类任务。适合发版、提交、生成报告、迁移数据。
复合型 Skill
包含说明、脚本、模板、参考资料。适合复杂生产任务，但要通过渐进式披露控制上下文成本。
SKILL.md 的设计重点
description 是触发器。它要准确描述什么时候用，而不是泛泛介绍“我很强”。
正文是路由器。正文告诉 Claude 先做什么、何时读取哪个参考文件、何时运行哪个脚本，而不是把全部知识堆在一个文件里。
工具权限要最小化。如果 Skill 只是读文件做总结，就不该默认拥有写文件或执行任意 Bash 的能力。
---
name: api-review
description: Use when reviewing REST or GraphQL API changes for compatibility, security, and test coverage.
version: 1.0.0
allowed-tools: Read, Grep, Bash(npm test:*), Bash(pnpm test:*)
---
# API Review Skill
## Goal
Review API changes before merge. Focus on contract stability, auth checks,
input validation, error shape, and regression tests.
## Workflow
1. Inspect changed route/controller/schema files.
2. Compare public response shapes with existing tests and docs.
3. Check auth and permission boundaries.
4. Run the narrowest relevant test command.
5. Report findings by severity.
## Reference files
- Read `references/api-checklist.md` only if the change touches public API shape.
- Read `references/security-rules.md` only if auth, tokens, or PII are involved.五、SubAgents：任务委派与上下文隔离
子智能体不是为了显得热闹，而是为了解决主上下文被污染、任务过大、专业边界不清的问题。
什么时候用子智能体
- 需要大范围探索，但主线程只需要结论。
- 需要并行调查多个模块。
- 任务噪声很高，比如读日志、扫依赖、找历史实现。
- 需要专业角色，比如安全审查、测试修复、性能分析。
- 希望限制某类任务的工具权限。
什么时候不要用
- 任务很小，主线程直接完成更快。
- 下一步完全依赖子智能体结果，且没有并行空间。
- 任务需要高度统一的编辑上下文，拆开会增加冲突。
- 只是为了“多 Agent”而多 Agent。
只读观察者
负责读代码、找事实、整理证据。适合 codebase-explorer、doc-researcher、log-analyzer。
执行型处理器
负责一个清晰写入范围内的修改。适合 test-fixer、migration-writer、docs-updater。
并行调查组
多个子智能体分别调查前端、后端、数据库、部署配置，主线程整合。
流水线角色
先探索，再实现，再审查，再验证。每一环有清楚输入输出。
团队型协作
为团队沉淀固定角色：架构师、实现者、审查者、发布员。适合成熟组织，但治理成本更高。
---
name: codebase-explorer
description: Use proactively when a task requires locating relevant files, ownership boundaries, or existing implementation patterns before editing.
tools: Read, Grep, Glob, LS
---
You are a read-only codebase explorer.
Your job:
- Find the files and patterns relevant to the user's task.
- Summarize the smallest useful implementation path.
- Cite concrete file paths and symbols.
- Do not edit files.
- Do not run broad or destructive commands.
Return:
1. Relevant files
2. Existing patterns
3. Recommended edit scope
4. Risks or unknowns六、Hooks：把“应该”变成“自动”
Hooks 是 Claude Code 的事件驱动机制。它允许你在工具调用前后、用户提交提示、会话停止等时机运行命令，从而实现拦截、审计、格式化和质量门禁。
执行前拦截：适合安全边界
在 Bash、Edit、Write 等工具执行前检查输入。比如阻止删除生产配置、阻止读取密钥文件、阻止危险 shell 命令。
执行后处理：适合自动格式化和审计
在文件编辑后运行格式化、lint、记录操作日志，或者把工具结果压缩成 Claude 能理解的反馈。
停止前门禁：适合验收
当 Claude 准备结束任务时，检查测试是否运行、是否还有未处理 TODO、是否遗漏交付说明。
子智能体结束检查：适合输出质量
当子智能体返回结果时，检查它是否给出证据、文件路径、风险说明，而不是只写宽泛结论。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous-bash.sh",
"timeout": 5
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-and-lint.sh",
"timeout": 30
}
]
}
]
}
}Hook 设计三原则
确定性优先：能用脚本判断的，就不要让模型再猜。
失败信息要可行动：不要只说 failed，要告诉 Claude 哪个文件、哪条规则、下一步怎么修。
控制阻塞成本：格式化可以快跑；全量测试可能放到 Stop Hook 或 CI 里。
七、MCP：连接外部世界
MCP 可以理解为 AI 工具世界的标准适配层。它让 Claude Code 通过统一协议访问数据库、浏览器、GitHub、工单系统、知识库和内部服务。
从 M×N 到 M+N
没有标准协议时，每个 AI 客户端都要分别适配每个外部工具，复杂度是 M×N。MCP 把外部工具包装成 server，AI 客户端只要理解 MCP，复杂度接近 M+N。
MCP 与 Skill 的关系
MCP 像厨房，提供真实工具和食材；Skill 像菜谱，告诉 Claude 什么时候用哪些工具、按什么步骤组合、如何判断做完。
MCP 落地前要问的 6 个问题
- 这个 MCP server 会暴露哪些工具？是否需要全部暴露？
- 它能读取哪些数据？是否包含客户信息、密钥或生产数据？
- 它能写入或删除数据吗？写操作是否需要额外确认？
- 工具输出是否可能过大，导致上下文成本爆炸？
- 认证凭据放在哪里，如何轮换？
- 失败时 Claude 能收到可理解的错误信息吗？
八、Headless 与 CI/CD
当 Claude Code 从交互终端进入无人值守流程，它就不再只是个人助手，而是软件交付链的一环。
自动代码审查
在 PR 创建或更新时，让 Claude 检查风险、测试覆盖和变更说明。适合做第一轮筛查，不应替代人类审批。
失败分析
当 CI 失败时，收集日志、定位可能原因、提出修复建议，必要时生成补丁。
发布辅助
根据提交、issue、PR 自动整理 changelog、迁移说明、回滚策略和验证清单。
# CI 中的 AI 审查任务设计示例
Goal:
Review the pull request for risky changes.
Inputs:
- PR diff
- Test results
- Project CLAUDE.md
- Security checklist
Allowed actions:
- Read repository files
- Read CI logs
- Comment with findings
Forbidden actions:
- Do not push commits
- Do not approve the PR
- Do not access production secrets
Output:
- Critical findings
- Suggested tests
- Questions for human reviewer
- Confidence level九、Agent SDK：把 Claude Code 变成组件
CLI 适合人机协作，SDK 适合系统集成。SDK 的价值在于你可以用程序控制会话、工具、权限、消息流和结构化输出。
适合 SDK 的场景
- 内部代码分析服务。
- 批量文档生成或迁移助手。
- 带审计日志的 AI 运维工具。
- 面向业务用户的受控自动化平台。
- 需要 JSON Schema 输出的工作流。
CLI 与 SDK 的选型
如果任务由工程师临场判断、频繁切换上下文，用 CLI。如果任务有固定入口、固定输入、固定输出、需要被其他系统调用，用 SDK。
不要太早 SDK 化。先在 CLI 中跑通工作流，再把稳定部分抽成命令、Skill、Hook，最后再封装成服务。
// 伪代码：代码分析服务的 SDK 化轮廓
import { query } from "@anthropic-ai/claude-code";
export async function analyzePatch(diffText) {
const messages = [];
for await (const message of query({
prompt: `
Review this diff for correctness, security, and missing tests.
Return strict JSON with fields: findings, tests, risks.
DIFF:
${diffText}
`,
options: {
allowedTools: ["Read", "Grep"],
maxTurns: 6
}
})) {
messages.push(message);
}
return normalizeClaudeMessages(messages);
}十、Plugins：团队能力的封装与分发
当一个团队积累了稳定的 Skills、SubAgents、Hooks 和 Commands，就需要把它们打包成可安装、可版本化、可治理的能力包。
什么时候该做 Plugin
- 多个项目重复使用同一套 AI 工作流。
- 安全、审查、发布等流程需要统一。
- 需要给新人一键安装团队标准能力。
- 需要版本管理和回滚。
什么时候不该做 Plugin
- 流程还不稳定，经常改。
- 只服务一个项目，放项目目录更清晰。
- 权限边界还没想清楚。
- 缺少 README、示例和测试方式。
team-ai-harness/
plugin.json
skills/
api-review/
SKILL.md
references/api-checklist.md
release-notes/
SKILL.md
templates/changelog.md
agents/
codebase-explorer.md
security-reviewer.md
commands/
review-pr.md
prepare-release.md
hooks/
block-dangerous-bash.sh
audit-tool-use.sh
README.md十一、综合实战：设计你的 Harness
下面这个小工具可以把你的选择转换成一份 Harness 配置草案。它不是最终答案，但能帮你思考应该先建设哪些能力。
选择你的团队痛点
练习 1：写一个项目 CLAUDE.md
选一个真实项目，用 30 分钟写出项目目标、目录结构、命令、安全边界和交付格式。然后让 Claude Code 做一个小 bugfix，看它是否少问了重复问题。
练习 2：做一个代码审查 Skill
先写最小版本，只包含 description、审查流程、输出格式。使用 3 个历史 PR 测试触发是否准确，再决定是否加入参考文件和脚本。
练习 3：做一个危险命令 Hook
拦截 `rm -rf`、生产配置修改、密钥文件读取。让错误信息告诉 Claude 为什么被拦截，以及允许的替代方案。
练习 4：把审查放进 CI
只让 AI 输出审查意见，不允许推送代码或批准 PR。观察一周后再决定是否扩大权限。
十二、30 天学习路线
不要一上来就搭复杂 Agent 团队。先让一个项目稳定受益，再逐层升级。
第 1-3 天：建立基本使用习惯
熟悉 Claude Code 的交互方式、常用命令、权限确认、读写文件和运行测试。目标是让它完成小而明确的任务。
第 4-7 天：写好 CLAUDE.md
整理项目规则、命令、安全边界和交付格式。用真实任务反复修订，删除空话，保留可执行规则。
第 8-12 天：沉淀第一个 Skill
选择一个重复任务，如代码审查、发版说明、测试补全。写最小 Skill，并用历史案例验证触发准确性。
第 13-17 天：引入 SubAgent
先做只读型 explorer，让主线程不再承担大范围搜索噪声。之后再尝试执行型子智能体。
第 18-22 天：加入 Hooks
从低风险自动化开始：格式化、lint、审计日志。再加入危险命令拦截和 Stop Hook 门禁。
第 23-26 天：连接外部系统
用 MCP 接入一个低风险工具，比如只读知识库或 issue tracker。先读后写，先低权限后高权限。
第 27-30 天：团队化试点
把稳定的 CLAUDE.md、Skill、SubAgent 和 Hook 推给一个小团队试用。收集失败案例，更新文档，再考虑 Plugin 化。
小测验：选择正确组件
你的团队希望 Claude 每次修改代码后自动运行格式化，并在失败时把错误反馈给 Claude。应该优先使用什么？
资料来源
本文的结构参考公开目录，技术概念参考官方文档。这里列出便于继续阅读的链接。