Claude Code系统提示词工程化实践：从项目规范到AI角色定制

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

你是不是也遇到过这样的场景：用 ChatGPT 或 Claude 写代码，结果它要么理解错了需求，要么生成的代码风格混乱，要么干脆忽略了项目里已有的架构约定？你可能会想：“是不是我提问的方式不对？”于是你开始研究“提示词工程”，在网上找各种“万能模板”，结果发现要么太笼统，要么不适用于你的具体场景。

问题的核心往往不在于你的提问技巧，而在于你缺少一个稳定、可复用、且与项目深度绑定的“系统级”指令集。这就像你每次雇佣一个新程序员，都要从头到尾交代一遍公司的代码规范、技术栈偏好和项目背景，效率极低。

今天要聊的，就是一个被 4.4 万开发者收藏的“提示词金矿”——Claude Code 的系统提示词自定义体系。这不仅仅是 Claude 的一个功能，它揭示了一个更本质的趋势：AI 编程助手正在从“一次性对话工具”演变为“可深度配置的工程化伙伴”。

很多人以为系统提示词（System Prompt）就是聊天框里那几句开场白，改改语气和角色就行。但 Claude Code 的官方文档展示了一套远比这精细和强大的工程化方案。它提供了四种不同粒度和持久性的自定义方法：项目级的CLAUDE.md、用户/项目级的“输出样式”、会话级的“追加指令”，以及完全自定义的提示词字符串。这套方案不是为了让你写更花哨的提示词，而是为了解决工程实践中的真实痛点：如何让 AI 助手在不同项目、不同角色、不同任务中保持行为一致且高效，同时又能被版本管理和团队共享。

本文将带你深入这套体系，不仅告诉你“是什么”，更会拆解“为什么”要这样设计，以及在实际开发中“怎么选”和“怎么用”。你会发现，掌握这套方法，相当于为你的 AI 助手装上了“项目记忆”和“角色切换”芯片，让它真正融入你的开发工作流。

1. 这篇文章真正要解决的问题

我们首先需要明确一个关键认知：系统提示词不是“魔法咒语”，而是“工程配置文件”。

很多开发者对提示词的认知还停留在“如何问得更好”这个层面，热衷于收集各种“神级 Prompt”。但在实际团队协作和复杂项目开发中，这种碎片化的、依赖于个人记忆和临场发挥的 Prompt 使用方式，会带来几个严重问题：

1. 一致性灾难：A 同事让 AI 生成的代码遵循 Google 风格，B 同事却得到了 Airbnb 风格的代码。项目代码风格混乱，Review 成本激增。
2. 上下文丢失：每次新开一个对话，你都要重新向 AI 介绍项目结构、核心模块、依赖关系。对于大型项目，这几乎不可能每次都讲清楚。
3. 效率瓶颈：重复编写相似的指令，例如“请为所有函数添加类型注解和文档字符串”、“优先使用 async/await 而非回调”。这些机械劳动本应自动化。
4. 知识孤岛：某个成员摸索出了一套针对项目数据库操作的最佳 Prompt，却无法有效分享给团队，团队整体效能无法提升。

Claude Code 的系统提示词自定义体系，正是为了解决这些问题而生。它把提示词的管理从“聊天艺术”提升到了“配置工程”的层面。通过本文，你将能解决以下具体问题：

• 如何让 Claude 一进入我的项目，就自动了解项目规范和技术栈？
• 如何为代码审查、SQL 优化、API 设计等不同场景创建专属的、可一键切换的 AI 角色？
• 如何在保留 Claude 强大编码能力的基础上，无缝融入我团队的特定要求？
• 如何将配置好的 AI 行为通过 Git 进行版本管理和团队共享？

如果你正在团队中推广 AI 编程助手，或者你个人希望 AI 助手能更深度、更稳定地辅助你的开发工作，那么这篇文章就是为你准备的。

2. 基础概念与核心原理

在深入实操之前，我们需要统一几个核心概念，理解 Claude Code 设计这套体系的底层逻辑。

2.1 什么是系统提示词（System Prompt）？

