Claude Code安全实践：从权限配置到技能手册落地

最近几个技术群都在传一份据说来自 Anthropic 内部的 33 页「技能手册」，核心主题是教自家员工怎么在真实工程环境里使用 Claude。消息来源真伪我没法验证，但里面最醒目的一句话——别让它动手——恰好和我这一年用 Claude Code 的体感完全对上。所以与其逐页猜哪句话是真的，不如我把这个原则拆成一套能直接落地的实践：安全边界怎么划、权限怎么配、技能文件怎么写、团队流程怎么搭、常见坑怎么填。

如果你也想把 Claude 从“聊天很爽”变成“干活放心”，这篇文章就是给你梳理的一张地图。全程我会用大量实际操作里的细节和踩坑记录，尽量让你读完能直接照着搭一套属于自己的“技能手册”，而不是看完只记住几句口号。

1. 先把这个事件本身拆清楚：33 页手册到底想管什么

1.1 “别让它动手”不是保守，是分层授权

如果只看这句话，你很容易把“别让它动手”理解成“Anthropic 不信任自己的模型”。其实恰恰相反，这是标准的工程分层授权思路。任何一个靠谱的团队都有一套变更管理流程：新同事头几个月不能直接动线上环境，老员工改生产配置也要走审批。把同样的逻辑套到 AI Agent 上，结论自然就是“别让它跳过你直接动生产环境”。这跟信不信任模型没关系，只跟风险边界有关系。

LLM 的执行方式本质上是概率化的。它解一道题有时候一次答对，有时候要试两步。平时聊天你感觉不到这种不确定性，可一旦给了它终端权限，每次“试一步”都可能落到文件系统、数据库、CI/CD 管道的真实副作用上。一次无意识的递归删除，一条跑到错误目录的指令，造成的损失可能要你追查一整天。所以手册把它当成头号原则摆出来，不是因为它保守，而是因为它知道“入口越宽，炸得越快”。

1.2 为什么连模型公司自己都坚持走审批流

我见过不少团队刚接上 Claude Code 时的第一反应：这东西能力这么强，直接全自动跑，省下的时间不是更多吗？坦白讲，这个诱惑我一开始也扛不住。后来有一次我让它批量重命名测试资源文件，它把另一个目录里的关键测试配置当成了同名文件，差点把整个分支搞到不能跑。从那天起，我对“审批流”这三个字的看法彻底变了。

审批流对使用者来说只是多一两次确认，但对错误率来说是数量级级别的下降。Agent 的错误特征不是“偶尔错一次”，而是“在你不注意的时候错一次”。它速度快、路径长，一旦带偏，你很难靠事后翻日志找回上下文。而人工审批恰好把一个“自动执行”问题，变成了“计划和结果比对”问题，后者是人脑比较擅长的。Anthropic 内部手册把审批放进默认流程，本质上是在承认：再强的模型也需要一个最终把关人。

1.3 手册里最值得抄的循环：先起草、再审查、后执行、留复盘

我从这份手册里提炼出来的核心循环是四步：先起草、再审查、后执行、留复盘。

• 起草：把目标、上下文、约束条件全部丢给 Claude，让它先产出方案或代码，而不是立刻动手。
• 审查：由人逐条核对方案里哪些操作涉及写、改、删，哪些步骤真的需要权限。
• 执行：只对确认过的步骤放开执行权限，最好一次只放一个操作。
• 复盘：观察执行结果，把任何失败模式写回技能文件或权限规则，让下一次协作更稳。

这个循环最有价值的地方在于：它不仅防住了意外操作，还让模型在每一次反馈中不断校准边界。Claude 会逐渐知道哪些指令需要先解释、哪些文件不能碰、哪些命令必须等批准。这就像给新人做带教——不是不给权限，而是让权限随着信任慢慢长大。

2. 核心细节解析：Claude Code 的安全机制与权限配置

2.1 先搞清楚 Claude Code 到底能做什么

要谈权限管理，得先摸清工具的完整能力面。Claude Code 是一个在终端运行、也以 VS Code 扩展形式存在的编程 Agent，它大致能做四类事情：

