AI 辅助编程2：Claude Code

2026-05-16 14:25:09

一、终端智能体运行机制基础

终端智能体是基于大语言模型的复杂控制系统，依赖三大技术支柱：自动化控制循环逻辑、标准化的工具交互协议，以及严密的安全权限隔离机制。

1. 控制循环

智能体的自主性建立在 “感知 → 思考 → 执行 → 反馈” 的持续循环之上。只要目标未达成或系统未强制停止，循环就会不断重复。

四个核心步骤：

步骤	说明
感知	收集系统环境状态：读取目录结构、配置文件（.csproj）、环境变量、Git 状态、剪贴板内容，并转为结构化文本。
思考	将数据与用户指令一同发送给 LLM，进行任务规划与决策，输出结构化的执行计划（明确要调用的函数）。
执行	客户端执行动作：调用 OS 文件接口、启动子进程（如 dotnet run）、根据 Diff 直接重写源码文件。
反馈	捕获执行结果：文件内容、终端输出、退出码（0 成功，非 0 失败）。若报错，则进入自我纠错闭环。

2. MCP 协议（Model Context Protocol）

MCP 是一个开源标准化通信协议，用于统一大语言模型与外部数据源、本地工具的交互方式。

架构组成

MCP Client（终端智能体），管理控制循环，与云端 LLM 通信，向 MCP Server 发送 JSON 请求。
MCP Server（本地/远程服务），将工具或数据源封装成标准接口，提供三类能力：
- 资源读取：读取静态数据（本地文件、企业知识库）。
- 工具调用：执行有副作用的操作（git commit、git push）。
- 提示词模板：提供预定义任务模板，规范业务流程。

核心价值：企业只需编写一个 MCP Server，任何支持 MCP 的智能体即可直接连接，获得运行内部测试用例的能力。

3. 权限管理

权限管理分为四个层级：

白名单操作（静默放行）：只读命令自动执行，无需确认，ls、dir、cat、type、git status。
拦截与授权（人工确认）：破坏性命令触发暂停，需用户输入 Y/N，curl、安装包、删除文件、复杂 Shell 脚本。
文件系统隔离：权限严格限制在启动时的项目文件夹内，无法使用绝对路径访问上级目录。
敏感数据脱敏：发送到云端前，使用正则扫描并替换密码、密钥为 [REDACTED_SECRET]。

二、Claude Code 简介

1. 工具定位

Claude Code 是 Anthropic 官方推出的命令行原生 AI 助手，定位为系统级独立执行者，而非“建议者”。

类型	特点
IDE 插件（建议者）	集成在编辑器侧边栏，被动响应，开发者主导，手动复制粘贴。
Claude Code（执行者）	运行在终端，直接创建文件夹、写代码、装依赖，不依赖特定 IDE。

2. 核心特性

打破 IDE 边界，直接与底层 Shell 交互：执行 ls/dir、全局 git 搜索、dotnet add package、读取配置文件。
自主决策与错误修复闭环，程序崩溃 → 自动捕获日志 → 分析原因 → 修改代码 → 再次运行，直至成功。
超长上下文优势，依托 Claude 系列模型的长上下文能力，可一次性处理数十万字的关联文件，完成大规模架构重构。

3. 收费模式

Claude Code 采用 按量计费，与网页版 Claude 独立。费用取决于每次交互消耗的 Token 数量。

API 按量计费（2026 年最新）

模型系列	输入价格	输出价格	适用场景
Haiku 4.5	$1.00 / 百万 Token	$5.00 / 百万 Token	快速读代码、单行修改、文本格式化
Sonnet 4.6（默认）	$3.00 / 百万 Token	$15.00 / 百万 Token	系统重构、前后端对接、新功能开发
Opus 4.6/4.7	$5.00 / 百万 Token	$25.00 / 百万 Token	复杂架构推演、深度逻辑分析、底层 Bug

提示词缓存优惠：同一项目中持续工作时，高频背景信息会被缓存，缓存命中部分费用可减免 90%。

上下文成本放大效应，终端智能体会自动读取海量关联信息，导致 Token 消耗激增。例如指令：

“尝试修复当前项目启动时的报错”

后台自动执行：

扫描整个项目目录结构

