Claude Code系统提示词工程化指南：从CLAUDE.md到自定义提示词-Seo优化-塔城地区网站建设公司

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Claude 随心用，限时 5 折。 👉 点击领海量免费额度

你肯定遇到过这种情况：对着 Claude 或者 ChatGPT 输入一个需求，得到的回答要么过于笼统，要么完全跑偏，要么就是格式混乱，需要你反复追问、修正、补充细节。折腾半天，最后发现，真正花在思考和解决问题上的时间，可能还不如跟 AI 来回拉扯的时间多。

问题出在哪？很多时候，不是模型能力不行，而是我们给的“指令”——也就是 Prompt——不够清晰、不够结构化、不够贴近模型的理解方式。这就像你让一个刚入职的新人去完成一项复杂任务，如果只给一句“把这个项目搞定”，他大概率会懵。但如果你能给他一份清晰的任务清单、一份过往的优秀案例、一套标准的操作流程，结果就会大不一样。

最近，一个在 GitHub 上收获了超过 4.4 万颗星的“提示词金矿”项目，为我们揭示了顶级团队是如何系统化地编写 Prompt 的。它不是一个简单的“提示词大全”，而是一套关于如何为 Claude Code 这类 AI 编码助手定制“系统提示词”的完整工程化方法论。这套方法的核心，不是教你几个“魔法咒语”，而是让你理解 AI 助手的“工作说明书”应该如何撰写，才能让它从一开始就走在正确的轨道上。

这篇文章，我们就来深入挖掘这个“金矿”。我不会只给你一堆现成的提示词模板，而是带你理解背后的设计逻辑：为什么一个优秀的系统提示词需要分层？如何根据你的使用场景（是 CLI 工具、聊天助手还是自动化 Agent）来定制不同的“身份”和“权限”？如何将一次性的成功对话，沉淀为可复用的团队资产？理解了这些，你才能真正掌握与 AI 高效协作的主动权。

1. 从“魔法咒语”到“工作说明书”：重新理解 Prompt 的价值

很多人对 Prompt 的理解，还停留在“如何问问题”的层面。比如，“请用 Python 写一个快速排序算法”，或者“帮我润色这段英文邮件”。这当然没错，但对于 Claude Code 这类深度集成到开发环境中的 AI 助手来说，这种单次、零散的交互效率太低了。

真正的效率提升，来自于让 AI 理解你的长期工作上下文、团队规范和个人偏好。想象一下，每次开始一个新对话，你都需要重新告诉 AI：“我是后端开发，主要用 Python 和 Go，代码风格遵循 Google 规范，函数必须有类型注解和文档字符串，优先使用异步编程……”这显然是不可持续的。

这就是“系统提示词”存在的意义。它不再是单次对话的“问题”，而是 AI 在整个对话生命周期内的“工作说明书”或“角色设定”。一个设计良好的系统提示词，应该能回答以下几个问题：

我是谁？(身份与角色)：我是一个代码审查助手？一个全栈开发伙伴？还是一个专注于数据处理的脚本生成器？
我拥有什么能力和权限？(工具与边界)：我能读写哪些文件？我能执行终端命令吗？我是否需要人类对每一步操作进行确认？
我应该遵循什么规则？(行为准则)：我的代码输出格式是什么？我的回答应该详细还是简洁？有哪些安全红线绝对不能触碰？
我处在什么环境中？(上下文感知)：当前的工作目录是什么？这是一个 Git 仓库吗？项目的技术栈和架构约定是什么？

GitHub 上这个高星项目所探讨的 Claude Code 系统提示词定制，正是围绕这几个核心问题展开的。它提供的不是一份固定的“终极提示词”，而是一套可组合、可分层、可持久化的配置体系。这套体系让我们能够将 Prompt 从临时的“对话技巧”，升级为可管理、可迭代的“工程资产”。

2. 拆解 Claude Code 的系统提示词工程：四种核心定制方法

Claude Code 的 Agent SDK 提供了四种主要的方式来塑造 AI 的行为，它们各有侧重，适用于不同的场景。理解它们的区别和联系，是进行有效定制的第一步。

2.1 CLAUDE.md：项目级的“长期记忆”与团队公约

这是最基础也最强大的一种方式。CLAUDE.md是一个放在项目根目录（或.claude/目录下）的 Markdown 文件。它的内容不会被直接注入到系统提示词中，而是作为“项目上下文”在对话开始时提供给 AI。

它的核心价值在于“持久化”和“共享化”。