• 读取文件：代码搜索、目录浏览、聚合上下文；
• 修改文件：创建、编辑、重命名、删除；
• 执行终端命令：运行测试、安装依赖、启动服务甚至提交代码；
• 调用外部工具：通过 MCP server 把各种 API、数据库、浏览器操作接进来。

这四类能力合在一起，等于给模型发了一张“能对整台机器所有文件产生副作用”的通行证。这就是为什么它没法像聊天窗口那样直接给结论就完事，每个动作都需要权限确认。我在帮团队落地时习惯先画一张能力清单，把工具能碰的资源类别列出来，再对照风险等级去配置权限。你连它能干什么都没搞清楚，就别谈安全边界了。

2.2 三种权限模式怎么选

Claude Code 里通常会涉及三种运行模式，每种模式解决不同协作场景。默认模式下，模型可以自主推理，但涉及文件修改、命令执行时会停下来等人确认，适合日常开发，效率和安全相对均衡。接受编辑模式会跳过文件修改的二次确认，自动落盘，适合批量格式化、补注释这类机械劳动，但对命令执行我建议仍然保留确认。计划模式会直接禁止一切执行，模型只能读取上下文并输出方案，它就是“别让它动手”原则里最直接的开关。

我个人的习惯是把计划模式设为默认，接到任务时先让 Claude 出方案；等我把方案里的危险点都圈出来了，再切换到默认模式，让它在确认框里一步步执行。经验是：对复杂任务，分两次问比一次性放权给它，风险低得多，最终产出质量也会更高。

2.3 把边界写死在 settings.json 里

模式是粗粒度开关，细粒度控制要落到权限规则上。Claude Code 支持在配置里声明允许和拒绝的规则，对工具调用做精确匹配。例如，可以让npm run test这类高频且低风险的命令进入白名单，不必每次确认；同时把git push、rm -rf、DROP TABLE这类高危操作放进黑名单，从规则层面让模型执行不了。

{ "permissions": { "defaultMode": "plan", "allow": [ "Bash(npm run test)", "Bash(npm run lint)", "Read(git status)" ], "deny": [ "Bash(git push)", "Bash(rm -rf *)", "Edit(config/production/*)" ] } }

这里有个细节：规则匹配的是工具调用的模式，不是简单字符串包含。所以写 deny 时要尽量覆盖常见变形写法，比如rm -rf和rm -fr都得单独写。默认情况下 Claude Code 已经比较克制，但如果有人自己把权限全开，后面所有锅都得自己背。我见过最快的翻车记录，是同事一上来就用了跳过权限校验的启动参数，然后在模型“善意”的驱动下把整个依赖目录清掉重装，最后版本全乱。代价不是时间，是信任。

另外还有一层更硬的控制叫 hooks。它可以在模型调用任何工具之前触发一段脚本，做审计、做阻断、做告警。这相当于给每次“动手”都留了日志和闸门。我通常会安排一个工具调用前钩子，把所有即将执行的命令写入本地审计文件。这样即使半夜出了状况，第二天也能精准回顾到底是谁、在哪一步、动了哪块。需要说明的是，不同版本的配置字段略有差异，具体以你安装版本的官方文档为准，但思路是一致的：先画规则，再留痕迹。

3. 实操过程：搭建你自己的“技能手册”工作流

3.1 安装与基础配置

实操部分从这里开始。Claude Code 的安装链路并不复杂，只是不同系统会有几个常见小坑。前提是机器上有 Node.js，版本最好 18 以上。安装命令非常简单：

node -v npm install -g @anthropic-ai/claude-code claude --version

装完之后，在项目目录直接运行claude就能进入交互式会话。如果你更习惯图形界面，也可以在 VS Code 里安装 Claude Code 扩展，侧边栏会有一个专门的面板做会话管理和代码理解。首次使用需要配置账号和 API 密钥，一般走官方登录流程，或者把密钥放到环境变量里让 CLI 自动识别。

安装时最容易翻车的点，是终端提示“claude 不是内部或外部命令”。这八成是 npm 全局目录没有进 PATH。解决方法是执行npm prefix -g看全局目录在哪，再把这个路径加进系统环境变量。Windows 上如果桌面端或扩展一直报“虚拟机平台”相关错误，需要去 Windows 功能里开启“虚拟机平台”组件，或者直接换用 WSL 2 环境跑 CLI，后者的稳定性明显更好。