运行构建/启动命令

捕获数百行错误日志

读取多个关联源代码文件

一次自动化排错可能在几分钟内消耗十几万 Token。

高频用户成本控制策略

强制执行账单追踪，使用 /cost命令，查看当前会话耗时与预估开销。
切断历史记忆堆积，定期使用 /compact（压缩核心背景）或 /clear（彻底清空会话）。
引入高性价比模型，通过配置将底层模型替换为 DeepSeek V3、Qwen、MiniMax M2.7，成本可降至原来的 1/10 甚至更低。

4. 安装配置与第三方接入

官方原生安装流程：

# 检查环境 前置环境：Node.js ≥ 18.0
node -v
npm -v

# 全局安装
npm install -g @anthropic-ai/claude-code

初次启动：在项目根目录运行 claude，浏览器打开 Anthropic Console 完成授权。

为什么需要第三方接入？

痛点	说明
高昂试错成本	大型重构单次排错可能消耗数美分至十几美分。
网络与并发限制	新 API 账号有严格频率限制，快速循环可能被拒绝。

解决方案：保留 Claude Code 终端界面与本地执行能力，将“思考大脑”替换为性价比更高的第三方模型。

核心配置工具：CC Switch，CC Switch是跨平台可视化配置管理工具。

三步配置：

安装：下载对应系统的桌面客户端。
添加提供商：填写 Base URL 和 API Key。
配置应用与模型：选择 Claude Code 与目标模型，点击“启用”。

配置完成后，终端输入 claude，数据将被路由到第三方模型处理。

三、Claude Code 核心工作概念

1. 智能体循环的具象化

以指令为例：

“帮我在当前项目中添加一个黑夜模式的 CSS 样式文件，并应用到首页”

阶段	行为
感知	执行 ls，读取配置文件，确定项目结构、CSS 目录和首页文件名。
规划	生成执行清单：新增哪些 CSS 变量，修改哪些文件。
执行	创建 CSS 文件，修改首页引入样式。
验证	运行 npm run dev，检查终端是否报错。

2. 权限拦截机制

类型	操作示例
静默放行（只读）	读文件、看目录、git status、git diff
强制拦截（危险）	重写/删除源码、执行 curl、npm install、运行 Shell 脚本

Diff 确认示例：

:root {
  --bg-color: #ffffff;
  --text-color: #000000;
+ --bg-color-dark: #0d1117;
+ --text-color-dark: #e8e6e1;
}

授权选项：

Yes：接受本次修改
Yes, allow all：允许本会话所有编辑
No：拒绝，智能体将重新规划

3. 上下文管理策略

自动感知：启动时自动检测 Git 未提交变更，将其纳入高优先级上下文。
主动管理：
- 上下文超载会导致响应变慢、成本剧增或被拒。
- 完成任务后应使用 /compact 或 /clear 清理“内存”。

四、Claude Code 基本用法

1. 交互式 Shell 模式（主要工作流）

cd your-project
claude

交互逻辑：支持持续对话，后续指令基于上文记忆。
退出方式：输入 /quit、/exit，或双击 Ctrl + C。

2. 单次命令执行模式

无需进入交互界面，适合自动化脚本：

claude -p "检查当前项目根目录下的 README.md 文件，修正里面所有的拼写错误，完成后直接保存。"

3. 代码 Diff 确认机制

颜色	含义
🔴 红色（-）	即将删除或修改的旧代码
🟢 绿色（+）	即将新增或替换的新代码
⚪ 无色	上下文参照代码

4. 常用核心命令

命令	功能说明
/init	扫描项目，生成 CLAUDE.md 架构说明、构建命令、规范）。
/model	运行时动态切换模型（Haiku ↔ Sonnet ↔ Opus）。
/plan	开启规划模式，先输出步骤清单，确认后再写代码。
/compact	压缩历史记忆，提取核心摘要，释放上下文空间。
/clear	彻底清空当前会话记忆，适合切换无关任务。
/cost	显示 Token 用量、耗时与精确美金预估。

五、Claude Code 实战

1. 实例：纯前端 HTML/JS 生成与迭代

演示 Claude Code 如何仅凭自然语言需求，自动生成静态资源文件并执行增量逻辑修改。

