1. 项目概述：为专业工程师量身打造的 Cursor 配置方案

如果你是一名经常与代码、配置和基础设施打交道的工程师，并且正在使用 Cursor 这款 AI 驱动的编辑器，那么你很可能已经体会过那种“智能助手不够智能”的挫败感。它有时会写出不安全的代码，有时会忽略你所在领域的特定规范，或者在你需要一套完整工作流时，只能给出零散的代码片段。这正是 madebyjake/cursor-config 这个开源项目要解决的问题。它不是一个简单的主题或快捷键配置，而是一套深度定制的、面向系统/网络管理员和工程师的 AI 助手行为准则与工作流引擎 。

简单来说，这个配置库通过一套精密的“规则”与“技能”系统，将 Cursor 从一个通用的代码生成工具，调教成你团队里那个经验丰富、严谨可靠、熟知所有运维“潜规则”的资深同事。它确保 AI 在编写 Python 脚本时遵循安全最佳实践，在修改 Kubernetes YAML 文件时能预见到常见的部署陷阱，在起草提交信息时能自动符合团队规范。其核心价值在于，它将工程师的领域知识、安全意识和协作规范，系统地“编码”到了 AI 助手中，从而大幅提升编码与运维的可靠性、一致性和效率。

2. 核心设计哲学：规则约束与技能引导的双层架构

这个配置最精妙的设计在于其清晰的双层架构，这直接对应了人类专家处理问题的两种模式： 本能反应 与 深度思考 。理解这个设计，是有效使用和扩展它的关键。

2.1 规则：内化的专业本能

规则（Rules）被定义在 .cursor/rules/ 目录下，以 .mdc 为扩展名。它们的作用是 “始终生效的约束” 。你可以把它理解为工程师的职业肌肉记忆或条件反射。当 AI 在处理特定类型的文件时，对应的规则文件会被自动加载，并作为不可违背的底线要求。

例如，当你在编辑一个 Dockerfile 时， docker.mdc 规则会自动生效。里面可能写着：“禁止使用 latest 标签”、“必须以非 root 用户运行”、“必须显式声明 WORKDIR ”。这些规则是强制性的、细粒度的，并且针对特定文件类型（通过 globs 模式匹配）。项目作者 Jake 特别强调了一个关键原则： 保持规则简短 。因为规则中的每一行文本，都会作为上下文消耗 AI 模型的 Token。冗长的规则会挤占本应用于理解当前代码的“脑容量”，降低响应的有效性和速度。因此，规则应该只包含最核心、最不容置疑的约束。

2.2 技能：按需调用的专家工作流

技能（Skills）则完全不同，它们位于 .cursor/skills/ 目录下，每个技能是一个独立的文件夹，其中包含一个 SKILL.md 文件。技能是 “按需加载的流程化工作流” 。只有当用户明确描述或触发了相关任务时，对应的技能才会被激活。

比如，当你对 Cursor 说“帮我排查一下这个 Pod 为什么一直 CrashLoopBackOff”， k8s-troubleshoot 技能就会被加载。这个 SKILL.md 文件里可能定义了一个完整的诊断流程：首先检查 Pod 描述和事件，然后查看容器日志，接着分析就绪和存活探针配置，最后提供常见的修复方案列表。技能文件可以写得非常详细，包含步骤、命令模板、决策树和示例，因为它的 Token 开销只发生在你需要它的时候。这就是“把深度放在这里，而不是规则里”的设计哲学。

这种分离带来了巨大的灵活性：

• 性能优化 ：日常编码只负载轻量级规则，响应迅速；复杂任务时才调用“重型”技能，保障深度。
• 关注点分离 ：规则管“不能做什么”（安全、规范），技能管“应该怎么做”（流程、最佳实践）。
• 易于维护 ：可以独立更新某个技能的排查步骤，而不会影响其他文件的编码规则。

3. 配置结构详解与安装部署

要使用这套配置，首先需要理解它的目录结构，并选择最适合你工作习惯的安装方式。

3.1 项目结构全解析

项目的结构非常清晰，反映了其设计思想：