你可以把它理解为 AI 模型的“初始人格设定”和“工作手册”。它在对话开始前就被注入，定义了 AI 的身份、能力边界、行为准则和响应风格。与用户每次输入的具体问题（User Prompt）不同，系统提示词是相对稳定、全局生效的背景指令。

在 Claude Code 的语境下，系统提示词默认包含了：

• 工具使用指南：如何调用文件读写、终端命令、网络请求等工具。
• 代码风格与格式化规则：缩进、命名、注释等规范。
• 安全与伦理指令：避免执行危险操作、保护隐私等。
• 响应语气与详细程度：如何组织回答，是详尽还是简洁。
• 环境上下文：当前工作目录、Git 仓库状态等。

2.2 Claude Code 提供的四种自定义方法

Claude Code 没有提供一种“万能”方法，而是根据不同的使用场景和持久化需求，设计了四种路径：

2.3 核心设计哲学：分层与组合

这四种方法不是互斥的，而是可以分层组合使用的。这是理解其强大之处的关键。

• 底层：CLAUDE.md提供最稳定、最基础的项目上下文。
• 中层：“输出样式”定义了一个可复用的角色模板。
• 上层：“追加指令”或“完全自定义提示词”提供本次会话的特定微调。

例如，你可以：

1. 在CLAUDE.md中定义项目通用的“使用 TypeScript + React + Ant Design”。
2. 创建一个“前端代码审查员”的输出样式，专注于 UI 组件规范。
3. 在本次代码审查会话中，通过append追加指令：“特别检查useEffect的依赖项是否完整”。

这种设计使得配置既灵活又结构化，既能满足长期稳定的团队规范，又能应对短期多变的临时需求。

3. 环境准备与前置条件

要实践本文内容，你需要准备好以下环境。请注意，本文重点在于讲解方法论和提供可操作的代码示例，部分版本号请以你实际使用的为准。

1. Node.js 环境：Claude Code Agent SDK 主要支持 TypeScript/JavaScript。确保已安装 Node.js（建议 LTS 版本，如 18.x 或 20.x）和 npm/yarn/pnpm 等包管理器。
2. Python 环境（可选）：如果你计划使用 Python SDK，需要 Python 3.8+ 和 pip。
3. Claude Code Agent SDK：通过包管理器安装。

   # 使用 npm npm install @anthropic-ai/claude-agent-sdk # 或使用 yarn yarn add @anthropic-ai/claude-agent-sdk # 或使用 pnpm pnpm add @anthropic-ai/claude-agent-sdk

   （Python 安装命令为pip install claude-agent-sdk，下文示例以 TypeScript 为主，原理相通）。
4. 有效的 Anthropic API 密钥：你需要在 Anthropic 官网注册并获取 API Key，并确保其有足够的权限调用 Claude 模型。
5. 一个代码编辑器或 IDE：如 VS Code、WebStorm 等。
6. 一个示例项目：为了演示CLAUDE.md和输出样式，建议准备一个简单的 Git 仓库，例如一个前端 React 项目或后端 Node.js 项目。

4. 核心流程拆解：从项目规范到角色定制

我们将按照从“持久化”到“临时性”，从“基础”到“高级”的顺序，拆解四种方法的具体实施流程。

4.1 基石：使用CLAUDE.md固化项目上下文

这是最应该首先建立的习惯。CLAUDE.md文件是你的项目“入职手册”。

第一步：创建文件在你的项目根目录下，创建名为CLAUDE.md的文件。你也可以选择将其放在.claude/目录下（即.claude/CLAUDE.md），这样更整洁。

第二步：编写内容CLAUDE.md是纯 Markdown 文件。你应该在里面写入任何希望 Claude 在为本项目工作时都知道的信息。例如：