步骤1：环境初始化与进入交互模式

创建空白工程目录 claude-frontend-demo，在终端中输入核心命令：claude。终端智能体接管当前命令行界面，进入等待指令状态。

步骤2：下达初始生成指令，输入自然语言指令，要求创建一个待办事项页面：

创建一个包含待办事项功能的 index.html 文件。要求页面必须居中显示，
包含一个文本输入框和一个添加按钮。下方是一个列表用于展示待办事项。
整体视觉风格必须强制使用纯黑背景、白色文字的暗黑模式 CSS，
且样式代码直接写在 HTML 文件的 head 标签内。

步骤3：观察智能体执行流程与授权

Claude Code 使用 write_file工具在当前目录创建物理文件，并展示完整代码结构。审查后授权创建，即可在浏览器中看到符合暗黑模式的待办事项列表页面。

步骤4：下达增量修改指令

在确认基础功能后，进行交互升级：

在当前的 index.html 基础上，将原本静态的待办事项列表，升级为支持鼠标拖拽排序的结构。
用户需要能够通过长按并拖动列表项来改变它们的先后顺序。
请保留原有的暗黑模式样式不变。

步骤5：理解代码差异视图与增量验证

这一次展示的是标准的彩色代码差异视图：

- const items = document.querySelectorAll('.todo-item');
- // 静态列表渲染逻辑
+ // 拖拽排序逻辑
+ let draggedItem = null;
+ items.forEach(item => {
+   item.draggable = true;
+   item.addEventListener('dragstart', handleDragStart);
+   item.addEventListener('dragover', handleDragOver);
+ });

智能体自动完成读取旧文件、理解上下文、重新生成代码、对比差异并写入硬盘的全部工程链路。

2. 实例：.NET 应用的自我运行与验证

演示智能体在多文件项目结构中工作，并自行执行系统构建命令来验证代码。

步骤1：创建空白控制台项目，ClaudeDotnetDemo
步骤2：唤醒智能体并下达多文件结构指令，在项目根目录打开终端进入 Claude Code 交互模式，输入 /init 初始化项目。Claude Code 会读取 .csproj 确认框架版本，生成 CLAUDE.md 记录识别到的内容。然后输入指令：

请实现一个极其简单的员工薪水计算程序。要求如下：
1. 新建一个独立的类与文件 Employee，包含 Name 属性和双精度浮点数类型的 BaseSalary 薪水属性。
2. 在 Program.cs 中，实例化三个具体的员工对象，分别为他们设置不同的薪水数值。然后在计算并输出这三个人的薪水总和。
3. 请自行尝试运行该项目，以验证最终的输出结果是否符合预期。

步骤3：解析多步骤执行与系统命令调用
- 创建独立文件阶段：调用文件写入工具，创建 Employee.cs新文件，展示完整类代码，授权创建。
- 修改现有文件阶段：对 Program.cs展示修改差异视图：删除默认代码（红色），替换为实例化和计算逻辑（绿色）。
- 系统级命令自主执行阶段：智能体在后台自动调用操作系统命令行执行工具，发送 dotnet run 命令。执行编译运行属于可能改变系统进程状态的操作，需确认授权。
- 捕获输出与结果反馈：智能体自动捕获控制台输出流（Stdout），在终端输出最终的综合报告。
步骤4：关键结论，Claude Code 不仅是“文本生成器”，它具备深刻的工程理解能力：
- 遵守面向对象编程规范，跨文件组织代码
- 熟练运用官方构建工具执行程序编译与结果校验
- 打通了从“代码编写”到“本地运行测试”的完整研发链路

提示：每一个步骤的任务完成后可以先执行 Clear，让上下文保存干净

3. 实例：自主发现程序 Bug 与修复

演示智能体基于标准错误输出流，自主完成分析异常、定位代码并修复问题的完整自动化。

步骤1：手动植入包含隐患的基础代码，创建测试项目 ClaudeBugDemo，人为植入以下代码：

int[] numbers = { 10, 20, 30, 40, 50 };
int sum = 0;

// 错误逻辑：循环条件使用了小于等于 (<=) 而不是小于 (<)
for (int i = 0; i <= numbers.Length; i++)
{
    sum += numbers[i];
}