.cursor/
├── rules/          # 规则库：按文件类型约束AI行为
│   ├── 00-meta-rules.mdc        # 元规则：指导如何创建和维护其他规则（由AI代理自身请求添加）
│   ├── core.mdc                 # 核心规则：适用于所有文件的通用约束（alwaysApply: true）
│   ├── python.mdc               # Python文件规则（匹配：**/*.py）
│   ├── node-ts.mdc              # Node.js/TypeScript/JavaScript规则（匹配：**/*.ts,**/*.js等）
│   ├── bash.mdc                 # Shell脚本规则（匹配：**/*.sh, .*rc等）
│   ├── docker.mdc               # Dockerfile规则（匹配：Dockerfile*, docker-compose*）
│   ├── kubernetes.mdc           # Kubernetes资源配置规则（匹配：k8s/, kubernetes/, manifests/等目录）
│   ├── yaml-toml.mdc            # YAML/TOML配置文件规则
│   ├── iac.mdc                  # 基础设施即代码规则（Terraform, Ansible）
│   ├── systemd.mdc              # systemd服务单元规则
│   └── network-config.mdc       # 网络配置规则（Nginx, 防火墙等）
│
└── skills/         # 技能库：按任务类型提供工作流
    ├── k8s-troubleshoot/        # K8s/K3s故障诊断技能
    ├── docker-audit/            # Docker镜像安全审计技能
    ├── incident-runbook/        # 事件响应手册与事后分析模板技能
    ├── pr-commit/               # 提交信息与PR描述生成技能
    ├── ansible-deploy/          # Ansible安全部署与故障排除技能
    ├── terraform-workflow/      # Terraform计划/应用及状态管理技能
    ├── security-review/         # 代码与基础设施安全审查技能
    └── new-service/             # 新服务/代码库脚手架清单技能

每个规则文件开头的 globs 注释指明了其生效的范围，这是 Cursor 识别何时加载该规则的依据。技能文件夹的名称具有自描述性，是你调用它的“咒语”。

3.2 三种安装方式及其适用场景

Jake 提供了三种安装方式，适用于不同的使用场景：

方式一：克隆到项目（推荐用于独立项目） 这是最简单直接的方式，特别适合为某个特定项目（如一个微服务仓库）配置专属的 Cursor 环境。

# 在项目根目录执行
git clone https://github.com/madebyjake/cursor-config .cursor

执行后，你的项目根目录下会出现一个 .cursor 文件夹，里面包含了所有规则和技能。这种方式的好处是配置与项目绑定，版本可控，可以通过 Git 管理配置的变更。一个常见的实践是，将 .cursor 目录加入项目的 .gitignore ，但保留一个安装脚本或文档，指导新成员如何初始化他们的本地环境。

方式二：创建符号链接（推荐用于多项目或个人全局配置） 如果你在多个项目中使用相同的配置，或者希望有一个中心化的配置源，符号链接是最佳选择。

# 1. 首先，将配置库克隆到一个固定位置，比如你的用户目录下
git clone https://github.com/madebyjake/cursor-config ~/cursor-config

# 2. 在每个需要使用此配置的项目中，创建.cursor目录并建立软链接
mkdir -p /path/to/your/project/.cursor
ln -s ~/cursor-config/rules /path/to/your/project/.cursor/rules
ln -s ~/cursor-config/skills /path/to/your/project/.cursor/skills

这样，所有项目都指向同一套配置。当你更新中心仓库（ ~/cursor-config ）后，所有项目都能立即受益。需要注意的是，符号链接可能在 Windows 系统上需要管理员权限或特殊设置，在跨平台团队中需留意。

方式三：直接复制（最灵活，但需手动同步） 直接将 rules/ 和 skills/ 目录复制到你的项目 .cursor/ 目录下。

cp -r /path/to/cursor-config/rules /path/to/your/project/.cursor/
cp -r /path/to/cursor-config/skills /path/to/your/project/.cursor/

这种方式给了你最大的自由度，可以针对当前项目随意修改规则和技能，而不会影响其他项目。缺点是，如果上游配置库更新了有用的新规则或修复，你需要手动合并更改。这适合那些配置相对稳定，且项目有高度定制化需求的场景。