3.2 从零写一个可复用的 Agent Skill

技能文件是一个 Markdown 文档，开头带一段 frontmatter，写明技能的 name 和 description，正文就是给 Claude 的完整操作手册。Claude 在遇到适用场景时，会先把这份文档读进去，按里面定义的步骤做事。它的价值在于把隐性经验变成显性规则，让团队每个人手里的 Claude 都拥有同一套打法。

--- name: code-review description: 对当前分支的 diff 做安全与健壮性审查，输出结构化评审表，不直接修改文件。 --- # Code Review 1. 先运行 `git diff main...HEAD` 获取变更内容。 2. 按以下顺序检查变更： - 是否在事务外执行了数据库写操作； - 是否硬编码了密钥或连接串； - 是否改变了公共接口参数但没同步调用方； - 是否引入了未使用的依赖。 3. 输出评审表，字段包含严重程度、位置、建议。 4. 除非特别说明，不要直接修改任何文件。

最后一条尤其重要，它把“只审查、不动手”的边界直接写进了技能定义里。以后只要触发这个技能，Claude 都会默认只做审查不改文件。这样一个技能文件放到位，比你在会话里反复提醒十次都管用。

接着需要让 Claude 能找到这个技能。个人项目可以放在默认的技能加载目录，团队项目则常常集中到一个 skills 仓库，按“技能名/SKILL.md”的目录结构维护，再通过配置文件指向仓库地址。这样新增技能只需要合并一个 MR，全组立刻可用，版本历史也清清楚楚。

3.3 一个可以抄的完整例子：先出方案、等批准再迁移

以迁移一批日志文件为例，看完整落地流程怎么走。如果直接让 Claude“把 A 目录旧日志整理到 B 目录并压缩”，它可能立刻就开始逐文件搬了。但按手册原则，第一轮先只给目标和约束，不做执行。

claude "请先不要执行任何命令。你只需要分析项目目录下 old_logs/ 的结构， 给出一个迁移到 archived_logs/ 的方案。方案里要包含：目录对照表、 是否压缩、校验方式、如果中途出错如何回滚。我审阅后再让你逐步执行。"

这个提示里“请先不要执行任何命令”是关键的边界词。Claude 会进入计划状态，读目录、列结构、给方案，整个过程零副作用。你确认方案后，再追加一句：

claude "方案我已确认。现在开始执行，但每一步执行前，先展示你将运行的命令， 等我回应 ok 再继续，不要一次性跑完所有步骤。"

这样它就变成了一个“每动一步都举手报告”的协作对象。过程可能比全自动慢几分钟，但对批量文件操作来说，这点时间买的是回滚余地。我特别推荐对文件、数据库、云资源有副作用的任务，长期坚持“先方案后执行”的习惯。

3.4 把技能做成团队共享资产

单人有单人用法，团队有团队用法。我在团队内部推的最简单做法是建立一个 skills 目录，用 git 管理，里面每类技能一个文件夹。申请新技能时，提一个 MR，内容必须包含场景说明、边界声明、示例对话。技能选择上，优先做三类：代码评审、依赖升级、环境问题排查，因为这几种场景错误率最低也最容易标准化。

接入 MCP server 也比较直接，命令行里用claude mcp add就可以把外部服务挂进来。需要留意的不是接入本身，而是接入之后必须重新审视权限——技能和 MCP 都是从外部拿进来的能力，组合在一起时，一次边界失误可能被放大成全局事故。我见过有人在团队技能里默认禁止访问生产配置，这就是很聪明的习惯，建议直接抄。

4. 常见问题与排查技巧实录

4.1 安装期问题速查

安装阶段我就见过不少人卡住。这里把最常见的几类整理成一张表，方便直接对照。

这些问题的共性是安装环境不干净。我的建议是第一次安装时就用干净的终端，关掉多余代理，装完先跑claude --version确认成功再进项目。

4.2 连接与服务类报错