Console.WriteLine("数组所有元素的总和是: " + sum);

注意：这段代码会引发数组越界异常：对于长度为 5 的数组，最大合法索引是 4，但循环条件使用 <=会导致 i=5时仍进入循环。

步骤2：下达自主排查与修复指令

运行项目，并收集产生的任何报错日志，并进行修复。
修复后，必须再次运行该项目进行复测。
如果还有错误，继续修复并运行，直到程序能够完美执行并输出最终正确的总和结果。
最后向我报告你修复了什么。

步骤3：智能体自主纠错的完整闭环

[初次执行 dotnet run]
        ↓
[捕获崩溃日志：数组越界异常]
        ↓
[深度思考定位：循环条件错误]
        ↓
[精确修改代码：<= → <]
        ↓
[二次执行验证：输出正确结果]

最终修复结果：将 <= 替换为 <，程序输出“数组所有元素的总和是: 150“。

4. CLAUDE.md 工程级规范注入

通过项目规约文件，强制向智能体注入团队代码规范与操作边界。

核心机制：当在项目根目录启动 Claude Code 时，客户端会在执行任何网络请求前扫描 CLAUDE.md 文件，并将其内容自动拼接在每次发送给云端的自然语言指令之前。这个过程对用户是隐蔽的。

- 强制性地为 AI 确立当前项目的操作边界和代码规范
- 可提交到 Git 版本控制系统，让团队每个开发者应用一致的约束

步骤1：创建规约文件，创建 CLAUDE.md 文件，填入特定的强制规范：

# 项目级人工智能开发规范

## 1. 变量命名强制规范
所有局部变量必须使用大写蛇形命名法（如：MAX_RETRY_COUNT）。

## 2. 日志输出强制规范
禁止使用 Console.WriteLine，必须调用 CustomEnterpriseLogger.RecordLog("你的信息");

步骤2：下达基础开发指令，输入一个简单且没有任何额外约束的常规指令：

请用 C# 语言创建一个名为 DataProcessor.cs 的文件。
写一个方法，接收两个整数参数，计算乘积，输出到控制台。

步骤3：观察执行结果，即使指令中完全没有提到任何规范要求，生成的代码也会无条件服从 CLAUDE.md 中的设定：

- int result = a * b;                          // 被禁止
- Console.WriteLine(result);                  // 被禁止
+ int CALCULATION_RESULT = a * b;             // 强制大写蛇形
+ CustomEnterpriseLogger.RecordLog(CALCULATION_RESULT);  // 强制日志类

5. 挂载 MCP 服务扩展能力

通过 MCP 协议接入外部数据库服务，让智能体安全地读取表结构并生成代码。

Claude Code（终端智能体）
        ↓ MCP 指令
MCP 服务端（本地中间件）
        ↓ SQL 查询
MySQL 数据库（数据存储）

数据库账号密码仅保存在本地 MCP 配置中，云端模型只接收表结构文本。

步骤1：数据库环境前置准备

-- 创建测试数据库
CREATE DATABASE IF NOT EXISTS TestCompanyDB
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

USE TestCompanyDB;

-- 创建员工表
CREATE TABLE IF NOT EXISTS employees (
    id INT AUTO_INCREMENT PRIMARY KEY COMMENT '员工唯一标识',
    name VARCHAR(50) NOT NULL COMMENT '员工姓名',
    department VARCHAR(50) NOT NULL COMMENT '所属部门',
    base_salary DECIMAL(10, 2) NOT NULL COMMENT '基础薪资',
    hire_date DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '入职时间'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='员工基础信息表';

-- 插入测试数据
INSERT INTO employees (name, department, base_salary) VALUES
('张三', '研发部', 15000.00),
('李四', '产品部', 12000.00),
('王五', '设计部', 11000.00);

步骤2：注册 MCP 服务

claude mcp add mysql-local \
  -e MYSQL_HOST="192.168.2.5" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="123456aa" \
  -e MYSQL_DB="testcompanydb" \
  -- npx -y @benborla29/mcp-server-mysql

# 验证连接
claude mcp list

步骤3：跨系统查询与代码生成

请通过 mysql-local 数据库连接，查询 employees 表的完整表结构。
然后生成对应的 C# 数据实体类属性。

终端输出展示：

Calling tool: mysql-local_query — 触发外部工具调用

MCP 服务端连接 MySQL，返回表结构文本

智能体将 MySQL 类型（VARCHAR, DATETIME）转换为 C# 类型（string, DateTime）
// 生成的 EmployeeEntity.cs
public class EmployeeEntity
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public string Department { get; set; } = string.Empty;
    public decimal BaseSalary { get; set; }
    public DateTime HireDate { get; set; }
}