持久化：只要这个文件存在，AI 在项目的任何一次会话中都能“记得”里面的内容。你不需要在每次对话中重复说明项目结构、常用命令、编码规范。
共享化：这个文件可以提交到 Git 仓库。这意味着，只要团队任何成员拉取代码，他们的 AI 助手就会自动继承同一套项目约定，保证了协作的一致性。

你应该在CLAUDE.md里放什么？

项目概述：这个项目是做什么的？核心业务逻辑是什么？
技术栈与架构：主要使用什么语言、框架、数据库？有什么特殊的架构模式（如微服务、事件驱动）？
开发规范：代码风格（PEP 8, Google Style Guide）、提交信息规范、分支管理策略。
常用命令：如何启动服务、运行测试、构建镜像、部署上线。
目录结构说明：src/,tests/,config/这些目录分别是干什么的。
外部依赖与配置：API 密钥、环境变量、第三方服务的配置说明。

示例CLAUDE.md片段：

# 项目：用户管理系统后端 ## 技术栈 - **语言**: Python 3.11+ - **Web框架**: FastAPI - **数据库**: PostgreSQL (主库), Redis (缓存) - **ORM**: SQLAlchemy 2.0 + Alembic (迁移) - **测试**: pytest, 工厂模式生成测试数据 ## 开发规范 1. **代码风格**: 遵循 Black 格式化，使用 isort 排序导入。所有函数和类必须包含 Google 风格的 docstring。 2. **API设计**: RESTful 风格，响应统一使用 `BaseResponse` 包装。 3. **错误处理**: 使用自定义异常类，并在全局异常处理器中处理。 4. **提交信息**: 遵循 Conventional Commits 规范。 ## 常用命令 - 安装依赖: `poetry install` - 启动开发服务器: `uvicorn app.main:app --reload` - 运行测试: `pytest -v` - 生成迁移脚本: `alembic revision --autogenerate -m "description"`

如何使用？在 SDK 中，通过设置settingSources: ["project"]选项，即可自动加载项目中的CLAUDE.md。它与你选择的系统提示词预设是正交的，可以叠加使用。

2.2 输出样式：可复用的“角色模板”

如果说CLAUDE.md定义了项目的“环境”，那么“输出样式”则定义了 AI 的“职业角色”。它是一个保存在~/.claude/output-styles/（用户级）或项目.claude/output-styles/（项目级）目录下的 Markdown 文件。

它的核心价值在于“角色化”和“可切换”。你可以创建多个输出样式，比如“代码审查员”、“SQL 优化专家”、“文档撰写助手”，然后在不同的任务间快速切换，而无需重写复杂的提示词。

如何创建一个输出样式？文件需要包含 Front Matter 元数据和具体的提示词内容。一个关键选项是keep-coding-instructions: true，这决定了是替换还是保留Claude Code 原生的编码指导。

示例：创建一个“安全代码审查员”角色

--- name: Security Code Reviewer description: 专注于代码安全性和漏洞审查的助手 keep-coding-instructions: true # 保留 Claude Code 原有的代码质量、安全规则等指令 --- 你是一名资深的安全工程师和代码审查专家。 你的核心任务是审查提交的代码，识别潜在的安全漏洞、不良实践和合规性问题。 **审查流程：** 1. **输入验证与净化**：检查所有用户输入是否经过适当的验证、转义或参数化。 2. **认证与授权**：验证身份验证和权限检查逻辑是否健全，是否存在越权风险。 3. **敏感数据处理**：检查密钥、令牌、个人信息等是否被硬编码或不当记录。 4. **依赖安全**：提醒注意依赖库的已知漏洞（可结合工具建议）。 5. **配置安全**：检查配置文件是否包含敏感信息，或存在不安全的默认配置。 **输出格式：** - 以分级列表形式列出发现的问题（高危、中危、低危）。 - 每个问题需包含：**问题描述**、**代码位置**、**潜在风险**、**修复建议**。 - 最后给出一个整体的安全评分（1-10分）和总结。

如何激活？

CLI 工具：运行/config命令进行选择。
SDK 调用：在配置中指定outputStyle字段。
配置文件：在.claude/settings.local.json中设置。

输出样式非常适合需要固定角色、且希望该角色能在不同项目和会话中复用的场景。

2.3 预设追加：在巨人肩膀上进行微调

这是最轻量、最常用的定制方式。当你觉得 Claude Code 默认的“编码助手”角色（即claude_code预设）大体上符合你的需求，只是想增加一些额外的、会话特定的指令时，就可以使用“追加”模式。

它的核心价值是“非侵入式增强”。你保留了 Claude Code 预设中所有内置的工具使用说明、安全规则、代码风格指南，只是在末尾加上你自己的要求。

如何使用？在 SDK 中，将systemPrompt配置为一个对象，指定预设并添加append字段。