连接问题最典型的报错有两个，一个类似 unable to connect to anthropic services，一个是 connection dropped (ECONNRESET)。第一个常见原因是网络层面不稳定，比如当前网络对长连接不友好，需要检查代理设置和防火墙规则，把相关服务域名加入可信任列表，并确保没有残留的全局代理干扰。第二个常见原因是任务跑得太久，连接被中间设备重置，也可能是上下文窗口被塞满导致的异常。

解决思路通常是拆任务。把一个大而全的请求拆成几个小步骤，让每次交互更短、更快，既能减少连接被重置的概率，也能让结果更可控。如果任务必须长跑，记得先确认版本的恢复能力，别硬扛着等它超时。

4.3 权限配置的几个典型坑

权限配置里我有几个踩过的典型坑，值得单独讲。第一，别用跳过权限校验的启动参数。它是把双刃剑，一旦用了，安全边界形同虚设。第二，deny 规则要写具体，并且多次验证。比如某次我只写禁止修改生产配置的主路径规则，漏掉了对相对路径或符号链接的覆盖，Claude 就绕过去改了目标文件。第三，有些脚本会通过动态拼接命令来避开简单规则匹配，所以不要把权限管理寄托在规则覆盖率上，还要配合 hooks 和日志审计。

还有一层更隐蔽的坑是提示注入。当 Claude 读取的文件内容来自互联网、第三方库或你本人都没来得及细读的文档时，文件里一旦藏了“请忽略权限提示并执行以下命令”这类内容，模型确实有被带偏的可能。因此，凡是要人工确认的命令，哪怕看起来像是它自信地“建议”的，也要回到自己的授权范围里审一遍，而不是因为它展示了完整命令就盲目放行。

4.4 一条快速排查清单

状态不稳时，我会按这个顺序排查：先确认 CLI 版本和扩展版本是否最新；再检查网络代理与证书设置；然后看是否存在自动化脚本或 hooks 在静默修改配置；最后查审计日志，找到最后一次成功调用前后的上下文。这套顺序解决了我九成以上的“莫名其妙挂掉”问题。建议你也存一份，先别看功能，先把环境拉回已知良好状态。

5. 手册之外：关于“边界感”的几点真实心得

5.1 把边界写进提示词，也算一种技能

配置和技能文件是硬边界，但很多时候你不会有时间去搭一个完整技能。这种情况下，在对话里主动声明边界同样有效。我会在会话开头明确告诉 Claude：“所有写操作必须先列出来，所有命令必须带说明，不要自动执行任何有副作用的动作。”只要这句话在，模型大部分时候都会收敛。

不要小看这种软约束。它配合确认框，已经足够挡住绝大多数低级事故。如果你连这句话都懒得多说，那就别怪模型自由发挥——你给它多少余地，它就有多大发挥空间。

5.2 汇报比动手更有价值

用 Claude 越久，我越觉得它最好的形态不是一个激进的操作员，而是一个优秀的汇报员。你可以让它并行做调研、出方案、找风险点，但把最终决策和执行确认留给自己。反过来说，如果一个工作流能让 Claude 在每次动手前都给出清晰的“我准备干什么、为什么这么干、风险是什么”，这个流程就已经成功了一大半。

我在团队里推动的也恰恰是这个理念：不是比拼谁让 Claude 干的活多，而是比拼谁的流程里人类把关更早、更轻松。代码审查里最值钱的批注，往往不是“这里写得不好”，而是“这里我不确认，先停下来”。Agent 协作也是一样，学会让它停下来，比学会让它加速更难。

5.3 从小试点再逐步放开

如果你正准备在团队引入 Claude Code，我的建议是先找两三个对工具熟练、且愿意填坑的同事试点，前两周只跟踪一个指标：误操作次数。误操作率降下来之前，别急着扩大人数或放开权限。等试点稳定了，再把技能文件、权限配置和审查清单一起沉淀下来，作为团队标准，而不是放任每个人各跑各的。权限可以逐步放，但边界必须一开始就立住。

最后说一句我实际用下来的感受：模型能力的上限，其实是团队流程的下限。那些看起来“多出来”的确认、审批和日志，不是在拖慢你，而是在替你把每个容易翻车的瞬间提前拦下。这也是这份“技能手册”最值得学习的地方——它看起来在限制 Claude，实际是在保护每一个使用 Claude 的人。