六、Agent Skills 介绍

Agent Skills 一种轻量级、开放的格式规范，通过注入专业领域知识和工作流程来扩展智能体能力。

1. 物理架构与目录规范

Agent Skill 表现为遵循特定层级规范的文件夹：

skill-name/
├── skill.md           # 核心定义文件（元数据 + 指令集）
├── references/        # 参考资料目录（API 文档、开发手册）
├── scripts/           # 可执行脚本目录（Python/Node.js/Shell）
└── assets/            # 资源文件目录（模板文件等）

SKILL.md（必选）：技能的大脑，包含元数据（名称和描述，决定触发条件）和指令集（详细步骤规范）
scripts/：存放可执行代码，将概率性语言生成转化为确定性程序执行
references/：存放 API 文档、内部开发手册、合规指南等长文本资料
assets/：存放静态资源文件，如模板文件

2. 核心运行机制：渐进式加载

发现阶段（极低开销）：仅读取技能的“名称”和“简短描述”，构成“能力清单”。不会读取完整内容。
激活阶段（精准匹配）：当任务与技能描述高度契合时，才将 SKILL.md 完整指令加载到运算上下文。
执行阶段（按需拓展）：需要什么才加载什么 — 按需读取 references/ 文档或调用 scripts/ 脚本。

3. 为什么我们需要 Agent Skills

从“玩具阶段”迈向“工业化生产阶段”的必然要求。

破解“大一统”提示词工程的维护灾难：将所有规则塞进全局上下文会导致：
- 注意力稀释：大模型处理超长文本时存在“中间迷失”现象，无关信息干扰会降低核心任务的理解精度。
- 成本与延迟膨胀：每次简单对话都携带庞大规则库 = 巨大资源浪费 + 推理延迟。
解决方案：Agent Skills 模块化设计 — 处理前端任务时只激活前端技能，处理后端时只激活后端技能。
将自然语言转化为确定性操作，AI 模型本质上是基于概率的预测引擎。没有技能约束时，“清理测试环境的过期数据”这样的指令，智能体可能每天用不同的方式执行。

解决方案：通过在 SKILL.md 中编写强制性的执行流，智能体从“自由发散的解决问题”转变为“严格执行标准化作业程序的高级自动化执行器”。
填平通用模型与企业私域架构之间的信息鸿沟，通用模型在遇到企业内部自研组件时会产生“逻辑幻觉”，凭空捏造不存在的 API 调用方法。

解决方案：将内部开发手册、接口参数要求打包为 Agent Skill。AI 从“懂通用知识的实习生”蜕变为“精通公司底层架构的资深工程师”。

4. Agent Skills 的三大核心优势

构成下一代终端智能体标准规范的基石。

精准捕捉与封装领域专业知识，将极其专业、小众且复杂的领域知识，转化为可被机器重复调用的能力资产。
- 隐私数据合规检查技能
- 定制化数据分析管道
- 品牌视觉规范封装
高级专家的经验以数字化形式无限复制，在开发流程的最前端直接作用于代码生成。
打造高度一致且可审计的可重复工作流，将多步骤任务转化为一致、稳定、完全可审计的操作流水线。

拉取代码 → 单元测试 → 安全扫描 → 配置比对 → 生成日志 → 提交代码 → 调用部署 → 发送回执

打破平台壁垒的跨产品复用能力，作为完全开放的标准，获得广泛生态支持：
- 一次构建技能包
- 可在 Claude Code / Cursor / GitHub Copilot / 其他兼容客户端中使用
“一次构建，全平台跨终端复用” — 摆脱对单一 AI 工具厂商的技术锁定，成为企业在 AI 时代构建、沉淀和分发数字化研发经验的核心基础设施。