个人经验与选择建议 ：我通常采用 “方式二（符号链接）为主，方式三（复制）为辅” 的策略。我会维护一个全局的、经过我个性化修改的配置库。对于大多数项目，使用符号链接。只有当某个项目有极其特殊的、与其他项目冲突的规则时（例如，一个遗留项目必须使用 Python 2.7 和特定的代码风格），我才会为其复制一份配置并进行独立修改。这平衡了一致性和灵活性。

4. 全局用户规则与 Cursor 软件设置

除了项目级的 .cursor 配置，Cursor 编辑器本身还有两个层面的设置至关重要：全局用户规则和软件功能设置。它们与项目配置协同工作，构成了完整的使用体验。

4.1 定义你的 AI 助手角色：全局用户规则

全局用户规则（Settings → Rules）是配置在 Cursor 客户端本地的，作用于所有项目和会话的顶层指令。它定义了 AI 助手的基础人格、知识领域和行为准则。Jake 的配置中给出了一个极佳的模板，你可以直接复制到你的 Cursor 设置中：

你正在协助一位专业的系统/网络管理员和工程师。

## 角色与技术栈
主要语言：Python, Node.js/JS/TS, Bash
基础设施：Docker, Docker Swarm, Kubernetes, K3s
基础设施即代码：Terraform, Ansible
配置格式：YAML, TOML, Markdown, systemd 单元文件

## 行为准则
- 安全第一：标记硬编码的密钥、过于宽松的权限、不安全的默认设置
- 倾向于明确、可读的代码，而非聪明的单行技巧
- 倾向于幂等解决方案——脚本和配置必须可以安全地重新运行
- 当不确定时：在继续之前提出一个聚焦的澄清性问题

## 澄清协议
- 关键问题（必须询问）：安全、凭证、数据完整性、破坏性操作
- 重要问题（不明确时询问）：性能权衡、外部集成
- 可选问题（合理假设）：风格偏好、次要的实现细节

## Git 规范
- 约定式提交：<类型>[范围]: <描述>
- 摘要最好 ≤50 字符，硬性限制 72 字符
- 绝不混合不相关的更改——标记并建议拆分

这段规则的精妙之处在于：

1. 确立专业身份 ：开宗明义地告诉 AI “你是在和专家对话”，这会促使它使用更专业、更严谨的术语和解决方案。
2. 划定能力范围 ：明确列出主要技术栈，让 AI 在相关领域给出更自信、更准确的建议，减少在无关技术上的发散。
3. 注入核心原则 ：“安全第一”、“幂等性”这些是运维工程的灵魂。将其作为行为准则，能让 AI 在代码生成的第一时间就考虑这些问题。
4. 定义交互协议 ：“澄清协议”部分极其重要。它明确了在哪些问题上 AI 应该主动提问，而不是自作主张。这防止了 AI 在遇到模糊需求时，要么鲁莽行动，要么过度询问。将问题分为“关键”、“重要”、“可选”三级，极大地优化了人机协作效率。

4.2 优化 Cursor 功能设置

Cursor 的软件设置（Settings）同样需要精心调整，以匹配专业工作流。Jake 基于其经验（截至2026年3月）给出了推荐：

功能设置（Settings → Features）

设置项	推荐值	理由
隐私模式	✅ 启用	保护代码隐私，避免数据被用于模型训练。
自动运行代理命令	❌ 禁用	至关重要！ 必须手动审查所有 Shell 命令后再执行，防止破坏性操作。
保存时格式化	❌ 禁用	与“代理审查选项卡”存在已知冲突（2026年3月的 Bug），可能导致代码混乱。
代码库索引	✅ 启用	这是使用 @codebase 引用和跨文件理解上下文的基础，必须开启。
文档	✅ 启用	允许使用 @docs 引用项目文档，增强上下文理解。

模型选择策略 不同的任务适合不同“脑力”的模型，平衡速度、成本与效果：

任务类型	推荐模型	说明
默认 / 日常工作	Claude Sonnet 4.6	在智能、速度和成本间取得最佳平衡的主力模型。
复杂重构、架构设计	Claude Opus 4.6	处理最复杂问题时的“王牌”，注意它可能对应 Cursor 的“最大模式”。
快速编辑、简单脚本	Auto	将简单任务交给 Cursor 自动路由到更轻量、快速的模型，节省成本。

代理模式使用心得

