Claude Code模板化实战：五层能力构建标准化AI编程工作流-育师

前阵子帮团队推Claude Code的时候，我最大的感受是：Agent本身的推理能力已经不是瓶颈，瓶颈在“怎么让每个人喂给Agent的上下文都是同一套高质量输入”。有人直接甩一句claude "帮我重构"就开始干活，有人把整个仓库架构文档贴在对话框里，还有人已经自己捣鼓Skill和Workflow了。差别就是这么拉开的。

我自己一直维护着一个叫claude-code-templates的仓库，专门用来解决这个问题。简单说，它是一套把Claude Code从“裸奔状态”变成“标准化工作环境”的模板集合，覆盖记忆文件、技能、工作流、斜杠命令、钩子和权限配置这几个层面。这篇文章就把这套东西完整拆开讲，包括目录结构、安装方法、怎么让它跑起来，以及我在这上面摔过的跟头。如果你正在用Claude Code做日常开发，或者刚被它激发出“我是不是该沉淀点什么模板”的想法，这篇文章应该对你有用。

1. 开始之前：先把Claude Code的环境地基打牢

很多人一上来就抄模板，结果装都没装对，后面全白搭。所以我先花一章篇幅，把环境准备和目录结构讲清楚。

1.1 三种常用安装方式，实际怎么选？

Claude Code现在主流的安装方式有三种，我在不同机器上都试过，各自的适用场景不太一样。

第一种是npm全局安装，最省事，也最适合频繁更新的人：

npm install -g @anthropic-ai/claude-code

装完验证一下版本：

claude --version

升级就用：

claude update

第二种是官方提供的安装脚本，适合不想走npm、希望直接装成系统命令的场景。Linux和macOS上一般是：

curl -fsSL https://claude.ai/install.sh | bash

Windows上则是PowerShell方式，新版Windows Terminal里直接执行：

irm https://claude.ai/install.ps1 | iex

第三种是走编辑器扩展。在VS Code插件市场搜“Claude Code”安装后，它会要求本机已经有可用的claude命令。扩展只是给你一个图形化入口，实际干活还是靠CLI。所以如果你在Windows上装完扩展发现一直连不上，不妨先在终端里跑一下claude --version，确认PATH里那个CLI是好的。

提示：如果npm全局安装时遇到权限报错，不要无脑加sudo。更推荐用nvm或者volta管理Node环境，再装全局包，省得后面被各种权限问题恶心。

卸载倒是很简单：

npm uninstall -g @anthropic-ai/claude-code

1.2 首次启动、登录与模板存储位置

装好后第一次运行claude，它会引导你登录。通常是网页授权，也可以手动配置API Key。登录成功后，用户目录下会生成一个.claude文件夹——这是所有全局配置和模板的存放点。

macOS / Linux上路径是：

~/.claude/

Windows上一般是：

C:\Users\你的用户名\.claude\

这个目录里通常会看到：

settings.json：全局权限和模型配置
skills/：用户级技能模板
commands/：自定义斜杠命令
CLAUDE.md：用户级记忆文件
config.json：MCP服务器等连接配置

除了用户级目录，每个项目里也可以建一个.claude/目录，放项目级配置。优先级通常是项目级覆盖用户级，比如项目里的settings.json和~/ .claude/settings.json如果冲突，以项目内为准。

这里有个容易忽略的点：Claude Code支持在项目根目录和子目录放CLAUDE.md，子目录的CLAUDE.md会在Agent进入相关目录时自动追加进上下文。这就给“按模块管理记忆”留了很大的设计空间，后面讲模板结构时会再展开。

1.3 关于“not available”提示的处理边界

有段时间安装或首次运行时，很多人会看到一行英文提示：

Note: Claude Code might not be available in your country. Check supported countries...

我的建议很简单：先别慌，更别去找旁门左道。这行字的意思是，你当前所在的网络出口环境不在官方支持列表里。这块不是技术问题，是使用范围和服务条款的问题。正当的做法是回到符合官方要求的网络环境，或者对照官方支持列表确认后再继续。绕开这个限制去强行安装，只会让后面的账号稳定性和安全性都埋雷。我在模板仓库的README里也专门写了一条：如果遇到这个提示，先把环境问题解决好，再回来谈模板。

2. claude-code-templates：一份仓库，五层能力

claude-code-templates本质上是一套分层模板。我在设计时没有把所有东西塞进一个文件，而是按Agent的工作生命周期拆成五层，每一层解决一个明确问题。

这五层分别是：记忆层、技能层、流程层、交互与守门层、权限层。

2.1 第一层：CLAUDE.md，给Agent的记忆锚点