七、Claude Code 中使用 Agent Skills

Claude Code 与 Agent Skills 由同一家公司推出，在底层架构上实现了对 Agent Skills 开放规范的原生深度支持。接下来讲解 Claude Code 如何发现、加载、安装和管理这些技能模块。

1. Claude Code 的技能发现机制

进入 Claude Code 交互模式时，它会在后台静默执行初始化扫描，固定寻找当前目录下是否存在 .claude/skills/ 文件夹。

目录扫描标准：

如果存在该文件夹，Claude Code 遍历其内部每个子文件夹。
绝不深度读取代码脚本或参考文档，仅打开 SKILL.md 提取“名称”和“简短描述”，保存到会话内存清单中。

渐进式加载的终端表现：

假设存放了十个技能，其中一个是“数据库结构迁移技能”。

当你要求“写一个前端登录页面”时，终端不会出现数据库技能提示；
但当你说“生成数据库表结构迁移脚本”时，匹配触发，技能被激活加载。

工作流程：

用户需求 → 语义匹配 → 激活 SKILL.md → 加载指令集 → 执行任务

2. 技能商店与生态管理

随着 Agent Skills 社区发展，我们不需要从零编写所有 Skill。Claude Code 提供标准化命令来安装、管理和更新外部技能插件。

安装策略对比：

类型	说明
全局安装	技能存放在 %USERPROFILE%.config\claude\skills。适用于个人通用开发习惯和提效工具，如“Markdown 美化技能”或“网络搜索技能”。任意项目目录均可调用。
项目级安装（推荐）	Skill 存放在项目根目录 .claude/skills/。涉及特定业务逻辑、团队 API 规范或部署流程的技能必须采用此方式，确保 Skill 成为项目代码库的物理组成部分。

本地离线内置技能：安装 Claude Code 客户端时已附带官方维护的离线核心 Skills，通过 /plugin 命令管理，包含离线插件市场。

远程仓库安装实战（以 PPT 幻灯片技能为例）：

# 添加插件市场
/plugin marketplace add zarazhangrui/frontend-slides

# 使用 /plugin 找到插件并安装
/plugin

# 或者直接 git 克隆到技能目录
git clone https://github.com/zarazhangrui/frontend-slides.git ~/.claude/skills/frontend-slides

更多优质智能体技能集合：https://github.com/VoltAgent/awesome-agent-skills

3. 技能资产的版本控制与团队共享

将 Agent Skills 引入企业级开发，终极目的不仅提升个人效率，更要在团队内部实现标准统一和经验沉淀。

核心原则：与业务代码同源管理，技能文件保存在 .claude/skills/。绝对不能将其加入 .gitignore。必须像对待核心业务源代码一样，执行 git add 和 git commit，推送到远端仓库。

团队协作流程：

新人入职 / 新环境：执行 git clone 拉取项目代码，.claude/skills/ 及所有技能包一并下载到新环境。
零配置启动：不需要查阅冗长文档，不需要手动执行安装命令。只需在项目根目录输入 claude 唤醒终端智能体。
团队一致性：无论资深开发还是实习生，在同一项目下使用 Claude Code，AI 助手拥有完全一致的“知识背景”和“能力”。

八、SKILL 实战

1. 自定义 Skill 的核心设计理念

**根本原则：**编写自定义技能并不是在进行简单的文字创作，而是在进行一种面向 AI 行为的系统级编程。我们是在设计一个具有严密逻辑边界的执行模块。

从发散性意图到确定性状态机，大语言模型本质上是基于概率的文本预测引擎，赋予了 AI 极强的创造力和泛化能力（发散性）。然而软件工程追求绝对确定性。

❌ 错误示例：角色扮演（发散性意图）

"你现在是一个拥有二十年经验的资深前端架构师。请以极其严苛的眼光审查代码，找出所有性能问题和安全隐患，给出优雅的重构建议。"

充满了模糊形容词（“资深”“严苛”“优雅”），模型需要在概率空间中猜测什么是“优雅”。

正确示例：确定性状态机

步骤 1: 检查明文硬编码密码/密钥。发现 → 立即停止并输出警告。
步骤 2: 逐行检查循环中的数据库查询（N+1问题）。
步骤 3: 检查变量命名，不符合驼峰 → 提供修改建议。
步骤 4: 汇总为三列 Markdown 表格输出。