import { query } from "@anthropic-ai/claude-agent-sdk"; const messages = []; for await (const message of query({ prompt: "为这个用户模型添加 CRUD 接口", options: { systemPrompt: { type: "preset", preset: "claude_code", append: ` 本次任务请特别注意： 1. 使用 Pydantic V2 进行请求/响应模型验证。 2. 所有数据库操作必须放在异步上下文中。 3. 为每个接口编写完整的单元测试，使用 pytest-asyncio。 4. 在返回的 JSON 中，时间字段统一格式化为 ISO 8601 字符串。 ` } } })) { messages.push(message); }

在这个例子里，AI 依然是一个全能的编码助手，但同时被额外要求关注异步、Pydantic 和测试。

2.4 完全自定义提示词：从头定义 AI 的身份

当你构建的 AI 应用与 Claude Code 的“人类在环的编码助手”这一基本设定相差甚远时，就需要完全自定义系统提示词。

什么情况下需要完全自定义？

不同的交互界面：你构建的是一个聊天机器人 UI，或者一个输出结构化数据供其他系统消费的 API，而不是在终端中给人看。
不同的身份：你的 AI 是一个“客服机器人”、“数据分析助手”或“游戏 NPC”，而不是“Claude Code”。
不同的权限模型：你的 AI 代理需要自主运行，无需人类逐步批准，或者只能在受限的资源集上操作。
非编码任务：你的 AI 主要处理文本分析、内容创作、研究总结等任务，Claude Code 预设中大量的编码指导反而会成为干扰。

完全自定义的挑战与责任选择自定义，意味着你需要从头构建所有指令，包括：

工具使用指导（如果你的 AI 需要调用工具）。
安全与伦理规则。
输出格式和风格。
身份和职责描述。

示例：一个数据分析助手的自定义提示词

你是一个专业的数据分析助手，名为“DataInsight”。 **你的能力：** - 你可以读取用户提供的 CSV、JSON 数据文件路径，并进行描述性统计分析。 - 你可以根据用户指令，生成数据可视化建议（描述图表类型和维度）。 - 你可以指出数据中可能存在的异常值或缺失模式。 - 你**不能**执行任何文件写入、系统命令或网络请求。 **你的行为准则：** 1. 回答首先给出核心结论或洞察。 2. 使用清晰的项目符号列表呈现支持性数据（如平均值、中位数、标准差）。 3. 所有数值结果保留两位小数。 4. 如果发现数据质量问题，用“⚠️”标记并说明。 5. 保持回答客观、专业，避免主观臆断。 **输出格式：** 【核心结论】 - 要点1 - 要点2 【详细分析】 1. 维度A分析：... 2. 维度B分析：... 【数据质量备注】（可选） - ⚠️ 注意：某字段缺失率较高。

3. 四种方法对比与选型指南：如何为你的场景选择最佳策略？

了解了四种方法后，如何选择？下面的表格从多个维度进行了对比，帮助你决策：

特性维度	CLAUDE.md	输出样式 (Output Style)	预设追加 (Append)	完全自定义
核心作用	提供项目上下文与长期记忆	定义可复用的AI角色	在预设基础上进行会话级微调	完全重塑AI的身份与行为
持久性	项目级持久（文件随项目保存）	用户/项目级持久（保存为文件）	会话级临时（写在代码里）	会话级临时（写在代码里）
可重用性	项目内所有会话自动继承	跨项目、跨会话复用（通过文件）	代码级复用（复制粘贴）	代码级复用（复制粘贴）
管理方式	文件系统（Git管理）	CLI + 文件系统	应用程序代码	应用程序代码
保留默认能力	是（与系统提示词正交）	可选(`keep-coding-instructions`)	是（追加在预设后）	否（需手动重新定义）
内置安全规则	是（由系统提示词决定）	可选保留	是	必须手动添加
环境上下文	自动注入	依赖预设或手动添加	自动继承预设的上下文	必须手动提供
最佳适用场景	团队规范、项目约定、常用命令	固定的专家角色（如审查员、SQL专家）	在编码助手基础上增加临时要求	构建与Claude Code定位完全不同的AI应用

决策流程建议：

首先，为你的项目创建CLAUDE.md。这是成本最低、收益最高的投入，能极大提升AI对项目背景的理解。
然后，问自己：我的AI需要扮演一个固定的专业角色吗？如果需要，并且这个角色会在多个地方使用，就创建一个输出样式。例如，为团队创建一个统一的“代码审查员”样式。
接着，在单次会话或特定功能中，如果默认的claude_code预设基本够用，只是需要一些额外指示，就用预设追加。
最后，只有当你构建的应用（如聊天机器人、自动化Agent）与“人类指导的编码助手”模式有本质不同时，才考虑完全自定义。