• 始终使用计划模式 ：对于任何涉及多个文件或复杂逻辑的任务，先按 Shift+Tab 进入“计划模式”。让 AI 先输出一个步骤计划，你审核后再让它执行。这就像让飞行员在起飞前先提交飞行计划。
• 保存计划 ：将重要的计划保存到 .cursor/plans/ 目录下。这不仅是一个记录，当下次你遇到类似任务时，可以直接引用或基于此计划修改，保证了上下文的连续性。
• 检查点功能 ：在执行任何具有潜在破坏性的代理操作（如大规模重命名、删除文件）之前，使用“检查点”功能。这为回滚提供了可能。

5. 实战应用：如何高效使用规则与技能

配置好环境只是第一步，真正发挥威力在于日常使用。下面我们通过几个典型场景，看看这套配置如何改变你的工作流。

5.1 技能的自然调用

调用技能无需记忆复杂命令，只需用自然语言描述你的任务。Cursor 会根据你的描述，自动匹配并加载最相关的 SKILL.md 文件。下表是一些经典用例：

你对 Cursor 说...	它会自动加载的技能...	你将得到什么？
“帮我排查一下这个一直 CrashLoopBackOff 的 Pod。”	k8s-troubleshoot	一个结构化的诊断流程： kubectl describe pod ... , kubectl logs ... , 探针检查清单，以及常见原因（如资源不足、镜像拉取失败、启动命令错误）的修复建议。
“审计这个 Dockerfile，看是否适合上生产。”	docker-audit	一份安全检查报告：指出是否使用了 latest 标签、是否以 root 运行、是否有多余的构建层、是否有未更新的基础镜像存在 CVE 漏洞，并给出加固建议。
“为这次线上故障写一份事后分析（Post-mortem）模板。”	incident-runbook	一个包含时间线、影响评估、根本原因、行动项（短期修复和长期预防）的标准事后分析文档框架，你只需要填充具体内容。
“为这些更改起草一个提交信息。”	pr-commit	一个符合“约定式提交”规范的信息草稿，例如 fix(api): handle null pointer exception in user endpoint ，并可能附带更详细的正文描述。
“安全地运行这个 Ansible Playbook，它用了 Vault 加密。”	ansible-deploy	一系列安全操作指引：提醒你检查 ansible.cfg 、使用 --ask-vault-pass 或指定密码文件、先在测试环境 --check 运行、以及如何解读常见的错误输出。
“规划并应用这项 Terraform 变更。”	terraform-workflow	一个完整的操作指南：运行 terraform plan -out=plan.tfplan 并审查输出，理解资源变更细节，确认后执行 terraform apply plan.tfplan ，并提醒你状态文件的管理和模块更新注意事项。
“从零开始搭建一个新服务。”	new-service	一个详尽的脚手架清单：创建 Git 仓库、设置 .gitignore 和许可证、初始化包管理器、配置 CI/CD 流水线、设置日志和监控、编写基础 Dockerfile 和 K8s 部署文件等。

5.2 规则的静默守护

与技能的主动调用不同，规则在后台默默工作。当你新建一个 Dockerfile 时， docker.mdc 规则已经生效。如果你试图写下 FROM nginx:latest ，Cursor 很可能会在代码补全时直接建议一个具体的版本号，或者在你写出这行后，在“代理审查”选项卡中给出一个警告提示：“避免使用 latest 标签以确保构建可重现性”。

再比如，当你编写一个 Bash 脚本时， bash.mdc 规则会强制要求你在脚本开头使用 set -euo pipefail ，以确保脚本在遇到错误、未定义变量或管道失败时立即退出，这是编写健壮 Shell 脚本的黄金标准。这种“防呆”设计，能在问题发生前就将其扼杀。

5.3 如何添加和维护你自己的规则

Jake 的配置是绝佳的起点，但每个团队都有自己独特的“坑”和规范。扩展规则库是使其价值最大化的关键。

添加新规则的“三次法则” 项目中的 00-meta-rules.mdc 文件本身就是一个关于如何创建规则的规则。一个核心原则是： 只有当 AI 在同一个模式上连续失败三次时，才考虑为其添加一条新规则。 这避免了规则库被大量琐碎、一次性的偏好所污染，保持其精炼和高效。