明确的触发条件和强制顺序，模型只需严格执行硬性规定。

最小权限与单一职责原则：一个技能文件夹只专注解决一个极其微观、具体的问题。

拆分示例：不要编写“项目初始化规范”技能，应拆分为：

标准化 README 文件生成器（仅负责生成说明文档）
前端工程目录结构脚手架（仅负责创建文件夹结构）
项目基础依赖包配置文件生成（仅负责编写依赖清单）

最小权限：严守系统执行的安全边界。

示例 — 日志分析技能

“你仅被允许读取 /var/logs/ 目录下 .log 纯文本文件。绝对禁止文件写入、修改系统配置、读取含 password 或 config 的文件。”

精准的元数据设计，在“发现阶段”，智能体唯一能读取的是每个技能的元数据（Name + Description）。调度引擎通过语义匹配 Description 决定是否激活。

问题	描述	后果
❌ 宽泛描述	“这是一个强大的前端代码辅助工具，帮助开发者编写更好的前端代码。”	任何“前端”“代码”相关词汇都会触发，导致技能劫持。
❌ 狭隘描述	“当用户输入操作码 Execute-Deploy-Pipeline-v3 时触发。”	除非死记硬背内部操作码，否则智能体永远不会触发，技能失效。

结构化描述的黄金法则

"当且仅当在 [特定开发环境或前置条件] 下，
用户明确要求进行 [极其具体的执行动作]
处理 [特定的目标对象] 时，激活此技能。"

正确示例：

“当且仅当用户提供了一段 JavaScript 或 TypeScript 代码，并且明确要求进行‘性能审查’、‘内存分析’或‘查找内存泄漏’时，激活此技能。不要在常规的 UI 样式修改任务中触发此技能。”

防御性编程：异常流与边界处理。

大语言模型有一个固有缺陷：被训练为极力满足用户指令的**“讨好型人格”。当任务缺乏必要数据时，模型不会拒绝执行，而是“脑补”或“捏造”缺失信息——即“数据幻觉”**。

典型幻觉场景

技能：“根据表名生成数据库实体类”。用户只输入“帮我生成一个实体类代码”，忘记提供表名。

如果不防御，智能体会凭空捏造一个 User或 Product表名，生成完全无用的代码。

防御机制：“暂停与反问”，在状态机指令流中，第一步永远是“输入参数校验”：

检查用户输入是否包含目标数据库表的准确名称
如果未提供表名，立即停止当前执行流程
绝对不能自行猜测、虚构或使用默认表名
向用户输出反问提示，等待补充输入

2. 实战演练：标准化 README 生成器

mkdir -p .claude/skills/readme-generator

第二步：编写 SKILL.md

---
name: readme-generator
description: 当且仅当用户明确要求创建、编写或初始化项目的 README 说明文档时触发此技能。不要在其他普通的文本翻译或代码生成任务中触发。
---

当你被要求生成 README 文件时，必须严格依次执行以下步骤：

1. 文件格式约束：必须使用标准的 Markdown 语法生成所有文本内容。
2. 核心结构约束：生成的内容中，必须包含且仅包含以下两个一级标题结构：
   - `# 项目介绍`
   - `# 快速启动`
   不允许自行虚构或添加其他额外的一级或二级标题。
3. 版权声明约束：在最后一行，必须原封不动地输出：
   `Copyright 2026 内部测试版权所有`
4. 执行保存约束：将内容保存为项目根目录下的 `README.md` 文件。

终端验证

$ claude
Claude Code v1.0 — 已加载 2 个技能

> 帮我生成一个当前项目的 README 文档。

⚡ 加载技能: readme-generator
正在根据技能指令生成 README.md ...

┌─ README.md ─────────────────────────┐
│ # 项目介绍                          │
│                                     │
│ # 快速启动                          │
│                                     │
│ Copyright 2026 内部测试版权所有      │
└─────────────────────────────────────┘

确认写入? (yes/no) yes
✓ 文件已保存: README.md

验证要点：

渐进式加载：终端出现 Skill 加载提示，证明调度引擎成功捕捉意图