很多人的CLAUDE.md就是一坨几百行的咒语，什么“你是资深工程师”“请务必认真思考”……写了一大堆，实际效果很差。因为Claude Code真正需要的是结构化的、可验证的项目约定，不是人格设定。

我仓库里的CLAUDE.md模板长这样：

# 项目基础信息 - 项目类型：后端服务 / 前端应用 / 全栈 - 技术栈：列出关键语言、框架、运行时 - 常用命令：安装、测试、构建、lint、启动 - 架构要点：模块划分、数据流方向、关键目录说明 # 编码约定 - 错误处理统一走 xxx - 测试文件放在同目录 __tests__ 下 - 禁止直接 console.log 提交 # Agent 工作约定 - 遇到不确定需求时，先列出选项，不要直接改代码 - 所有涉及删数据的操作，必须经过用户确认 - 执行修改前先运行测试

写这种文件的原则是：只写“Agent必须知道且容易记错”的东西，而不是写搜索引擎能查到的东西。比如“RESTful API的设计规范”就不需要写，但“这个项目里API错误码统一用三位数字”就值得写。

模板同时支持三层记忆：用户级~/.claude/CLAUDE.md放你的通用工作习惯，项目根放项目整体约束，子目录放模块级约束。这个分层的好处是，Agent在哪个目录干活，就自动加载哪一层的记忆，不会一上来就把整个项目的所有历史都读进上下文。

2.2 第二层：Skills，把“会做”变成“擅长做”

Skills是Claude Code比较有代表性的能力扩展方式。它的目录结构很固定：

.claude/skills/<技能名>/SKILL.md

每个技能就是一个文件夹，里面必须有SKILL.md，开头带一段YAML frontmatter，用来描述技能的名称和作用。我举一个仓库里现成的code-review技能：

--- name: code-review description: 在准备提交PR之前，对工作区改动做一轮全面的Code Review，重点关注安全问题、性能隐患和边界条件。当你需要检查代码改动质量时使用。 --- # Code Review 执行清单 1. 先读取当前git diff，了解改动范围 2. 逐文件检查，按以下优先级： - 安全问题（注入、越权、密钥泄露） - 性能隐患（N+1查询、无界循环、大对象复制） - 边界条件（空列表、超时、并发） 3. 输出：问题清单 + 修改建议 + 严重级别

这里最关键的是description字段。Claude Code不会主动扫描技能文件夹，它是在对话中根据用户请求匹配技能描述，命中了才加载对应的SKILL.md作为额外指令。所以description写得越具体、越贴近真实用户话术，技能被触发的概率越高。像“代码审查”这种泛泛的词反而不容易被命中，你要写“在准备提交PR之前”“检查代码改动质量时”这种带场景的话。

在对话窗口里输入/skills，可以查看当前环境加载了哪些技能。技能可以放用户级~/.claude/skills/，也可以放项目级.claude/skills/，后者会随项目走，适合团队共用。

2.3 第三层：Workflows，把流程固化成可执行协议

如果说Skills是“单点能力”，Workflows就是“端到端的流程编排”。Claude Code支持在.claude/workflows/目录下定义工作流，每个工作流是一个Markdown文件，用frontmatter声明它的用途、模式、可用工具和权限。

我仓库里最常用的一个模板是“需求到实现”的工作流：

--- name: implement-feature description: 根据PRD实现一个新功能，覆盖测试和文档。当你需要按需求文档落地功能时使用。 mode: primary tools: Read, Edit, Write, Bash, TodoWrite permissions: - read - edit --- # 功能实现流程 1. 读取 docs/prd.md，列出需求清单和验收标准 2. 检查现有代码结构，确认改动影响范围 3. 先写测试，再实现核心逻辑 4. 运行测试，直到全部通过 5. 补充或更新README里相关说明 6. 输出变更摘要，按模块拆分提交建议

Workflows的价值在于把“人类团队里约定俗成的流程”固化成Agent每次都会遵守的协议。它比直接在对话里说“你先做A再做B”可靠得多，因为每次执行都是同一套标准，不会被Agent的随机性带偏。

对于更复杂的任务，你还可以把工作流模式设成subagent，让主Agent把子任务派发给专门的工作流去执行，类似于把团队里的“写测试的人”和“做架构设计的人”分开。这个设计在文档里写得比较清楚，我这里只提一句：不要一上来就设计复杂的多Agent协作，先让一个primary workflow跑通，再考虑拆子任务。

2.4 第四层：Slash Commands与Hooks，交互和守门员

Slash Commands是给“人类主动触发”用的快捷指令。目录在.claude/commands/，每个Markdown文件就是一个命令。

比如我放了一个review.md：

--- description: 对当前改动做一轮代码审查 argument-hint: 可选填关注点，如安全、性能 --- # 代码审查 请针对当前工作区的改动做一次审查，重点关注：$ARGUMENTS