添加新规则的最佳实践是直接与 AI 协作：

1. 当你发现 AI 反复犯一个同类错误时，打开 Cursor 的聊天面板。
2. 输入指令：“请为 Cursor 创建一个新的规则文件，用于约束 [某种错误行为]，适用的文件类型是 [例如 **/*.py]。”
3. AI 会参考 00-meta-rules.mdc 的格式，为你生成一个规则草案。你只需审核并稍作修改，然后将其保存到 .cursor/rules/ 目录下，并以合适的 glob 模式命名。

规则的定期维护 规则不是一成不变的。随着项目演进、团队规范更新或 AI 模型能力变化，规则也需要维护：

• 每周回顾 ：留意哪些规则被 AI 持续忽略或违反。这可能意味着规则表述不清、约束力不足，或者已经过时。需要重写或强化它。
• 即时更新 ：一旦发现 AI 因为缺少规则而犯了一个重要错误，立即创建或更新对应的规则。这是“在战斗中学习”的最佳时机。
• 定期清理 ：如果一个规则超过一个月都没有触发或纠正过任何问题，可以考虑将其注释掉或删除。保持规则库的简洁就是保持其效力。

6. 进阶集成：Git 提交钩子与团队规范

将 Cursor 的智能与团队开发流程相结合，能产生更大的化学反应。Jake 的配置中提供了一个极其实用的 Git 提交信息钩子（Commit Hook），它能确保所有通过 Cursor 辅助生成的提交信息，都符合团队的规范。

6.1 提交钩子工作原理

这个 Bash 脚本放置在 .git/hooks/commit-msg 中，会在每次 git commit 时被触发。它做两件事：

1. 格式校验 ：检查提交信息的第一行是否符合“约定式提交”规范（如 feat(api): add new endpoint ）。这确保了提交历史的可读性和自动化工具（如生成变更日志）的可用性。
2. 长度警告 ：检查摘要行是否超过 72 字符的硬性限制，并建议最好控制在 50 字符以内，以保证在各类 Git 工具中显示良好。

脚本内容如下：

#!/usr/bin/env bash
set -euo pipefail
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\(.+\))?(!)?: .{1,72}$'
first_line=$(head -1 "$1")
if ! echo "$first_line" | grep -qE "$commit_regex"; then
  echo "ERROR: Commit message does not follow Conventional Commits." >&2
  echo "Expected: <type>[scope]: <description>" >&2
  echo "Got: $first_line" >&2
  exit 1
fi
char_count=${#first_line}
if [ "$char_count" -gt 72 ]; then
  echo "WARNING: Summary is $char_count chars (recommended ≤50, limit 72)" >&2
fi

6.2 为所有新仓库自动配置

手动为每个仓库配置钩子很麻烦。你可以将其设置为 Git 的全局模板，这样所有新初始化的仓库都会自动拥有这个钩子。

# 1. 将配置库中的钩子脚本复制到全局模板目录
mkdir -p ~/.git-templates/hooks
cp /path/to/your/cursor-config/.git/hooks/commit-msg ~/.git-templates/hooks/

# 2. 告诉 Git 使用这个模板目录
git config --global init.templateDir ~/.git-templates

# 3. 对于已存在的仓库，可以手动复制或运行 `git init` 重新初始化（注意这不会影响已有文件）

完成此设置后，任何新的 git init 创建的仓库，其 .git/hooks/ 目录下都会预置这个 commit-msg 钩子。这实现了团队规范的“基础设施即代码”，从源头保障了提交质量。

实操心得：钩子与 Cursor 技能的联动 ： pr-commit 技能生成的提交信息，会天然符合这个钩子的校验规则。这就形成了一个完美闭环：当你完成一段代码修改后，使用 Cursor 的 pr-commit 技能生成规范的信息，然后 git commit 时钩子自动校验通过。这几乎消除了编写不合格提交信息的可能性，将团队规范无缝嵌入到了开发工作流中。

7. 常见问题与个性化调优指南

即使有了如此完善的配置，在实际使用中你仍可能会遇到一些问题，或者希望进行个性化调整。以下是一些常见情况的处理方法和进阶建议。

7.1 规则不生效或技能未触发

问题 ：我安装了配置，但 AI 似乎没有遵守我写的规则，或者在我描述任务时没有调用对应的技能。

• 检查配置路径 ：首先确认 .cursor 目录是否位于项目的 根目录 下。Cursor 不会在子目录中寻找此配置。
• 检查规则语法 ：确保 .mdc 文件语法正确。规则文件本质上是给 AI 看的自然语言指令，但需要清晰的格式。可以参考现有规则文件的结构。
• 检查 glob 模式 ：确认规则文件顶部的 globs 注释是否正确匹配了你的目标文件。例如， **/*.py 能匹配所有子目录下的 .py 文件。
• 技能调用方式 ：技能是通过自然语言描述触发的。尝试使用更接近技能名称或描述中关键词的短语。例如，说“做一个安全审查”可能触发 security-review 。
• 重启 Cursor ：有时 Cursor 对配置文件的更改需要重启编辑器才能完全加载。

7.2 性能考量与 Token 优化

问题 ：随着规则和技能越来越多，会不会拖慢 Cursor 的响应速度？

• 规则的精简原则 ：这是 Jake 反复强调的。每条规则都应像军规一样简洁有力。避免在规则文件中写长篇大论的教程或解释，那些应该放在技能里。定期回顾和删除无效或冗余的规则。
• 技能的按需加载 ：技能只有在被触发时才加载，因此其文件大小对日常性能影响很小。但一个过于庞大的技能文件（比如超过几千字）仍可能在触发时导致响应变慢。考虑将超大型技能拆分为更聚焦的子技能。
• 模型上下文窗口 ：记住，所有加载的规则和当前对话上下文都会占用模型的 Token 限额。在处理一个超大文件或进行超长对话后，AI 可能会“忘记”较早的规则。此时，可以新开一个聊天窗口或使用 @rules 指令重新强调核心规则。

7.3 个性化定制：打造你自己的配置库

Jake 的配置是一个强大的基础，但最好的配置是适合你自己的。建议你：

1. Fork 这个仓库 ：在 GitHub 上 Fork madebyjake/cursor-config ，以此作为你个人或团队配置的起点。
2. 从修改全局规则开始 ：首先根据你的主要技术栈（比如 Go、Rust、Java）调整全局用户规则。添加或删除编程语言，修改行为准则。
3. 创建专属规则 ：针对你团队特有的代码规范（如特定的日志格式、错误处理模式）创建规则文件。例如，创建一个 go.mdc 来强制要求错误检查、禁用某些包等。
4. 开发专属技能 ：将你们团队内部常用的、复杂的工作流程技能化。例如：
   • database-migration/ ：包含从生成迁移脚本到在生产环境安全执行的完整流程。
   • load-testing/ ：指导如何设置和解读压力测试，包括工具选择、参数配置和结果分析。
   • on-call-handover/ ：生成值班交接日志的模板和检查清单。
5. 建立维护流程 ：在团队内部分享你的配置库，并建立一个简单的流程（如通过 Pull Request）来收集大家对规则和技能的改进建议，让配置随着团队成长而进化。

7.4 安全与隐私的最终提醒

• 永远禁用“自动运行代理命令” ：这一点再怎么强调都不为过。AI 生成的命令可能具有破坏性（如 rm -rf / 的变体）。手动审查每一行命令是必须坚守的底线。
• 隐私模式 ：如果你处理的是公司私有代码或敏感数据，务必在 Cursor 设置中启用隐私模式，以防止代码片段被发送用于模型改进。
• 规则中的秘密 ： 绝对不要 在规则或技能文件中写入真实的 API 密钥、密码或任何敏感信息。这些文件是纯文本，可能会被意外提交到版本库。如果需要涉及凭证操作，技能应指导用户从环境变量或安全的密码管理器中获取。

这套 cursor-config 不仅仅是一组配置文件，它代表了一种与 AI 协作的新范式：从被动的、通用的问答，转向主动的、领域定制的、流程化的智能增强。它要求你作为工程师，不仅会使用工具，更要懂得如何“训练”和“塑造”工具，使其真正成为你专业能力的延伸和倍增器。花时间根据自己的需求去调整和丰富它，你会发现，你投资的每一分钟，都会在日后无数次的编码、调试和运维工作中，得到丰厚的回报。