强制约束生效：尽管输入没有提任何格式要求，生成内容必然只包含两个标题

版权声明一字不差地附带在末尾

3. 在 SKILL 中集成可执行脚本

大语言模型本质上是预测文本的算法，它并不真正"计算"数学题，也不能真正"执行"系统级操作。纯文本指令在这些场景下极其危险——模型可能"幻觉"出完全错误的结果。

脚本目录的作用与定位：scripts/ 目录专门存放需要在本地实际运行的代码文件：Python、Node.js、Shell、.NET 程序等。

要求绝对确定性的计算：哈希值计算、加解密数据、精确的财务数据统计
调用外部系统或内部工具：连接私有数据库、调用内部微服务接口、执行构建打包工具
复杂的文本/文件处理：大规模正则替换、解析专有文件格式

工作机制与交互协议：

智能体理解意图 → CLI 参数传递 → 本地脚本执行 → 捕获 stdout → 反馈用户

4. 实战演练：SHA-256 哈希值计算器

场景设定：安全审计中需要计算文件的 SHA-256 哈希值。大语言模型无法凭空计算真实文件的哈希值，极有可能“幻觉”出完全错误的乱码。我们需要强制调用本地 Python 脚本获取真实结果。

mkdir -p .claude/skills/hash-calculator/scripts

scripts/hash.py

import sys
import hashlib

def calculate_sha256(filepath):
    """计算文件的 SHA-256 哈希值"""
    sha256_hash = hashlib.sha256()
    try:
        with open(filepath, "rb") as f:
            for byte_block in iter(lambda: f.read(4096), b""):
                sha256_hash.update(byte_block)
        return sha256_hash.hexdigest()
    except FileNotFoundError:
        return f"错误：未找到文件 {filepath}"
    except Exception as e:
        return f"错误：计算哈希值时发生异常: {e}"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("用法: python hash.py <文件路径>")
        sys.exit(1)

    target_file = sys.argv[1]
    result = calculate_sha256(target_file)
    print(f"[{target_file}] 的 SHA-256 哈希值为:\n{result}")

第二步：编写 SKILL.md 整合脚本调用

---
name: hash-calculator
description: 当且仅当用户明确要求计算某个文件的 SHA-256 哈希值（或校验和）时触发此技能。
---

当你被要求计算文件的 SHA-256 哈希值时，必须严格执行以下步骤：

1. **绝对禁止自行猜测**：你绝不能使用内部知识去猜测或生成任何哈希值。
2. **执行本地脚本**：执行以下命令调用专用计算脚本：
   `python scripts/hash.py <目标文件路径>`
3. **输出真实结果**：捕获脚本输出，原封不动反馈给用户。如果脚本报错也反馈错误信息。

终端运行与调用验证

> 请帮我计算一下当前目录下 test.txt 文件的 SHA-256 哈希值。

⚡ 加载技能: hash-calculator
根据技能指令，我将调用本地脚本计算哈希值...

⚠ 将要执行: python scripts/hash.py test.txt
  授权此操作? (y/n) y

[test.txt] 的 SHA-256 哈希值为:
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

执行闭环四步验证：

技能激活：终端显示加载提示，证明调度引擎匹配成功
安全授权拦截：终端暂停，弹出授权提示——关键安全机制
脚本执行与结果捕获：后台启动 Python 进程，捕获标准输出
真实结果输出：包含真实哈希值，而非模型幻觉的乱码

总结：通过脚本集成，技能不再仅是约束文本生成的模板——它变成了一个可以无限扩展功能的系统级插件引擎。只要在 SKILL.md 中定义好清晰的调用协议，智能体就能安全、稳定地执行关键任务，彻底消除“人工智能幻觉”在关键计算领域的风险。

分类: 读书笔记
标签: AI

XIAOSUO 记录个人学习的足迹

AI 辅助编程2：Claude Code

一、终端智能体运行机制基础

二、Claude Code 简介

三、Claude Code 核心工作概念

四、Claude Code 基本用法

五、Claude Code 实战

六、Agent Skills 介绍

七、Claude Code 中使用 Agent Skills

八、SKILL 实战

About

随笔档案

随笔分类

随笔标签

推荐随笔

最新随笔

收藏链接