这样在对话里输入/review 安全，就会触发这个模板，并把“安全”传给$ARGUMENTS参数。Slash Commands很适合把高频、固定格式的操作沉淀下来，比如提PR、写周报、生成迁移脚本。

Hooks则是另一个维度的东西——它像守门员一样，在Agent执行某个动作之前或之后介入。这部分通常写在settings.json里，然后指向一段脚本。我仓库里给了一个PreToolUse的示例，用来拦截危险的删除命令：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash(rm -rf|drop table|truncate):", "hooks": [ { "type": "command", "command": "node .claude/hooks/guard-danger-command.js" } ] } ] } }

guard脚本的逻辑很简单：匹配到危险命令就输出exit 1，让Agent停下来等用户确认。这样比单纯在提示词里写“不要删库”可靠得多，因为Hooks是机制层面的拦截，不依赖Agent自觉。

2.5 第五层：settings.json权限模板，安全与效率的平衡

最后一层是权限配置。Claude Code默认是每次工具调用都要确认的，这在探索阶段没问题，但真跑起多步流程时，频繁点确认会让人抓狂。

我的模板里给了一套分级的权限策略：

{ "permissions": { "allow": [ "Read", "Edit", "Git", "Bash(npm run test:):", "Bash(npm run lint:):", "Bash(npm run build:):" ], "ask": [ "Bash(npm install:)", "Bash(rm:)" ], "deny": [ "Bash(drop database:)" ] } }

核心思想是：读文件和编辑文件默认放行，运行项目内已有脚本放行，安装依赖和删除操作保持询问，明确危险的命令直接拒绝。

提示：不要把--dangerously-skip-permissions当成日常选项。我见过有人在开发机上全程跳过权限，结果Agent顺手执行了一段从网上抓来的脚本，把项目配置文件改得面目全非。这种参数只适合跑一次性且完全可信的任务。

3. 实操复现：把模板库初始化到你的环境

理论知识说完了，这一章就讲怎么把这个仓库真正部署起来。我会给两种方式：一种是脚本化一键布置，一种是手动装GitHub上的Skills。

3.1 用初始化脚本一键布置全局模板

我把常用的布置动作写成了scripts/init.sh，做三件事：拷贝用户级模板、创建目录结构、输出最终清单。

#!/usr/bin/env bash set -euo pipefail CLAUDE_DIR="${CLAUDE_DIR:-$HOME/.claude}" REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" mkdir -p "$CLAUDE_DIR"/{skills,commands,workflows,hooks} # 拷贝全局记忆文件 cp "$REPO_DIR/templates/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md" # 拷贝用户级技能 cp -R "$REPO_DIR/templates/skills/"* "$CLAUDE_DIR/skills/" # 拷贝用户级斜杠命令 cp -R "$REPO_DIR/templates/commands/"* "$CLAUDE_DIR/commands/" # 如果存在全局settings模板，合并（这里只做提示，不覆盖已有配置） if [ -f "$CLAUDE_DIR/settings.json" ]; then echo "检测到已有 settings.json，跳过自动覆盖，请手动合并" else cp "$REPO_DIR/templates/settings.json" "$CLAUDE_DIR/settings.json" fi echo "模板初始化完成。目录：$CLAUDE_DIR"

执行后，你本机的Claude Code就有了全局记忆文件、一批基础技能和斜杠命令，以及一份保守的权限配置。项目级的.claude/目录同样可以直接拷贝，我只建议把settings.json合并而不是覆盖，因为每个项目的危险命令清单不一样。

3.2 手动安装GitHub上的Skills

社区里有很多现成的Skills仓库，许多人问“claude code怎么手动装github上的skills”。其实方法非常简单，本质上就是把它放到Claude会扫描的目录里。

假设你找到的仓库结构是skills/<技能名>/SKILL.md，那么：