# 项目：电商后台管理系统 ## 技术栈 - 前端：React 18, TypeScript, Vite, Ant Design 5.x - 状态管理：Zustand - 请求库：Axios，已封装在 `src/utils/request.ts` - CSS: Tailwind CSS ## 代码规范 1. **组件**：所有 React 组件必须使用 `const ComponentName: React.FC<Props> = () => {}` 形式定义。 2. **类型**：必须为所有函数参数和返回值定义 TypeScript 类型或接口。 3. **API 调用**：统一使用 `src/api/` 目录下定义的模块，禁止在组件内直接写 `axios.get`。 4. **目录结构**： - `src/components/`：通用组件 - `src/pages/`：页面组件 - `src/hooks/`：自定义 Hooks - `src/stores/`：状态管理 - `src/utils/`：工具函数 ## 常用命令 - 启动开发服务器：`pnpm dev` - 代码检查：`pnpm lint` - 构建：`pnpm build` ## 当前重点任务 我们正在重构用户管理模块，新 API 设计文档见 `docs/api-v2.md`。请优先参考新文档。

第三步：在 SDK 中启用默认情况下，SDK 会自动从当前工作目录和用户目录加载CLAUDE.md。你也可以显式指定：

import { query } from "@anthropic-ai/claude-agent-sdk"; const messages = []; for await (const message of query({ prompt: "帮我创建一个用户列表页面，包含搜索和分页", options: { // 使用 Claude Code 的默认预设（包含工具调用、安全规则等） systemPrompt: { type: "preset", preset: "claude_code" }, // 显式指定从项目加载 CLAUDE.md（默认已包含，此处为演示） settingSources: ["project"] } })) { messages.push(message); if (message.type === "assistant") { console.log(message.message.content); } }

现在，Claude 在为你创建用户列表页面时，会自动知晓应该使用 React + TypeScript + Ant Design，并且会去src/api/目录下寻找 API 模块，生成的代码风格也会符合你的规范。

4.2 进阶：创建可复用的“输出样式”（角色模板）

当你需要在不同项目间，或为不同任务类型快速切换 AI 角色时，“输出样式”是利器。

第一步：创建输出样式文件输出样式是一个带有 YAML Frontmatter 的 Markdown 文件。

• 用户级：保存在~/.claude/output-styles/（例如~/.claude/output-styles/code-reviewer.md），对所有项目生效。
• 项目级：保存在项目内的.claude/output-styles/目录，可随 Git 共享。

创建一个代码审查专家的样式文件code-reviewer.md：

--- name: 代码审查专家 description: 专注于代码质量、安全性和性能的审查助手 keep-coding-instructions: true # 关键！保留 Claude Code 原有的编码和安全指令 --- 你是一个经验丰富的代码审查专家。你的任务是仔细审查提交的代码，并提供建设性反馈。 请按以下优先级进行检查： 1. **功能性错误与边界情况**：逻辑错误、未处理的异常、竞态条件。 2. **安全性问题**：SQL 注入风险、XSS、敏感信息泄露、不安全的依赖。 3. **代码质量**：重复代码、函数过于复杂、糟糕的命名、违反 SOLID 原则。 4. **性能**：不必要的渲染、低效的算法、内存泄漏风险。 5. **可维护性**：文档是否清晰、测试是否覆盖关键路径。 **输出格式要求**： - 使用 Markdown 表格总结发现的问题。 - 对每个问题，提供**问题描述**、**风险等级（高/中/低）**、**具体代码位置**和**修改建议**。 - 最后给出一个总体评分（1-10分）和改进摘要。

关键参数keep-coding-instructions：

• true：保留 Claude Code 预设中的所有编码和安全指令。适用于编码相关的角色（如审查、优化、重构）。
• false或省略：用你文件中的内容完全替换Claude Code 的编码指令。适用于非编码角色（如文档撰写、会议纪要生成）。

第二步：激活输出样式有多种激活方式：

• 通过 CLI：在 Claude Code CLI 中运行/config命令进行选择。
• 通过本地设置文件：在项目或用户目录的.claude/settings.local.json中配置：

  { "outputStyle": "代码审查专家" }

• 通过 TypeScript SDK（需加载用户或项目设置源）：

  import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "请审查这段用户登录的代码：\n```typescript\n// ... 代码内容 ...\n```", options: { systemPrompt: { type: "preset", preset: "claude_code" }, settingSources: ["user"], // 或 ["project"]，用于加载输出样式 // 注意：outputStyle 是在 settings 对象内，而非顶级 options settings: { outputStyle: "代码审查专家" } } })) { // 处理响应 }

4.3 微调：使用append进行会话级指令追加

当你已经有一个很好的基础角色（无论是默认预设还是输出样式），但本次对话有特殊侧重点时，使用append。

import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "优化这个数据库查询函数", options: { systemPrompt: { type: "preset", preset: "claude_code", append: ` 本次优化的核心目标是 **降低查询延迟** 和 **减少数据库连接数**。 请特别注意： 1. 分析现有查询是否缺少必要的索引。 2. 检查是否有 N+1 查询问题。 3. 考虑使用连接（JOIN）替代多个独立查询。 4. 评估数据缓存的可能性。 请优先给出性能影响最大的优化建议。 ` } } })) { if (message.type === "assistant") { console.log(message.message.content); } }

append的优势在于，它不会覆盖原有的claude_code预设指令，只是在其后追加。这是一种风险最低、最安全的定制方式。

4.4 重塑：编写完全自定义的系统提示词

当你构建的 AI 代理与“编码助手”这个角色相去甚远时，就需要完全自定义。例如，构建一个内部客服机器人。

import { query } from "@anthropic-ai/claude-agent-sdk"; const customerServicePrompt = ` 你是我公司“TechCorp”的内部 IT 支持助手“小T”。 你的知识截止日期是 2024年7月。 你的职责是帮助员工解决办公软件、网络、硬件申请等问题。 **行为准则**： 1. 态度必须友好、耐心、专业。 2. 对于已知问题，直接提供解决方案或指向内部知识库文章（KB-xxx）。 3. 对于需要人工介入的问题（如硬件损坏），引导用户填写 JIRA 工单（IT-HELP）。 4. 绝不透露任何内部系统密码、密钥或未公开的员工信息。 5. 如果用户问题超出你的知识范围或职责，礼貌地告知并建议联系对应部门。 **响应格式**： - 首先简要复述用户问题，表示理解。 - 然后分步骤提供解决方案。 - 最后以“请问还有其他可以帮您的吗？”结尾。 现在开始对话。 `; for await (const message of query({ prompt: "我的公司邮箱无法登录了，提示密码错误。", options: { systemPrompt: customerServicePrompt // 直接使用自定义字符串 } })) { if (message.type === "assistant") { console.log(`小T：${message.message.content}`); } }

重要提醒：当你使用完全自定义提示词时，Claude Code 默认提供的工具调用能力、安全规则、编码指南将全部丢失。你需要在自己的提示词中重新定义这些规则（如果需要的话）。

5. 完整示例：构建一个团队协作的 AI 助手工作流

让我们通过一个完整的场景，将上述方法串联起来。假设我们是一个前端团队，希望标准化代码提交前的 AI 审查流程。

目标：任何团队成员在提交代码前，都能一键调用一个 AI 审查助手，该助手熟知项目规范，且审查重点可配置。

步骤 1：建立项目级规范 (CLAUDE.md)在项目根目录创建CLAUDE.md，定义技术栈、代码规范、目录结构等（内容同 4.1 节示例）。

步骤 2：创建团队共享的审查角色 (输出样式)在项目内创建.claude/output-styles/目录，并新建文件frontend-review.md：

--- name: 前端代码审查员 description: 针对本前端项目的代码审查专家，遵循项目 CLAUDE.md 规范。 keep-coding-instructions: true --- 你是一名专注于本前端项目（电商后台）的代码审查员。除了遵循 CLAUDE.md 中的通用规范，请额外关注： - **React 组件**：是否合理使用了 `memo`, `useCallback` 进行性能优化？ - **状态管理**：Zustand store 的划分是否清晰，有无不必要的全局状态？ - **TypeScript**：类型定义是否严格，有无使用 `any`？ - **Ant Design**：组件使用是否符合最新版本的最佳实践？ - **测试**：新增或修改的代码是否易于测试？ 请以表格形式输出审查结果，包含【问题类型】、【文件/行号】、【问题描述】和【修改建议】四列。

步骤 3：编写可执行的审查脚本 (自定义提示词或append)创建一个 Node.js 脚本scripts/code-review.js，让团队成员可以运行node scripts/code-review.js <本次审查的侧重点>。

// scripts/code-review.js import { query } from '@anthropic-ai/claude-agent-sdk'; import { readFileSync } from 'fs'; import { execSync } from 'child_process'; // 获取本次提交的代码差异 const gitDiff = execSync('git diff --cached').toString(); if (!gitDiff.trim()) { console.log('暂存区没有代码变更。'); process.exit(0); } // 获取命令行参数作为本次审查的侧重点 const focusArea = process.argv[2] || '常规审查'; const customAppend = ` 以下是本次提交的代码差异。请以“前端代码审查员”的角色进行审查。 **本次审查的侧重点**：${focusArea} 请严格依据项目规范（CLAUDE.md）和前端审查员的要求输出。 `; async function main() { const messages = []; for await (const message of query({ prompt: `请审查以下代码差异：\n\`\`\`diff\n${gitDiff}\n\`\`\``, options: { systemPrompt: { type: "preset", preset: "claude_code", append: customAppend }, settingSources: ["project"], // 加载项目 CLAUDE.md 和 output-styles settings: { outputStyle: "前端代码审查员" } } })) { messages.push(message); if (message.type === "assistant") { process.stdout.write(message.message.content); } } } main().catch(console.error);

步骤 4：集成到开发流程在package.json中添加一个脚本命令：

{ "scripts": { "review": "node scripts/code-review.js", "review:perf": "node scripts/code-review.js 性能优化", "review:security": "node scripts/code-review.js 安全性" } }

现在，团队成员在git commit前，可以运行npm run review或npm run review:perf来获得一次针对性的 AI 代码审查。

6. 运行结果与效果验证

运行上述审查脚本后，你应该会得到一个结构化的 Markdown 格式输出。一个成功的输出示例如下：

## 代码审查报告 **审查角色**：前端代码审查员 **审查重点**：常规审查 **提交哈希**：(根据上下文) ### 发现问题汇总 | 问题类型 | 文件/行号 | 问题描述 | 修改建议 | 风险等级 | | :--- | :--- | :--- | :--- | :--- | | **代码质量** | `src/components/UserList.tsx:45-60` | `useEffect` 依赖项数组包含了一个每次渲染都会变化的引用（`fetchUsers` 函数）。这会导致该 `useEffect` 在每次渲染后都执行。 | 使用 `useCallback` 包装 `fetchUsers` 函数，并将其依赖项（如 `api`）放入 `useCallback` 的依赖数组中。然后将 `useCallback` 返回的稳定引用放入 `useEffect` 的依赖数组。 | 中 | | **性能** | `src/components/UserList.tsx:78` | 在渲染列表项时，直接使用 `item.id` 作为 `key`。但数据源中可能存在 `id` 重复或不稳定的情况。 | 确保 `key` 的唯一性和稳定性。如果 `item.id` 确实唯一且稳定，则没问题。否则，需要组合其他字段或使用稳定的唯一标识。 | 低 | | **类型安全** | `src/api/user.ts:12` | 函数 `getUserProfile` 的返回类型被标记为 `Promise<any>`，失去了 TypeScript 的类型优势。 | 根据后端 API 文档或实际响应，定义一个具体的接口（如 `UserProfile`），并将返回类型改为 `Promise<UserProfile>`。 | 中 | | **项目规范** | `src/utils/formatDate.ts` | 新增的工具函数未在 `src/utils/index.ts` 中导出，不符合项目约定的“通过索引文件统一导出”的规范。 | 在 `src/utils/index.ts` 中添加 `export { formatDate } from './formatDate';`。 | 低 | ### 总体评分与建议 **本次提交代码质量评分：7/10** **主要优点**： - 组件结构清晰，逻辑分离得当。 - 使用了 Ant Design 组件，UI 风格统一。 **改进摘要**： 1. **高优先级**：修复 `UserList.tsx` 中 `useEffect` 的依赖问题，避免不必要的重复请求和渲染。 2. **中优先级**：为 `getUserProfile` API 函数添加精确的 TypeScript 类型定义。 3. **低优先级**：遵循项目规范，导出新增的工具函数。 **请问还有其他可以帮您的吗？**

如何验证效果？

1. 指令遵循：检查 AI 的输出是否严格遵循了CLAUDE.md中的技术栈要求（如使用了 React + TypeScript）、代码规范（如函数定义格式）以及输出样式中的格式要求（如 Markdown 表格）。
2. 上下文感知：AI 是否提及了项目特有的信息？例如，它是否知道应该使用src/api/下的模块？是否引用了项目约定的目录结构？
3. 角色一致性：当切换不同的“输出样式”（如换成“SQL 优化助手”）时，AI 的关注点和输出风格是否发生了符合预期的变化？
4. 问题发现：对于你故意在测试代码中埋下的一些常见问题（如缺少key、useEffect依赖错误），AI 是否能准确识别并提出合理建议？

7. 常见问题与排查思路

在实际使用中，你可能会遇到以下问题：

8. 最佳实践与工程建议

掌握了基本操作后，以下建议能帮助你将这套系统用得更好：

1. 从CLAUDE.md开始，逐步细化：对于任何新项目，先创建CLAUDE.md来固化项目上下文。这是成本最低、收益最高的第一步。
2. “输出样式”用于固化角色，“append”用于临时调整：将需要频繁复用的、成体系的指令集（如“代码审查”、“SQL 调优”）做成“输出样式”。对于单次会话的微调（如“本次重点看性能”），使用append。
3. 谨慎使用“完全自定义提示词”：除非你构建的 AI 代理与“编码助手”角色有本质不同，否则尽量基于claude_code预设进行扩展。重新实现工具调用、安全规则等既复杂又容易出错。
4. 利用版本控制：将项目内的CLAUDE.md和.claude/output-styles/目录纳入 Git 管理。这是团队共享和迭代 AI 助手行为规范的最佳方式。
5. 保持指令清晰、具体、无歧义：避免使用模糊的形容词。例如，将“写出高质量的代码”改为“所有函数必须有 JSDoc 注释，复杂度超过 10 的圈复杂度必须重构”。
6. 测试你的配置：像测试代码一样测试你的提示词配置。准备一些标准任务（如“创建一个简单的计数器组件”），观察不同配置下 AI 的输出是否符合预期。
7. 关注成本与缓存：对于生产环境频繁调用的 Agent，合理使用excludeDynamicSections可以提升缓存命中率，降低延迟和成本。
8. 组合使用，发挥最大效力：最常见的模式是：CLAUDE.md（项目基础） + “输出样式”（通用角色） +append（本次任务微调）。这三者结合，能构建出既稳定又灵活的 AI 辅助工作流。

9. 总结

Claude Code 的系统提示词自定义体系，其价值远不止于“让 AI 更听话”。它本质上是一套AI 助手行为管理的工程化框架。通过CLAUDE.md、输出样式、append和完全自定义这四种方法，它覆盖了从项目规范、团队角色到临时任务的所有粒度，让 AI 的能力能够被精准地塑造和复用。

对于个人开发者，这套体系能极大提升与 AI 协作的效率和代码质量的一致性。对于团队而言，它更是将 AI 助手从“个人玩具”升级为“团队资产”的关键。通过将最佳实践沉淀为可版本控制的配置文件，新成员能快速获得与团队标准一致的 AI 辅助，从而降低 onboarding 成本，提升整体工程效能。

别再把时间浪费在反复输入相似的提示词上了。开始为你最重要的项目创建一个CLAUDE.md文件，为你最常做的任务定义几个输出样式。当你把这些配置纳入日常开发流程后，你会发现，一个真正懂你项目、懂你团队的 AI 助手，才是提升生产力的终极杠杆。

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