前阵子帮团队推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 | bashWindows上则是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-code1.2 首次启动、登录与模板存储位置装好后第一次运行claude它会引导你登录。通常是网页授权也可以手动配置API Key。登录成功后用户目录下会生成一个.claude文件夹——这是所有全局配置和模板的存放点。macOS / Linux上路径是~/.claude/Windows上一般是C:\Users\你的用户名\.claude\这个目录里通常会看到settings.json全局权限和模型配置skills/用户级技能模板commands/自定义斜杠命令CLAUDE.md用户级记忆文件config.jsonMCP服务器等连接配置除了用户级目录每个项目里也可以建一个.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. 逐文件检查按以下优先级 - 安全问题注入、越权、密钥泄露 - 性能隐患N1查询、无界循环、大对象复制 - 边界条件空列表、超时、并发 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。另外有个顺手的小技巧在交互页面按ShiftTab会切到自动接受权限的临时模式适合连续看Agent快速改多文件但只适合当前会话不会全局放权。全局层面我还是建议用一个保守的settings.json模板宁可它多问几次也别让Agent任意执行未知命令。4.2 MCP接入把外部工具变成Agent的双手MCPModel 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_URLClaude Code本身跑的是Anthropic官方模型但很多人想把它接到DeepSeek等其他模型上原因无非是成本、延迟或团队既有模型生态。这完全是可行的因为官方客户端支持通过环境变量指定兼容接口的地址和鉴权信息。最简单的方式是设置两个环境变量export ANTHROPIC_BASE_URLhttps://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为准不同版本略有差异但思路是一样的它帮你托管了那几行环境变量省得每次手改。4.4 思考等级与提示词缓存模板带来的额外红利热搜词里有“claude code调整思考等级命令xhigh workflows”我实际用下来这确实是模板A