4. 高级技巧与工程化实践：超越单次对话

掌握了基本方法后，我们来看看如何将这些技巧工程化，用于构建更稳定、高效的生产级应用。

4.1 组合使用：构建分层提示词策略

这些方法不是互斥的，完全可以组合使用，形成强大的合力。

典型组合模式：CLAUDE.md+ 输出样式 + 会话追加

基础层 (CLAUDE.md)：提供项目通用的技术栈、规范和上下文。所有AI会话都基于此。
角色层 (输出样式)：根据任务类型，加载不同的专家角色（如“后端开发”、“前端开发”、“DevOps”）。
任务层 (会话追加)：在具体会话中，针对当前子任务给出更精细的指令。

例如，在一个微服务项目中：

CLAUDE.md定义了整个微服务架构、通信协议（gRPC）、日志规范。
当你处理“用户服务”时，激活“Python/Go 后端开发”输出样式，它包含了后端的特定模式。
在本次代码审查会话中，你通过追加指令强调：“本次重点审查与‘订单服务’的gRPC接口兼容性和错误处理。”

4.2 优化提示词缓存：提升性能与成本

Claude Code 的预设系统提示词中，包含了一些动态内容，如当前工作目录、Git仓库状态、操作系统信息等。这意味着，即使两个会话使用相同的预设和追加文本，只要工作目录不同，它们就无法共享提示词缓存，每次都需要重新计算，影响速度和增加成本。

解决方案：excludeDynamicSections选项在 SDK 中，你可以设置excludeDynamicSections: true（TypeScript）或"exclude_dynamic_sections": True（Python）。这个选项会将动态的上下文信息从系统提示词移动到第一条用户消息中。这样，系统提示词就变成了一个静态的模板，可以在不同会话、不同机器之间共享缓存。

何时使用？当你部署的 AI Agent 会在多个相似环境（如多个CI/CD runner）中执行相同逻辑的任务时，启用此选项可以显著提升效率。需要注意的是，这样做会略微降低 AI 对“当前目录”等动态环境的感知权重，但对于批量、自动化的任务来说，缓存共享的收益通常更大。

4.3 从“能用”到“好用”：编写有效提示词的实用原则

无论采用哪种方法，编写提示词本身都是一门艺术。以下是一些经过验证的原则：

清晰明确，避免歧义：使用肯定句，明确指令。“生成一个函数”不如“生成一个名为calculate_statistics的 Python 函数，接收数字列表，返回包含均值、中位数、众数的字典”。
提供上下文和示例：在CLAUDE.md或自定义提示词中，给出输入输出的例子。AI 非常擅长通过例子学习。
结构化输出：明确指定你希望的输出格式（JSON、Markdown 表格、带编号的列表）。这能极大简化后续的程序化处理。
分步骤思考：对于复杂任务，可以鼓励 AI “逐步思考”或“先列出大纲”，这能提高结果的逻辑性和完整性。
设定边界和约束：明确说明什么是不能做的，比如“不要修改src/core/目录下的文件”，“不要使用已弃用的 API”。
迭代优化：将你发现的有效提示词片段保存下来，逐步丰富你的CLAUDE.md或输出样式库。这是一个持续积累的过程。

5. 总结：将 Prompt 工程化为团队的核心竞争力

回顾这 4.4 万星项目带给我们的启示，其价值远不止于几个好用的提示词模板。它展示的是一种系统化的、工程化的与 AI 协作的思维方式。

从临时到持久：不要再把每次与 AI 的对话都当成一次性的“咒语施法”。通过CLAUDE.md和输出样式，将那些经过验证的、高效的协作模式沉淀下来，变成团队共享的资产。
从通用到专用：拒绝“万能助手”的幻想。通过分层定制的提示词，为不同的场景（项目、角色、任务）打造最专用的 AI 伙伴，让它的能力聚焦在刀刃上。
从技巧到流程：Prompt 工程不应是少数人的“黑魔法”。通过将最佳实践文档化、模板化，可以降低整个团队的使用门槛，让 AI 助手真正融入开发流程，成为提升团队生产力的标准组件。

最终，与 AI 高效协作的关键，不在于寻找那个“一劳永逸”的完美提示词，而在于建立一套可持续演进的方法论。这套方法论让你能清晰地定义 AI 的职责，精准地注入上下文，并灵活地调整其行为以适应千变万化的需求。当你开始像管理代码一样管理你的提示词时，AI 才能真正从一个有趣的玩具，转变为你和团队手中不可或缺的利器。