# Claude Code 工程实践：权限、Skills、MCP 与可验证交付

让 Claude Code 修改项目并不难。更需要设计的是一次完整的交付：它依据哪份需求工作，能调用哪些工具，修改如何检查，测试结果对应哪个提交，以及出错之后怎样恢复。

本文按这个顺序展开，从终端与 VS Code 的基本使用，到项目说明、Skills、MCP 和 SDK，再回到 Git 与发布验证。配置与命令按 **2026 年 10 月 18 日**核查的官方文档整理；团队落地时，应把已安装版本一起记录到工作规范中。

![工作流说明的组成](https://developer.qcloudimg.com/http-save/yehe-12805371/87c8fd86328317236ad9e3eef64f335e.png)

## 1. 把它接入现有工程流程

Claude Code 可以读取文件、修改源码、运行命令，并接入外部工具。它的执行范围取决于实际工具、权限配置、操作系统与远端账号，不能仅从“终端工具”或“IDE 插件”这两个界面标签推断。

可以先选择一个明确任务，例如修复具备最小复现的缺陷。要求产出包含：原问题、受影响文件、实现理由、实际运行的检查、未完成项和最终 diff。将这些产物纳入已有 PR 流程，比另建一套只看模型自评分的完成标准更容易衔接。

同一项目可以使用终端与编辑器界面。选择时主要看操作是否方便、差异是否容易审阅、会话与权限是否清楚，而非预设某类界面只能做补全。

## 2. 安装与版本核查

官方安装指南提供原生安装器，以及 Homebrew、WinGet 等包管理方式。原生安装与包管理安装的更新机制不同，团队应选定一种维护路径，避免同名二进制来自多个位置。[安装与更新指南](https://code.claude.com/docs/en/setup)

例如，macOS 可使用文档列出的 Homebrew cask：

```bash
brew install --cask claude-code
claude --version
claude --help
```

Windows 的 WinGet 路径为：

```powershell
winget install Anthropic.ClaudeCode
claude --version
claude --help
```

Linux、WSL 或原生安装器的具体步骤可按同一指南选择。遇到命令找不到时，先检查 PATH 和实际二进制位置；遇到认证错误时，区分登录方式、组织策略、网络与 API 凭据，不要为了跑通安装随意放宽整机脚本策略。

首次启动后按界面完成对应账号或 API 接入。登录方式不同，凭据与计费路径也可能不同，不能把浏览器登录统一描述成“自动回填一枚 API Key”。

## 3. 终端与 VS Code 可以并行使用

在项目目录启动终端会话：

```bash
claude
```

官方 VS Code 扩展提供图形界面，包含文件引用、计划审阅、差异显示和会话历史等功能；也可以在 VS Code 集成终端运行 CLI。[VS Code 集成指南](https://code.claude.com/docs/en/vs-code)

共享的是同一份项目文件，并不意味着所有界面在每个版本中都有完全相同的快捷键和配置读取规则。先确认当前打开的目录、分支、会话和运行环境，尤其是在本机、远程 SSH、WSL 与容器混用时。

项目本身不需要为了“适配 AI”改成某种统一前端结构。更有帮助的是给出真实的构建、测试、代码生成和本地运行入口，并说明哪些目录是源码、哪些是派生产物。

![终端与编辑器协作](https://developer.qcloudimg.com/http-save/yehe-12805371/340ea6bbe8e1e8a2edd857227a4c5786.png)

## 4. 权限模式与操作系统隔离是两层控制

当前官方文档列出的模式包括以下几种。是否可用、默认值和界面入口，还取决于版本、账号与组织配置。[权限配置](https://code.claude.com/docs/en/permissions)

| 模式值 | 主要语义 |
| --- | --- |
| `default` | 按权限规则询问；界面也称 Manual |
| `acceptEdits` | 自动接受文件编辑及部分常见文件操作 |
| `plan` | 以调查与规划为主，不编辑项目源码 |
| `auto` | 由后台分类器核查动作是否符合请求，减少常规询问 |
| `dontAsk` | 原本需要询问而未获预先允许的调用会被拒绝 |
| `bypassPermissions` | 跳过权限提示，仍受产品保留的限制与外部权限约束 |

`acceptEdits` 并非“每次写文件都弹窗”；`auto` 也不是简单把命令全放进白名单。跳过提示不会给进程额外的 root 权限，更不能取消远端服务的授权要求。

Plan 也不是操作系统沙箱。部分只读命令可运行，其他命令的审批或分类器行为由具体配置决定；MCP 工具与 hooks 还需要单独核查。若确实要求不能写入某个环境，应在执行账户、文件系统和网络边界上落实。

## 5. 用真实配置字段表达规则

项目共享设置通常放在 `.claude/settings.json`，个人项目覆盖放在 `.claude/settings.local.json`，用户配置则有自己的作用域。可以在 `/permissions` 中查看规则及来源。

下面是局部配置示例，展示官方 `permissions` 字段和工具匹配写法：

```json
{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}
```

规则按 deny、ask、allow 的优先级判断。还要看规则匹配的究竟是哪种工具：Read 的路径规则不能被解释为整机的文件访问策略；Bash 文本匹配也不能覆盖所有不同写法的同一程序。需要文件与网络的强约束时，再结合沙箱和执行环境。

提示词与项目文档用于引导行为，权限规则由运行时实施。把“禁止生产部署”写进 Markdown 很有用，但若部署凭据仍可被任意工具使用，文档本身不会形成强制边界。

## 6. 模式切换以当前状态为准

CLI 可用 Shift+Tab 切换模式，但不是所有安装都固定循环“Plan → Accept Edits → Auto → Bypass”。当前文档将基础循环与可选模式分开说明，自动模式和 bypass 的出现还有可用性与启动条件。[模式选择与切换](https://code.claude.com/docs/en/permission-modes)

启动复杂任务时，可以明确选择规划模式：

```bash
claude --permission-mode plan
```

先让它调查影响范围和验证方式，再审阅计划。进入执行阶段时，确认当前激活模式，特别是计划接受选项可能同时改变后续的权限模式。

一种适合团队的做法是把任务类别写入规范：一般开发、只读审查、依赖升级、发布准备分别使用什么环境与默认权限。规范应描述实际可检查的规则，避免依赖某一版界面的颜色或固定按键次数。

## 7. `/goal` 的完成条件要具体

官方命令表中的 `/goal` 用来设置一个条件，让 Claude 跨轮次继续工作，直到满足条件或因其他原因清除目标。该命令不自动提供仓库冻结、数据库事务、完整测试覆盖或发布保证。[命令参考](https://code.claude.com/docs/en/commands)

可以将目标写成可核对的结果：

```text
/goal 修复日期解析的空字符串错误：补充失败用例，完成最小实现，
运行相关测试并报告实际结果；保持公共接口与依赖不变。
```

明确停止条件后，还应给出验收依据。若测试环境缺失，应报告缺少什么；若需要的 API 只在生产可用，应先提出验证方案，而非把未执行的步骤标成完成。

大任务可以分阶段交付：调查、实现、验证、集成。阶段之间保留输入版本、变更和证据，方便后来的人判断工作是否仍对应当前代码。

## 8. 会话恢复与上下文压缩

几个常用操作可分别解决不同问题：

| 操作 | 用途 |
| --- | --- |
| `claude --continue` | 继续当前目录最近一次对话 |
| `claude --resume` | 选择或指定要恢复的会话 |
| `/context` | 查看上下文使用情况 |
| `/compact` | 用摘要释放上下文空间 |
| `/clear` | 开始空上下文的新对话 |
| `/model` | 选择当前会话模型 |

继续最近一次对话和从列表恢复特定对话不是同一件事。恢复之前，也要核对当前分支和文件状态；会话记得某个旧提交，不表示工作区仍停留在那里。[CLI 参考](https://code.claude.com/docs/en/cli-reference)

没有适用于所有模型和任务的官方“上下文 50% 立即失效”定律。可以根据上下文使用、任务阶段与信息密度安排压缩，并明确要求摘要保留目标、关键决定、未完成项和证据路径。

摘要会丢细节，重要事实仍应能回到文件、提交和报告中核实。更换模型也不必一概清空会话；应按实际功能与任务需求选择。

## 9. 项目说明写事实与入口

`CLAUDE.md` 适合记录项目背景、开发入口、编码约定和约束。当前官方文档也提供了 `AGENTS.md` 支持及相应版本、设置条件；在需要兼容不同会话时，可以通过 `CLAUDE.md` 的 `@AGENTS.md` 导入共享说明。[项目记忆](https://code.claude.com/docs/en/memory)

例如，仓库已有一份可信共享说明时，`CLAUDE.md` 可以包含：

```markdown
@AGENTS.md

## 本项目入口
- 开发与测试命令见 README 的 Development 一节。
- 修改公共接口前核对调用方和兼容要求。
- 提交报告时列出实际运行的命令与仍未验证的部分。
```

不宜把整份文档站点放入项目说明。稳定而高频的规则放在这里，较长的专题材料按需读取。新增指令也应走正常审阅，避免把第三方网页中的内容直接变成团队执行规则。

## 10. Skill 的有效入口是 `SKILL.md`

以项目共享 Skill 为例，目录可以这样组织：

```text
.claude/
└── skills/
    └── review-current-change/
        └── SKILL.md
```

下面是一份完整的最小 Skill 内容，用于手动请求检查当前修改：

```markdown
---
name: review-current-change
description: 检查当前修改的任务范围、回归风险与验证证据。
disable-model-invocation: true
---

读取当前任务说明、git diff 和项目测试入口。
输出：
1. 当前修改解决的问题与受影响模块。
2. 可复现的问题，附文件位置和触发条件。
3. 已实际运行的检查与结果；未运行项明确列出。
4. 仍需维护者判断的事项。

本次只交审查报告，不修改源码，不提交、不推送。
```

将文件放在上述项目路径后，可用 `/review-current-change` 调用。`disable-model-invocation: true` 控制模型不能自行触发该 Skill；它不会给步骤自动授予工具权限。[Skills 官方文档](https://code.claude.com/docs/en/skills)

Skill 可以附带脚本、参考文件和模板，但 Markdown 中的一步操作并不等于已经执行。可靠的报告应保留命令、结果和对应输入，而非只列一排 PASS。

## 11. 共享 Skill 时检查来源与同名冲突

项目、个人、企业和插件位置有不同作用域。同名覆盖顺序不能按“离项目越近越优先”猜测：当前文档列出的企业、个人、项目同名规则，是企业高于个人、个人高于项目。

跨工具复用时，可以维护一份共享内容，再让各工具按其支持的入口加载。目录名相似不代表所有工具都会自动扫描，也不代表扩展字段有相同语义。需要验证本机与目标运行环境实际加载的是哪份文件。

对于高频流程，宜把可确定执行的部分放进经过测试的脚本，把何时调用、输入约束和结果解释放进 Skill。脚本与文档都可以版本化；修改后用代表性任务验证，再推广给团队。

![项目文件组织示例](https://developer.qcloudimg.com/http-save/yehe-12805371/e6fdb3d36a656e2df1e16a7652f66b50.png)

## 12. MCP 把接入协议与业务服务分开

MCP 为主机与外部能力提供共同通信方式。工具、资源和提示模板等能力由 server 暴露，主机负责会话与模型侧交互。服务背后仍可能调用 HTTP API、数据库或本地进程。

传输方式要按当前规范与服务端支持选择。当前规范包含 stdio 与 Streamable HTTP；不能把旧式 SSE 写成所有远程接入的唯一选择。[MCP 传输规范](https://modelcontextprotocol.io/specification/latest/basic/transports)

协议不会自动提供可靠鉴权、租户隔离、审计存储或提示注入防护。MCP、直接 API 和 CLI 都需要核查真实权限、数据流和执行对象。凭据没有写进提示词，并不意味着本机子进程永远无法读取它。

工具描述是模型选择动作的依据，执行端仍应验证参数、资源身份和授权。一个工具自称“只读”，也应检查实际实现及凭据权限。

![MCP主机与外部能力](https://developer.qcloudimg.com/http-save/yehe-12805371/bd061e21cac0d93e0722786f6585812d.png)

## 13. 用官方 server 地址接入

添加远程 MCP 时，应从服务商当前文档获取端点与认证方式，不要凭名称猜 npm 包。Claude Code 官方文档给出的 Sentry 接入示例为：

```bash
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp get sentry
```

在交互会话中通过 `/mcp` 核对连接和认证。配置成功、已授权和某个具体业务查询成功，是三个可以分别失败的步骤。[MCP 接入指南](https://code.claude.com/docs/en/mcp)

存储位置也需要区分：项目共享配置在仓库根的 `.mcp.json`；local 与 user 作用域存储在 `~/.claude.json` 的对应位置。它们不能随意替换成 `~/.claude/mcp.json`，也不能把所有 `mcpServers` 配置塞进通用 settings 文件就视为生效。

对于项目共享 server，应检查配置本身是否可信。端点、命令和环境变量也属于可执行的接入配置；能进入仓库，不代表应该携带真实密钥。

## 14. CLI 与 MCP 按证据和维护成本选择

已有稳定 CLI 的任务可以直接调用；需要多个主机复用同一能力时，MCP 接入也可能方便。选择时可以比较结构化输出、鉴权范围、错误反馈、超时、幂等与审计，而非预设其中一种天然安全或必然便宜。

CLI 可以输出 JSON 并记录执行日志；MCP server 也可能没有持久化审计。模型看到的上下文开销还取决于工具定义是否按需加载、输出体积与运行框架，不能仅按协议 JSON 字段数量估算。

例如只读取 GitHub 问题列表时，可要求已有工具返回所需字段；要写评论或创建 PR，则要确认仓库、账号、目标对象与内容。发送超时之后，优先读回查证，避免重复创建。

## 15. SDK 使用已公开的查询接口

构建自己的程序时，应使用实际 SDK 接口，区分工具可用性、自动批准和拒绝规则。`allowed_tools` 用于自动批准指定工具，不能单独理解成“其余工具全部不存在”。

下面的 Python 示例使用 `query` 与 `ClaudeAgentOptions`。它限制本例内置工具列表，关闭额外 MCP 配置来源，并设置最大轮次；运行前需要按官方指南安装 SDK 并配置认证。[Python SDK 参考](https://code.claude.com/docs/en/agent-sdk/python)

```python
import asyncio
from claude_agent_sdk import ClaudeAgentOptions, query

async def main():
    options = ClaudeAgentOptions(
        tools=["Read", "Glob", "Grep"],
        allowed_tools=["Read", "Glob", "Grep"],
        permission_mode="dontAsk",
        mcp_servers={},
        strict_mcp_config=True,
        max_turns=4,
    )
    async for message in query(
        prompt="读取当前项目的 README，概括结构与测试入口，不修改文件。",
        options=options,
    ):
        print(message)

if __name__ == "__main__":
    asyncio.run(main())
```

这个查询会产生真实模型用量。工程接入时还要处理终止状态、错误、费用、日志脱敏和恢复。轮次上限限制的是代理回合，不等同于严格的单任务货币预算或完整的操作系统隔离。

## 16. Git 记录要能定位与回退

开始修改前检查分支和工作区，避免覆盖别人尚未提交的内容。一个任务可以对应一组聚焦提交；没有必要把每次模型尝试都立即提交到共享主分支。

审阅时至少查看当前差异与暂存列表：

```bash
git status --short
git diff --stat
git diff
git diff --cached --name-only
```

暂存时使用明确路径，并在提交前核对包含的内容。`.gitignore` 用于影响未跟踪文件的纳入，不会让已经进入历史的密钥自动消失，也不是禁止任意程序读取文件的访问控制。

共享历史中的错误提交通常可以通过新的反向提交撤销。若使用 `git revert --no-commit` 先准备反向改动，它会修改工作区和暂存区；验证后正常提交，不能把 `git revert --continue` 当作所有无冲突场景的固定下一步。`--continue` 用于继续已有 sequencer 操作。[git revert 文档](https://git-scm.com/docs/git-revert)

回退代码也不等于回退数据库或已经发出的消息。此类外部效果需要自己的补偿与恢复流程。

![分支保护流程](https://developer.qcloudimg.com/http-save/yehe-12805371/5aa15b83ee711f4b749569c5f97c0924.png)

## 17. 把验证绑定到最终提交

检查结果应能对应到接受时的源码版本。一次测试通过后又修改了相关代码，就需要判断哪些验证已经失效，而不能继续沿用旧绿灯。

一个很小的接受接口可以清楚表达这种对应关系：

```python
def revision_verified(revision, evidence):
    required = {"tests", "build", "review"}
    if not isinstance(revision, str) or not revision:
        return False
    if not isinstance(evidence, dict) or not required <= evidence.keys():
        return False
    return all(
        isinstance(evidence[name], dict)
        and evidence[name].get("revision") == revision
        and evidence[name].get("passed") is True
        for name in required
    )
```

这只是接收已有证据的纯函数，实际项目需要确定证据来自哪个可信检查器，并防止内容在验证后发生变化。报告“已经构建”时，也应带上真正的构建命令、结果与版本。

## 18. 发布流程与团队推广

生成的应用仍应走项目原有发布链路：可复现构建、测试、制品、预览或预发布、批准、正式部署与读回检查。每个阶段的命令和权限应与实际平台对应，不能假定所有平台都有相同的灰度和回滚能力。

数据库迁移要检查兼容性、数据恢复与版本顺序。健康检查也应区分存活与就绪：进程还在运行，不代表它具备处理业务请求所需的依赖。

团队试点可以按四个阶段推进：统一版本与基础权限，沉淀一条高频 Skill，接入一个实际需要的外部服务，再把验证和恢复纳入持续交付。阶段长短由问题和证据决定。

最终交接时，留下的是可定位的提交、真实检查结果、有效配置和已知限制。接手的人应能重新运行检查，也能发现与先前环境的差异。让这些证据持续可用，Claude Code 的产出就能更自然地进入团队已有的开发与维护流程。

![团队试点节奏示例](https://developer.qcloudimg.com/http-save/yehe-12805371/5827ed1125f0178d055d7e77e3799c42.png)

让 Claude Code 修改项目并不难。更需要设计的是一次完整的交付：它依据哪份需求工作，能调用哪些工具，修改如何检查，测试结果对应哪个提交，以及出错之后怎样恢复。

Claude Code 工程实践：权限、Skills、MCP 与可验证交付

从权限、Skills 与 MCP 的职责边界出发，组织 Claude Code 的任务执行、独立验证和交付证据；通过受控工具访问、明确停止条件和可重放检查支撑工程协作。

人工智能

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Claude Code 工程实践：权限、Skills、MCP 与可验证交付-腾讯云开发者社区-腾讯云

Claude Code 工程实践：权限、Skills、MCP 与可验证交付

Claude Code 工程实践：权限、Skills、MCP 与可验证交付

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