最近在实践 Claude 的时候,发现很多同学还停留在“把提示词写得足够长”这一个阶段。其实 Claude 真正高效的生产力工具链是:提示词(Prompts)+ Projects + Skills + 连接器(Connectors) 四者组合起来的工作流。单独用提示词是“打字对话”,把它们组合成系统,才是可持续的 AI 工作流。
这篇文章我会用中英双语对照的方式,完整拆解这四块能力:从基础提示词写法讲起,再到项目级上下文管理,到可复用 Skill 的创建,最后落到连接器打通外部系统的工作流设计。适合刚接触 Claude 的开发者,也适合已经在用 API、但想把企业级工程化能力用起来的后端工程师。
1. 先从 Claude 与 AI 应用开发背景说起
1.1 Claude 是什么
Claude 是 Anthropic 推出的一款大语言模型产品,包含网页端(claude.ai)和 API 接入两种使用方式。它面向对话、写作、代码生成、知识问答、复杂推理等场景,尤其在长上下文理解、代码能力和安全对齐方面表现比较突出。
很多开发者最早接触 Claude,是因为在编码辅助场景下需要比传统大模型更稳定的复杂项目理解能力。Claude 的单次上下文窗口较长,可以在一个会话中放大量代码文件、技术文档甚至数据库建表语句,这让它很适合做项目级 AI 助手。
1.2 提示词、Projects、Skills、连接器的定位区别
在进入实操之前,我们先把四个概念的关系理清楚:
| 能力 | 一句话定位 | 解决的核心问题 |
|---|---|---|
| 提示词 / Prompts | 控制模型输出的指令模板 | 让模型知道你现在想要什么 |
| Projects | 一组会话共享的上下文容器 | 让模型始终知道你的项目背景 |
| Skills | 可复用的自定义能力包 | 让模型能调用你沉淀的工具逻辑 |
| 连接器 / Connectors | 与外部系统之间的集成通道 | 让模型能读写 GitHub、Google Drive 等外部数据 |
简单来说:
- 你只写提示词,每次对话都要重复背景。
- 用 Projects,背景只维护一次,多会话共享。
- 用 Skills,把高频动作沉淀成技能,模型“会干活”。
- 用连接器,让模型能和真实业务数据联动,工作流才能真正闭环。
下面每一部分都会给出中英双语的提示词示例,方便你在不同使用习惯中直接复制。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与版本说明
2.1 账号注册
进入 claude.ai 官网,使用邮箱注册即可。需要注意以下几点:
- 账号需要保持可用状态,如果遇到登录风控,按官方的验证流程处理。
- 网页端和 API 是两套体系:网页端看订阅套餐,API 看 Anthropic 控制台中的额度。
- 如果你是企业用户,建议直接申请 Anthropic 的 Organization 账号,方便团队成员统一管理 key。
2.2 API Key 获取
如果你要把 Claude 能力集成到自己项目中,需要先在 Anthropic Console 中创建 API Key:
- 登录 console.anthropic.com。
- 进入 API Keys 页面,点击 Create Key。
- 复制生成的 key,在服务端环境变量中保存。
示例:
bash复制export ANTHROPIC_API_KEY="sk-ant-xxxxx"
2.3 版本与模型选择
Claude 模型版本更新比较快,本文示例以常见环境为例,重点讲解配置思路而不是锁定某个版本的参数。
在 API 调用时,模型名需要根据官方当前文档进行调整。建议使用较新的 Sonnet 或 Opus 系列。例如:
python复制model="claude-3-5-sonnet-20241022"
具体版本名请以官网模型列表为准。这篇文章后续提示词与项目配置示例,在网页端和 API 端都适用,代码片段中的 model 参数可以替换成你当前环境可用的版本。
2.4 建议的工具链
- 网页端:claude.ai 直接使用。
- API 端:Python + anthropic SDK,或者 Node.js + @anthropic-ai/sdk。
- 版本管理:把提示词模板、Skill 目录、项目说明文件统一放入 Git 仓库,方便团队成员 Review。
3. 提示词工程:让 Claude 听懂你的指令
3.1 提示词基础结构
一条完整的提示词通常包含几个部分:
- 角色:告诉 Claude 它应该以什么身份回答。
- 任务:明确说明要做什么。
- 限制条件:包括格式、长度、语气、禁止事项。
- 上下文:给出输入数据或背景资料。
- 示例:给出输入输出样例,让模型对齐格式。
先看一个最基础的中英文对照提示词。
中文版:
text复制你是一名资深 Python 后端工程师。请审查下面的代码片段,找出潜在的异常处理问题,并给出修改建议。要求:
1. 先列出问题列表。
2. 每个问题给出严重程度(高/中/低)。
3. 最后给出修复后的完整代码。
代码片段:<在这里粘贴代码>
英文版:
text复制You are a senior Python backend engineer. Review the code snippet below, identify potential exception handling issues, and provide fix suggestions. Requirements:
1. List problems first.
2. Mark each issue with severity (High/Medium/Low).
3. Provide complete fixed code at the end.
Code snippet: <paste code here>
这里的关键点在于:先锁定角色(senior backend engineer),再给任务(review + fix),最后定输出结构(list + severity + fixed code)。 模型看到清晰的输出要求,就不会给你一段笼统点评。
3.2 角色设定与系统提示词
工程化使用中,我们通常不是一次性输入大段提示词,而是把“通用行为准则”放在 System Prompt 中,把每次不同的任务放在 User Message 中。
Anthropic API 中的 messages.create 接口本身就区分了 system 参数和 messages 参数。
python复制import anthropic
client = anthropic.Anthropic(
api_key="你的API Key"
)
resp = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
system=(
"你是一个专业的 API 文档助手。\n"
"你的任务是帮助开发者理解 REST API。\n"
"回答时必须包含:接口说明、请求示例、响应示例、错误码说明。"
),
messages=[
{"role": "user", "content": "请解释 POST /api/v1/orders 这个接口。"}
]
)
print(resp.content[0].text)
对应英文 System 版本:
text复制You are a professional API documentation assistant. Your task is helping developers understand REST APIs. Every answer must include: endpoint description, request example, response example, and error code explanation.
System Prompt 的特点是“一次性设定,持续生效”,所以适合放团队统一的回复风格、输出规范、禁止事项。
3.3 输出格式约束
在提示词工程中,最容易被忽略的是输出格式约束。模型如果没有固定输出结构,后面的解析脚本就会很痛苦。我们在提示词里可以要求模型输出 JSON,配合少量示例。
中文提示词:
text复制请把下面的用户需求解析成 JSON,字段包括:action、object、keyword、page。不要输出任何解释文字,只输出 JSON。
英文提示词:
text复制Parse the following user request into JSON with fields: action, object, keyword, page. Do not output any explanation text. Output JSON only.
如果你使用的是 API,更推荐使用 Anthropic 的工具调用(Tool Use)能力,让模型在结构化参数中输出:
python复制resp = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=2048,
tools=[
{
"name": "parse_request",
"description": "Parse user request into structured query",
"input_schema": {
"type": "object",
"properties": {
"action": {"type": "string"},
"object": {"type": "string"},
"keyword": {"type": "string"},
"page": {"type": "integer"}
},
"required": ["action", "object"]
}
}
],
messages=[
{"role": "user", "content": "帮我找一下上海地区的订单,翻到第二页。"}
]
)
工具调用比纯文本约束稳定很多,是工程化 ML 应用的核心方式,后面 Skills 部分的底层逻辑和它密切相关。
3.4 思维链与复杂推理
面对复杂任务,让 Claude 先做“内部分步推理”,再给结论,可以显著提升准确率。
Anthropic 官方推荐的“改写并精简”等技巧,我这里用一个更通用的思维链提示词示例。
中文版:
text复制请按以下步骤思考并输出:
1. 先列出这个问题涉及的前提条件。
2. 再分析每个前提条件对结果的影响。
3. 基于以上分析,给出最终结论。
4. 如果条件不足,请明确指出缺哪些信息。
问题:我们有一个订单表,订单状态有 pending、paid、shipped、completed。请问需要怎样的索引设计来支撑“按用户查询最近 30 天已完成订单”?
英文版:
text复制Please think step by step and output:
1. List the prerequisites involved in this problem.
2. Analyze how each prerequisite affects the result.
3. Provide the final conclusion based on the analysis.
4. If information is insufficient, explicitly state what is missing.
Question: We have an orders table with statuses pending, paid, shipped, completed. What index design is needed to support "query a user's completed orders from the last 30 days"?
提示词中的“先列出前提条件”很重要。它不只是让模型输出思路,而是强制模型检查自己有没有遗漏输入约束。对于索引设计这类依赖数据分布的任务,Claude 会主动提醒你补充数据量、读写比等参数。
3.5 提示词使用建议
实际工程里,提示词管理不要写在代码字符串里散落各处。给出目录设计:
text复制prompts/
system/
api_assistant.md
code_reviewer.md
templates/
parse_json.prompt
index_design.prompt
每条提示词文件统一使用 Markdown 维护,版本走 Git,评审走 Merge Request,替换走 CI 发布。
4. Projects:把上下文管理起来
4.1 Projects 解决的问题
当你反复给 Claude 讲同一个项目背景时,就已经出现上下文浪费了。Projects 是 Claude 网页端中的一种容器,它允许你把项目说明、参考资料、自定义指令集中放在一个“空间”里,里面的每个对话都自动共享这些上下文。
简而言之:Projects 是共享上下文,不是会话记录。
典型业务场景:
- 一个项目有自己统一的代码规范和技术栈说明。
- 一个团队有固定的输出模板和术语表。
- 一个产品需要长期围绕同一份需求文档和接口文档做分析。
4.2 创建 Projects
在 claude.ai 网页端中,进入 Projects 区域,点击 Create Project。你需要填写:
- Project Name:项目名称。
- Project Instructions:项目级自定义指令,相当于这个项目下的 System Prompt。
- Description:给模型看的项目背景介绍。
- 附加文件:可以上传代码、PDF、Markdown 等参考资料。
这里给出一个项目自定义指令的双语示例。
中文版:
text复制这是「订单交易分析平台」项目。我们的技术栈是 Python 3.12 + FastAPI + PostgreSQL。代码规范遵循 PEP 8。数据库表名前缀统一为 ord_。当用户提出 SQL 优化建议时,必须说明该 SQL 的执行计划分析思路。回答时请使用中文,术语可以保留英文。
英文版:
text复制This is the "Order Trading Analytics Platform" project. Our stack is Python 3.12 + FastAPI + PostgreSQL. Code style follows PEP 8. Database tables are prefixed with ord_. When providing SQL optimization advice, always explain the execution plan analysis approach. Use Chinese in responses, while technical terms may remain in English.
4.3 项目级自定义指令
项目级自定义指令是 Projects 的灵魂。它本质上是一个持久的 System Prompt,作用于该 Project 下的所有 Chat。
设置时建议覆盖以下方面:
- 项目背景:这个项目是干什么的。
- 技术约束:允许使用的依赖、语言版本、命名规则。
- 回答风格:代码、文档、SQL 的输出偏好。
- 禁止行为:哪些内容不输出,哪些操作必须先确认。
4.4 参考文档的附加
Projects 支持附加多种参考文件。这里有一个有效的文件组织思路:
text复制docs/
README.md # 项目总览
requirements.md # 需求文档
architecture.md # 架构说明
api_spec.yaml # API 定义
database_schema.sql # 数据库建表语句
注意一个问题:附加上去的文件会占用上下文 Token。如果你的项目文件很多,不要把整个仓库塞进去,只放那些“每次对话都要用到”的核心文件。详细代码尽量让 Claude 通过连接器去 Git 仓库按需读取,而不是一次性附带全部。
4.5 Projects 在 API 中如何体现
网页端的 Projects 功能在 API 层面没有完全一一对应的实体。在 API 中实现类似效果,有几种常用做法:
- 固定 System Prompt 模板:把项目说明作为 system 参数传入。
- 在每条 messages 前注入精简版项目上下文。
- 使用上下文文件的摘要:把 docs 目录切片后,每次检索相关片段再拼入请求。
如果团队需要项目级上下文复用,建议把这部分封装成一个上下文管理模块:
python复制class ProjectContext:
def __init__(self, project_id: str):
self.project_id = project_id
self.system_prompt = load_project_prompt(project_id)
def build_system_prompt(self) -> str:
return self.system_prompt
def build_user_message(self, question: str) -> str:
# 可以在这里注入项目相关的动态信息,例如当前版本、数据快照时间
return question
封装之后,调用层不用关心上下文拼接逻辑,团队协作也更清晰。
5. Skills:给 Claude 装上“可复用技能”
5.1 Skills 与提示词的区别
Skills 是 Anthropic 推出的“代理技能”机制。它的定位是:让 Claude 在特定任务场景下,知道如何拆解步骤、调用工具、组织产出,并把整套流程打包成一个可复用技能。
对比一下:
| 维度 | 提示词 | Skills |
|---|---|---|
| 作用方式 | 改变回复内容 | 改变执行流程 |
| 复用性 | 每次复制文本 | 目录化封装,整体调用 |
| 能否调用工具 | 文本层面描述 | 可以绑定真实脚本执行 |
| 适合场景 | 单轮问答、格式控制 | 多步骤任务、代码生成、数据处理 |
简单理解:提示词是“告诉模型怎么说”,Skills 是“告诉模型怎么做”。
5.2 从模板创建 Skill
Claude 提供了一些开箱即用的 Skill 模板,例如文档转换、前端组件生成等。如果你要创建自定义 Skill,核心是准备一个符合规范的能力包。
一个 Skill 在结构上通常包含:
- SKILL.md:描述技能用途、使用步骤与触发条件。
- scripts/:存放可执行脚本或工具。
- 参考资源:模板、示例文件。
创建自定义 Skill 时,Claude 会先在界面中生成一个 Skill 描述,然后你可以通过对话逐步完善它的执行逻辑。重点是把“模型要做什么”和“脚本要做什么”分开写清楚。
5.3 Skill 目录结构与文件规范
下面是一个自定义 Skill 的目录示例。
text复制my-skill/
├── SKILL.md
├── scripts/
│ ├── build_report.py
│ └── requirements.txt
└── assets/
└── report_template.xlsx
SKILL.md 的推荐结构:
markdown复制---
name: report_builder
description: 根据数据库查询结果生成业务周报 Excel 文件。
---
# Report Builder
## 使用场景
当用户需要基于订单表生成周报时,使用本技能。
## 步骤
1. 从数据库连接读取最近 7 天订单数据。
2. 使用 scripts/build_report.py 生成 Excel 文件。
3. 必要时对异常数据标注说明。
## 注意事项
- 读取数据库前必须确认用户有权限。
- 生成文件前先输出统计摘要。
对应英文版:
markdown复制---
name: report_builder
description: Generate a weekly business report Excel file based on database query results.
---
# Report Builder
## Use Case
Use this skill when the user needs to generate a weekly report from the orders table.
## Steps
1. Read order data for the last 7 days from the database connection.
2. Generate an Excel file using scripts/build_report.py.
3. Annotate abnormal data when necessary.
## Notes
- Verify user permissions before reading the database.
- Output a statistical summary before generating the file.
5.4 一个可运行的 Skill 示例
假设我们要做一个“CSV 数据清洗”技能。它需要接收一个 CSV 文件路径,输出清洗后的新 CSV。
SKILL.md:
markdown复制---
name: csv_cleaner
description: Clean a CSV file by removing duplicate rows, normalizing date formats, and converting empty fields to NULL.
---
# CSV Cleaner
## Steps
1. Parse the CSV file provided by the user.
2. Remove duplicate rows based on the primary key column.
3. Normalize date columns to YYYY-MM-DD.
4. Write the cleaned result to a new file with suffix _cleaned.
scripts/clean_csv.py:
python复制import pandas as pd
import sys
from pathlib import Path
def clean_csv(input_path: str, primary_key: str, date_columns: list[str]) -> str:
df = pd.read_csv(input_path)
# 去重
df = df.drop_duplicates(subset=[primary_key], keep="first")
# 日期规范化
for col in date_columns:
if col in df.columns:
df[col] = pd.to_datetime(df[col], errors="coerce").dt.strftime("%Y-%m-%d")
# 空字符串转 NaN
df = df.replace(r"^\s*$", pd.NA, regex=True)
output_path = str(Path(input_path).with_name(
Path(input_path).stem + "_cleaned.csv"
))
df.to_csv(output_path, index=False)
return output_path
if __name__ == "__main__":
if len(sys.argv) < 3:
print("Usage: python clean_csv.py <input> <primary_key>")
sys.exit(1)
input_file = sys.argv[1]
pk = sys.argv[2]
date_cols = sys.argv[3:] if len(sys.argv) > 3 else []
result = clean_csv(input_file, pk, date_cols)
print(f"Cleaned file saved to: {result}")
当用户在 Claude 对话中要求“清洗桌面上的 sales_data.csv,主键是 order_id”,Claude 会根据 SKILL.md 的指引调用脚本完成实际工作。
这个例子想说明一件事:Skills 的底层价值是把不可控的自然语言任务,转化成可控的脚本执行流程。 工程上最稳的组合是“Claude 负责理解和拆解指令,脚本负责执行确定性逻辑”。
6. 连接器工作流:打通外部系统
6.1 连接器解决了什么问题
很多团队在用 Claude 时遇到一个尴尬:模型很聪明,但它拿不到公司内部的代码、文档、数据表。
连接器(Connectors)就是用来解决这个问题的集成通道。它们允许 Claude 以授权方式读取外部系统中的数据,或触发外部系统执行动作。连接器的核心是“打通数据管道”,让模型不再只依赖用户手动粘贴内容。
常见连接器方向:
- 代码仓库:访问 GitHub / GitLab 仓库,读取代码、提交记录、Issue。
- 云盘与文档:访问 Google Drive、Notion 等文档库。
- 团队消息平台:读取 Slack 频道中的上下文。
- 数据库:通过受控连接器查询业务数据(需严格权限审查)。
- 自动化平台:触发工作流,例如在 CI/CD 或任务管理系统中创建任务。
6.2 常见连接器类型
在 Claude 中,连接器通常以产品界面中的“连接 + 授权外部应用”方式出现,也可以在 API 工作流中通过 MCP(Model Context Protocol)或自定义工具接入。
我建议把“连接器”分成两类理解:
- 界面级连接器:在 claude.ai 中直接连接 Google Drive、GitHub 等,方便个人和团队在对话中引用外部内容。
- API 级集成:开发者自己在代码中封装工具,让 Claude 具备调用内部 API 的能力。
在 API 侧,最通用的做法是定义工具。例如让 Claude 能查询订单数据:
json复制{
"tools": [
{
"name": "query_orders",
"description": "Query recent orders from internal order service. Requires date range.",
"input_schema": {
"type": "object",
"properties": {
"start_date": {"type": "string", "description": "Start date in YYYY-MM-DD"},
"end_date": {"type": "string", "description": "End date in YYYY-MM-DD"},
"status": {"type": "string", "description": "Order status filter"}
},
"required": ["start_date", "end_date"]
}
}
]
}
6.3 配置连接器的基本流程
无论哪种连接器,配置流程一般包含如下步骤:
- 确定数据源:你要打通哪个系统,解决什么场景。
- 权限申报:明确允许 Claude 读哪些范围,写哪些范围。
- 授权连接:在 Claude 或自定义应用发起 OAuth 授权。
- 设置触发规则:明确“什么情况下使用连接器”。
- 测试与审计:小范围测试并记录日志。
以 GitHub 连接为例,如果你在 claude.ai 中连接 GitHub:
- 第一步:点击添加 GitHub 连接。
- 第二步:选择授信的仓库范围(Private / Public)。
- 第三步:Claude 就能在对话中读取仓库内容并讨论代码。
- 第四步:如果启用了写入权限,需要额外校验确认,避免模型误改代码。
要记住:连接器永远只访问已授权的数据。 在内部系统中,最安全的做法是给连接器配置只读账号,并且限定仓库和目录范围。
6.4 连接器 + Projects + Skills 的组合工作流
连接器的真正威力,在于和 Projects、Skills 叠加。
假设这样一个场景:在一个“订单分析”Project 中,我们放入了项目说明和业务术语表。然后我们给这个 Project 配置了“订单数据库查询连接器”和“周报生成 Skill”。
工作流如下:
- 开发者新建一个 Claude 对话,对话自动加载 Project 上下文。
- 开发者说:“拉取最近 7 天已完成订单的数据,生成周报。”
- Claude 通过连接器读取数据库中的订单数据。
- Claude 匹配到周报生成 Skill。
- Skill 中的脚本对数据做清洗和统计。
- Claude 汇总结果,输出一份业务周报。
在这个过程中,每一步都不需要开发者手动贴数据、贴背景、重复解释指标口径。这就是 AI 工作流和单次提示词对话的区别。
如果是在 API 侧复刻类似流程,代码骨架如下:
python复制import anthropic
client = anthropic.Anthropic()
system_prompt = """
你是订单分析平台助手。当用户请求生成周报时:
1. 调用 query_orders 获取最近数据。
2. 使用 generate_report 工具生成报告。
3. 给出数据摘要,不输出原始完整数据。
"""
tools = [
{
"name": "query_orders",
"description": "查询订单数据,必须指定时间范围",
"input_schema": {
"type": "object",
"properties": {
"start_date": {"type": "string"},
"end_date": {"type": "string"}
},
"required": ["start_date", "end_date"]
}
},
{
"name": "generate_report",
"description": "生成周报 Excel",
"input_schema": {
"type": "object",
"properties": {
"report_date": {"type": "string"},
"metric": {"type": "string"}
},
"required": ["report_date"]
}
}
]
resp = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=4096,
system=system_prompt,
tools=tools,
messages=[
{"role": "user", "content": "请生成上周的订单周报。"}
]
)
print(resp.content)
代码中 query_orders 和 generate_report 需要你根据内部系统实际情况实现。Claude 会在回答中自动发起工具调用,然后你把自己的工具返回结果交给 Claude 继续汇总。
这样设计的好处是:
- 模型不需要知道数据库密码。
- 工具方法可以审计。
- 数据读取和报告生成逻辑可以独立测试。
- 权限控制集中在工具层。
7. 常见问题与排查思路
7.1 提示词不生效
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 设置的角色不起作用 | 指令放在 messages 中而不是 system 中 | 把长期约束移到 system 参数 |
| 输出格式始终不符合要求 | 没有给出格式示例 | 在提示词中加入带格式的 Input/Output 示例 |
| 模型总忘记限制条件 | 条件太多、优先级不明确 | 减少限制项,按重要性排序 |
排查思路:先用一个最小化提示词测试,确认是否是提示词本身有问题,而不是上下文干扰。然后把限制条件一条一条加回去,找到“打破平衡”的那一条。
7.2 Projects 上下文不生效
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 新建对话没有加载项目内容 | 忘记在当前对话中选择 Project | 确认对话右上角的 Project 标识 |
| 模型回答没有参考附加文档 | 文档内容太长被截断 | 精简附件,只保留高频核心文档 |
| 项目指令和用户指令冲突 | 优先级未定义 | 在项目指令中写明“用户指令不得违反项目安全约束” |
7.3 Skill 执行报错
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 脚本被调用但无日志 | 脚本没有标准输出 | 在脚本关键步骤添加 print / logger |
| Skill 使用不正确路径 | 工作目录和脚本目录不一致 | SKILL.md 中写清绝对路径或统一目录规范 |
| 权限拒绝 | 脚本没有执行权限 | 检查文件权限,必要时用 chmod +x |
排查清单:
- [ ] 脚本能否独立运行?
- [ ] 输入参数是否都能拿到?
- [ ] 输出结果是否在模型可访问范围内?
- [ ] SKILL.md 中的步骤是否和真实脚本逻辑一致?
7.4 连接器无法访问数据
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 连接器授权失败 | OAuth 权限范围过大或 token 过期 | 重新授权,并按最小权限申请 |
| 能连接但读不到数据 | 仓库目录或文档范围未授权 | 检查授权范围,确认路径 |
| API 工具调用无响应 | 工具超时 | 增加超时时间,并返回明确 error message |
8. 最佳实践与工程建议
8.1 把提示词当代码管理
提示词是会腐烂的。业务指标一变,技术栈一变,提示词里的描述就过期了。强烈建议把提示词模板放进 Git,配合 CI 做版本检查。每个项目维护一个 prompts/ 目录,命名用 动词_对象.prompt,例如 generate_sql.prompt、review_code.prompt。
8.2 权限与安全边界
这是最重要的一条。无论是连接器还是 API 工具,都要遵循最小权限原则:
- 能只读就不要开放写权限。
- 能限定仓库就不要让模型读取全部仓库。
- 能脱敏就不要让模型看到原始手机号和身份证。
- 所有写入、删除、发布类操作,必须二次确认。
8.3 日志与可观测性
给每次 Claude 请求记录日志,至少包含:
- 请求时间。
- 使用的模型。
- system / tools 版本。
- 输入输出摘要。
- 工具调用耗时。
- 错误码或异常原因。
Python 中可以在调用 SDK 前后记录结构化日志。
python复制import time
import logging
logger = logging.getLogger("claude_app")
def call_claude(client, messages, **kwargs):
start = time.time()
try:
resp = client.messages.create(
model=kwargs.get("model", "claude-3-5-sonnet-20241022"),
max_tokens=kwargs.get("max_tokens", 1024),
messages=messages,
tools=kwargs.get("tools"),
system=kwargs.get("system")
)
duration = time.time() - start
logger.info({"event": "claude_call_success", "duration": duration})
return resp
except Exception as e:
duration = time.time() - start
logger.error({"event": "claude_call_failed", "duration": duration, "error": str(e)})
raise
8.4 性能与成本优化
优化方向按影响从大到小排序:
- 减少无关上下文:Project 附件和 System Prompt 越长,Token 成本越高。
- 缓存静态内容:项目背景在系统初始化时加载一次,不要每次请求重新拼接。
- 合理使用模型分层:简单任务用小模型或快模型,复杂推理才用能力更强的模型。
- 工具结果精简:数据库连接器返回数据时,只返回模型需要的字段,而不是整张表。
8.5 从个人试用到团队标准化
个人试用往往是零散对话。上升到团队标准化,需要建立三个规范:
- 提示词评审规范:提示词写完后必须经过另一个工程师评审。
- Skill 发布规范:新增 Skill 要在测试对话中验证 5 次以上再发布到生产组织。
- 连接器审批规范:连接器只能由管理员开通,每次变更记录变更原因。
9. 总结与学习路线
这篇文章中,我们完整走了一遍 Claude 的能力体系:
- 提示词:掌握角色设定、系统提示词、输出格式约束、思维链四类写法。
- Projects:理解共享上下文容器的价值,学会用项目指令约束模型行为。
- Skills:理解“模型理解 + 脚本执行”的可复用技能模式,并通过 SKILL.md 组织逻辑。
- 连接器:理解外部数据接入工作流,把 Claude 与真实业务系统联动。
如果你正在往工程化方向进阶,下一步建议按顺序做这三件事:
第一,把你日常最高频的 5 个 Claude 使用场景模板化,沉淀成团队共用的提示词库。第二,选一个真正存在数据读取痛点的项目,接入第一个只读连接器,跑通“模型读数据 → 分析 → 输出报告”的闭环。第三,把重复性最高的任务封装成一个最小 Skill,让模型从“回答问题”升级成“完成任务”。
Claude 的提示词变化很快,模型版本也经常更新,但底层思路是稳定的:把背景放到项目管理,把能力做成独立技能,把数据交给受控连接器,最后用提示词指挥全局。 按这个思路去落地,你的 Claude 工作流会越来越接近一个真正的“AI 工程系统”,而不是一个偶尔好用的聊天框。