git clone <仓库地址> /tmp/awesome-skills cp -R /tmp/awesome-skills/skills/* ~/.claude/skills/

装完重启Claude Code，再输入/skills，就能看到新加载的技能。如果某个技能不生效，先检查路径是不是~/.claude/skills/技能名/SKILL.md，少一层目录都不行。

装社区技能时有两件事要小心：一是看它的SKILL.md有没有依赖脚本，装完要把配套脚本也一起拷过来；二是同类技能重复装会导致触发时互相抢描述，我遇到过两个code-review技能混在一起，结果Agent一会执行甲的逻辑，一会执行乙的逻辑，输出风格完全不稳定。后来我的原则是：同类型技能只保留一个。

3.3 验证模板是否生效的三种方法

装完模板不代表生效，必须自己验证一遍。我常用的验证方式有三种。

第一种是直接输入/skills和/commands，看列表里有没有你新加的东西。这个方法最快，适合刚装完后的初步确认。

第二种是“触发式验证”。比如我装了一个security-review技能，就故意在对话里输入：“帮我审查一下这段登录代码的安全性，我准备提交PR。”如果技能被触发，Agent会主动引用SKILL.md里的检查清单，输出风格和直接问完全不同——它会按清单逐项展开，而不是泛泛而谈。

第三种是跑一次预设Workflow。新建一个空分支，输入类似“按implement-feature工作流，把这个README里的功能描述落地”。工作流如果生效，你会看到Agent先读取PRD、再列需求清单、然后才动手，顺序和Workflow文件里定义的一致。

这几种验证方式覆盖了三个层次：文件有没有被扫描到、技能有没有被语义触发、工作流有没有被流程级执行。三层都通了，模板才算真正接进你的使用环境。

4. 让模板真正跑起来：权限、MCP与多模型切换

模板装好只是开始。真正让这套东西顺手的，是后面的几个进阶配置。这些配置都是高频热搜词，我今天一次性讲透。

4.1 权限策略：从“每次都问”到“该问才问”

前面已经给了权限模板，这里再说一个实际问题：怎么找到“每次都要问”和“过度放权”之间的甜点值。

我的建议是，第一周先不要急着改权限。让Claude Code在原生日志状态下跑几天，然后统计一下：它在哪些命令上频繁让你确认，这些命令是不是安全、是不是项目内脚本。比如我统计后发现“跑测试”和“git commit”占了确认次数的六成，于是把它们放进allow；而“安装依赖”和“删除文件”仍然保留ask。

另外有个顺手的小技巧：在交互页面按Shift+Tab会切到自动接受权限的临时模式，适合连续看Agent快速改多文件，但只适合当前会话，不会全局放权。全局层面，我还是建议用一个保守的settings.json模板，宁可它多问几次，也别让Agent任意执行未知命令。

4.2 MCP接入：把外部工具变成Agent的双手

MCP（Model Context Protocol）是Claude Code接入外部工具的标准方式。我的模板仓库里专门有一个MCP推荐清单，包括文件系统、网页抓取、数据库查询、上下文检索这类常用工具。

项目级的MCP配置通常放在.mcp.json里：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }, "fetch": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"] } } }

也可以用命令行方式管理：

claude mcp add my-server -- <启动命令> claude mcp list

接入MCP后，模板里的Workflow就可以写“查询数据库获取用户列表，然后生成统计报告”，Agent会直接调用数据库工具，而不是靠猜。这里有个经验：MCP服务器不要加太多，每个工具的描述都会占用上下文空间，而且会让Agent在决策时多一层权衡。我一般的标准是，项目里最多常驻三到五个MCP服务，其余按需用claude mcp add临时注册。

4.3 接DeepSeek等第三方模型：ccswitch与ANTHROPIC_BASE_URL

Claude Code本身跑的是Anthropic官方模型，但很多人想把它接到DeepSeek等其他模型上，原因无非是成本、延迟或团队既有模型生态。这完全是可行的，因为官方客户端支持通过环境变量指定兼容接口的地址和鉴权信息。

最简单的方式是设置两个环境变量：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的DeepSeek API Key" claude

如果你用的是其他兼容服务商，把ANTHROPIC_BASE_URL换成服务商文档里给的地址就行。ANTHROPIC_AUTH_TOKEN一般填服务商的API Key。还可以用ANTHROPIC_MODEL指定模型别名，例如deepseek-chat或deepseek-reasoner。

这里要提醒一句：第三方兼容接口再好，也不是官方模型的全集。像某些高级思考模式、特定工具调用细节，可能会和原生Claude Code体验有差别。所以我把模型切换相关的变量做成了模板里独立的一份env.example，专门记录“当前切换到的是哪个模型、哪些能力不可用”，避免三天后自己都忘了当前在跑什么。

社区里还流行一个叫ccswitch的小工具，专门解决“在多个模型/服务商配置之间切换”的麻烦。它的本质是把多套环境变量组合存起来，然后用一行命令切换。我实际用下来觉得最有用的场景，是同时维护DeepSeek的两种模型：

ccswitch add deepseek-chat --base-url https://api.deepseek.com/anthropic --model deepseek-chat --token xxx ccswitch add deepseek-reasoner --base-url https://api.deepseek.com/anthropic --model deepseek-reasoner --token xxx ccswitch use deepseek-chat claude

需要注意，切换完配置后通常要重启Claude Code进程才会完全生效。ccswitch的具体命令以它的README为准，不同版本略有差异，但思路是一样的：它帮你托管了那几行环境变量，省得每次手改。