规则与技能

规则

规则是 markdown 文件，为所有对话提供持久的指令。你不必在每次开始新任务时重复同样的偏好，而是定义一次，让 Cline 自动遵循。当你想让 Cline 遵循团队的编码规范（命名约定、文件组织、错误处理模式）、理解项目特定的上下文（技术栈、架构决策、依赖）、应用一致的文档或测试要求，或记住「不要修改 /legacy 里的文件」「总是使用 TypeScript」这类约束时，用规则。

支持的规则类型

Cline 能识别来自多种来源的规则，所以你可以使用其他工具已有的规则文件：

所有检测到的规则类型都出现在 Rules 面板里，你可以逐个切换它们。

规则存放在哪里

规则可以存放在两处：你的项目工作区，或你系统上的全局位置。工作区规则放在项目根目录的 .clinerules/ 或 .cline/rules/ 里，VS Code、Desktop 和 CLI 都支持这两种布局，用于团队规范、项目特定的约束，以及任何你想通过版本控制与协作者共享的东西。全局规则放在系统的 Cline Rules 目录里，用于适用于所有项目的个人偏好；Cline 还从 ~/.agents/AGENTS.md 读取跨工具的全局 AGENTS 指令。

your-project/
├── .clinerules/              # 工作区规则
│   ├── coding.md             # 编码规范
│   ├── testing.md            # 测试要求
│   └── architecture.md       # 结构性决定
├── src/
└── ...

例子用的是 .clinerules/，你也可以把同样的规则文件放进 .cline/rules/；两个目录存在时都会被搜索，所以不需要把规则复制进两处（VS Code 的 Rules 面板仍在 .clinerules/ 里创建新的工作区规则）。Cline 处理两个目录里的规则文件，把它们合并成统一的规则集；01-coding.md 这样的数字前缀有助于组织文件，但可选。工作区规则和全局规则同时存在时，Cline 把它们合并，冲突时工作区规则优先。

全局规则目录的默认位置：Windows 是 Documents\Cline\Rules，macOS 和 Linux/WSL 是 ~/Documents/Cline/Rules。Cline 还会在 ~/.cline/rules 和 ~/Cline/Rules 里搜索全局规则；在 Windows 上，它检查由 OneDrive、OneDriveConsumer 和 OneDriveCommercial 配置的 OneDrive 目录下的 Documents\Cline\Rules。

创建规则

1. 打开 Rules 菜单：点 Cline 面板底部、模型选择器左边的天平图标。
2. 创建新规则文件：点「New rule file...」并输入文件名（如 coding-standards），文件以 .md 扩展名创建。
3. 写规则：用 markdown 格式添加指令；让每个规则文件聚焦于单一关注点。

你也可以用 /newrule 斜杠命令让 Cline 交互式地创建规则。每条规则都有一个开关来启用或禁用，让你在不删除规则文件的情况下对当前任务细粒度地控制哪些规则适用，例如你可能有一条严格的测试规则，想在原型阶段禁用，或有一条只在处理该客户功能时才需要的客户专属规则。

写出有效的规则

结构：规则在易于浏览且具体时效果最好，用 markdown 结构组织指令：

# Rule Title
Brief context about why this rule exists (optional but helpful).

## Category 1
- Specific instruction
- Another instruction with example: `like this`
- Reference to file: see /src/utils/example.ts

## Category 2
- More instructions
- Include the "why" when it's not obvious

Cline 把规则作为上下文读取，所以格式很重要：标题帮助 Cline 理解每条指令的范围，要点让单个要求清晰，代码示例展示你到底想要什么。

最佳实践：具体而不是含糊（「Use descriptive variable names」太宽泛，「Use camelCase for variables, PascalCase for classes, UPPER_SNAKE for constants」给 Cline 具体的东西）；包含原因（规则看起来武断时解释理由，如「Don't modify files in /legacy (this code is scheduled for removal in Q2)」帮助 Cline 在边界情况下做出更好的决定）；指向示例（代码库已经展示了你想要的模式时就引用它，如「Follow the error handling pattern in /src/utils/errors.ts」比从头描述更有效）；保持规则最新（过时的规则让 Cline 困惑并浪费上下文）；一个文件一个关注点（按主题拆分规则：coding.md、testing.md、architecture.md，方便开关特定规则）。注意：规则消耗上下文 token，避免冗长的解释或粘贴整份风格指南，保持规则简洁，需要详细参考时链接到外部文档。

一个示例：

# Project Guidelines

## Code Style
- Use TypeScript for all new files
- Prefer composition over inheritance
- Use repository pattern for data access
- Follow error handling pattern in /src/utils/errors.ts

## Documentation
- Update relevant docs when modifying features
- Keep README.md in sync with new capabilities

## Testing
- Unit tests required for business logic
- Integration tests for API endpoints
- E2E tests for critical user flows

条件规则

条件规则让你把规则限定在代码库的特定部分：规则只在你处理匹配的文件时激活，让上下文保持聚焦和相关。没有条件时，每条规则对每个请求都加载；有条件时，规则只在你当前的文件匹配其定义的范围时激活。例如，文档风格规则应该只在你编辑文档时出现，而不是在你写应用代码或测试时。随着规则库增长，为每个请求加载每条规则会浪费上下文 token 并可能稀释 Cline 的注意力；条件规则只给 Cline 与你实际接触的文件相关的指令，所以响应更快更准确：做后端工作时前端规则不会争夺注意力，写测试时测试规范恰好出现。

条件规则在规则文件顶部使用 YAML frontmatter。Cline 处理请求时，从你当前的工作收集上下文（打开的文件、可见的标签页、提及的路径、编辑过的文件），评估每条规则的条件并激活匹配的规则。条件规则激活时你会看到通知，如「Conditional rules applied: workspace:frontend-rules.md」。在 .clinerules/ 目录里任何规则文件的顶部添加 YAML frontmatter：

---
paths:
  - "src/components/**"
  - "src/hooks/**"
---

# React Component Guidelines

When creating or modifying React components:
- Use functional components with React hooks
- Extract reusable logic into custom React hooks
- Keep components focused on a single responsibility

--- 标记界定 frontmatter，闭合 --- 之后的一切都是规则内容。paths 条件：目前支持的条件是 paths，接受 glob 模式数组，例如 "src/**"（src/ 下所有文件）、"*.config.js"（根目录的配置文件）、"packages/*/src/"（monorepo 包的源码）。glob 语法：* 匹配除 / 之外的任何字符；** 匹配包括 / 在内的任何字符（递归）；? 匹配单个字符；[abc] 匹配括号里的任一字符；{a,b} 匹配任一模式。

行为细节：多个模式时，只要任一模式匹配上下文里的任一文件，规则就激活（如 frontend/** 和 mobile/** 在你于前端或移动端工作时激活）；没有 frontmatter 的规则始终激活；paths: []（空数组）意味着规则永不激活，可用来临时禁用一条规则；YAML 无效时 Cline 选择放行（fail open）：规则带着可见的原始内容激活，以帮助调试。

什么算「当前上下文」：Cline 根据这些评估规则：你的消息（提示里提到的文件路径，如「update src/App.tsx」）、打开的标签页（编辑器里当前打开的文件）、可见的文件（活动编辑器窗格里可见的文件）、编辑过的文件（Cline 在任务期间创建、修改或删除的文件）、待处理的操作（Cline 即将编辑的文件）。条件规则可以在你的第一条消息时、相关文件打开时，或任务中途 Cline 开始处理匹配文件时激活。提示：在提示里明确文件路径，「Update src/services/user.ts」可靠地触发基于路径的规则，「update the user service」则可能不会。

实用示例：前端与后端规则分开以避免噪音（.clinerules/frontend.md 的 paths 是 src/components/**、src/pages/**、src/hooks/**，内容如用 Tailwind CSS 做样式、尽量用服务端组件、保持客户端组件小而聚焦；.clinerules/backend.md 的 paths 是 src/api/**、src/services/**、src/db/**，内容如服务用依赖注入、所有数据库查询经过仓库、返回类型化的错误而不是抛异常）；测试文件规则（paths 是 **/*.test.ts、**/*.spec.ts、**/__tests__/**，要求描述性的测试名「should [expected behavior] when [condition]」、尽量一个测试一个断言、mock 外部依赖而不是内部模块、用工厂而不是 fixture 生成测试数据）；文档规则（paths 是 docs/**、**/*.md、**/*.mdx，要求标题用句子大小写、所有功能都带代码示例、段落简短、链接到相关文档）。条件规则与规则开关界面并用：关掉条件规则会完全禁用它（即使路径匹配也不激活），打开则让它在条件满足时激活，这提供两级控制：手动开关和基于条件的自动激活。

有效条件规则的技巧：从宽到窄（先 src/**，再收窄到 src/features/auth/**）；用描述性的文件名指示范围（如 api-endpoints.md、database-models.md、react-components.md、没有 frontmatter 的 universal.md）；把通用规则分开（始终开启的规则放进没有 frontmatter 的文件，条件规则留给特定上下文的指导）；测试你的模式（不确定模式是否匹配时，创建一条内容为 TEST: This rule should activate for your/pattern/here files. 的简单测试规则，然后处理该路径下的文件，看是否出现激活通知）。排障：规则没有激活——检查上下文里的文件路径是否匹配 glob 模式、确认规则在规则面板里是打开的、确保 YAML frontmatter 有正确的 --- 分隔符；规则意外激活——检查 glob 模式（** 是递归的，可能匹配得比预期多）、检查匹配该模式的打开文件、你消息里提到的文件路径也算上下文；输出里显示 frontmatter——YAML 无法解析，检查语法错误（未加引号的特殊字符、缩进不当）。

技能

技能是为特定任务扩展 Cline 能力的模块化指令集。每个技能打包详细的指导、流程和可选资源，Cline 只在与你的请求相关时才加载。你可以安装多个技能，Cline 只加载需要的：部署技能在你询问部署之前保持休眠。与始终生效的规则不同，技能按需加载，所以你在做不相关的事情时它们不消耗上下文。从 Skills 菜单管理技能：点 Cline 面板底部、模型选择器左边的天平图标，然后切到 Skills 标签页。

技能如何工作

技能使用渐进加载来最大化效率：

你发送消息时，Cline 看到可用技能及其描述的列表；如果你的请求匹配某个技能的描述，Cline 用 use_skill 工具激活它，加载 SKILL.md 里的完整指令。你也可以用斜杠命令从聊天输入里明确调用已启用的技能：输入 / 打开命令建议，选择想运行的技能命令（如 /aws-deploy），Cline 触发该技能并加载它的 SKILL.md 指令；当你想立即强制使用某个技能而不是等基于描述的自动匹配时很有用。

技能结构

每个技能是一个含 SKILL.md 文件（带 YAML frontmatter）的目录：

my-skill/
├── SKILL.md          # 必需：主要指令
├── docs/             # 可选：额外文档
│   └── advanced.md
└── scripts/          # 可选：实用脚本
    └── helper.sh

---
name: my-skill
description: Brief description of what this skill does and when to use it.
---

# My Skill

Detailed instructions for Cline to follow when this skill is activated.

## Steps

1. First, do this
2. Then do that
3. For advanced usage, see [advanced.md](docs/advanced.md)

必需字段：name 必须与目录名完全一致；description 告诉 Cline 何时使用这个技能（最多 1024 个字符）。

创建技能：打开 Skills 菜单（Cline 面板底部、模型选择器左边的天平图标，切到 Skills 标签页）；点「New skill...」并输入技能名称（如 aws-deploy），Cline 创建带模板 SKILL.md 的技能目录；编辑 SKILL.md（更新 description 字段指明何时触发、在正文里添加详细指令、可选地在 docs/、templates/ 或 scripts/ 子目录里添加辅助文件）。你也可以在文件系统里手动创建目录结构：把技能目录放在 .cline/skills/（工作区）或 ~/.cline/skills/（全局），Cline 会自动检测。把重要信息放在 SKILL.md 的前面（Cline 按顺序读取文件，所以前置常见情形），并用「## Error Handling」「## Configuration」这样清晰的章节标题，让 Cline 能扫描相关部分。每个技能都有一个开关来启用或禁用，发现技能时默认启用，这让你在不删除技能目录的情况下控制哪些技能活动（例如在本地开发时禁用 CI/CD 技能，或只在处理某客户项目时启用客户专属技能）。

写好你的 SKILL.md

命名约定：技能名出现在 name 字段里，必须与目录名完全一致；用小写加连字符（kebab-case），并对技能做什么给出描述性。好的名字：aws-cdk-deploy、pr-review-checklist、database-migration、api-client-generator；避免：aws（太含糊）、my_skill（下划线、没有描述性）、DeployToAWS（用 kebab-case 而不是 PascalCase）、misc-helpers（太泛）。

写出有效的描述：描述决定 Cline 何时激活技能，含糊的描述意味着技能不会在你期望时触发。好的描述具体且可操作，例如「Deploy applications to AWS using CDK. Use when deploying, updating infrastructure, or managing AWS resources.」「Generate release notes from git commits. Use when preparing releases, writing changelogs, or summarizing recent changes.」「Analyze CSV and Excel data files. Use when exploring datasets, generating statistics, or creating visualizations from tabular data.」；弱描述留下太多歧义，如「Helps with AWS stuff.」「Data analysis helper.」「Useful for releases.」。以技能做什么开头（用动作动词），包含用户可能说的触发短语，并提到具体的文件类型、工具或领域；用不同措辞的请求测试你的描述，看技能是否触发。

保持技能聚焦：让 SKILL.md 保持在 5k token 以内；如果技能需要更多内容，把它拆成 docs/ 目录里的单独文件并从主指令引用，Cline 只在需要时加载被引用的文件。包含真实的例子：展示要运行什么命令、期望什么输出、结果应该是什么样；抽象的指令比具体的例子更难遵循。

技能存放在哪里

技能可以存在全局或项目工作区里。项目技能：.cline/skills/（推荐）、.clinerules/skills/、.claude/skills/；全局技能：~/.cline/skills/（macOS/Linux）、C:\Users\USERNAME\.cline\skills\（Windows）。全局技能和项目技能同名时，全局技能优先；这让你把通用技能放在全局，同时把项目特定的技能放在 .cline/skills/ 里供整个团队使用。通过提交 .cline/skills/ 对项目技能做版本控制，你的团队可以一起共享、评审和改进它们。

随附辅助文件

技能可以包含 Cline 只在需要时才访问的额外文件：

complex-skill/
├── SKILL.md
├── docs/
│   ├── setup.md
│   └── troubleshooting.md
├── templates/
│   └── config.yaml
└── scripts/
    └── validate.py

• docs/：用于对 SKILL.md 来说太详细或只在特定情形下相关的信息：高级配置选项、边界情况的排障指南、参考资料（API 模式、数据库模式）、平台特定的指令。部署技能可以有 docs/aws.md、docs/gcp.md 和 docs/azure.md，Cline 根据你的请求只加载相关的平台指南。
• templates/：当技能创建配置文件、样板代码或结构化文档时用：配置文件（Terraform、Docker Compose、CI/CD 流水线）、代码脚手架（组件模板、测试 fixture）、文档模板（README、API 文档）。项目设置技能可以包含 templates/dockerfile、templates/docker-compose.yml 和 templates/.env.example，由 Cline 为每个新项目定制。
• scripts/：用于你想要一致行为的确定性操作：验证（lint 配置、检查前提条件）、数据处理（解析、格式化、转换）、复杂计算（成本估算、资源规模）、API 交互（获取数据、运行健康检查）。脚本节省 token，因为只有它们的输出进入上下文，而不是代码本身：一个 500 行的验证脚本产生一个简单的「Passed」或详细的错误信息，而不消耗任何用于脚本逻辑的上下文。

在 SKILL.md 里引用这些文件：

For initial setup, follow [setup.md](docs/setup.md).
Use the config template at `templates/config.yaml` as a starting point.
Run the validation script to check your configuration:
python scripts/validate.py

当指令引用文档文件时，Cline 用 read_file 读取它们；脚本可以直接执行，只有脚本的输出进入上下文窗口。用脚本做确定性操作（验证、格式化）、复杂计算、需要可靠性的操作，以及你不想花 token 解释的任何事；用指令做适应上下文的灵活指导、决策过程、因情况而异的步骤，以及最佳实践和模式。

示例：数据分析技能：创建 data-analysis/ 目录和这个 SKILL.md：

---
name: data-analysis
description: Analyze data files and generate insights. Use when working with CSV, Excel, or JSON data files that need exploration, cleaning, or visualization.
---

# Data Analysis

When analyzing data files, follow this process:

## 1. Understand the Data
- Read a sample of the file to understand its structure
- Identify column types and data quality issues
- Note any missing values or anomalies

## 2. Ask Clarifying Questions
Before diving in, ask the user:
- What specific insights are they looking for?
- Are there any known data quality issues?
- What format do they want for the output?

## 3. Perform Analysis
Use pandas for data manipulation (load with pd.read_csv, then inspect df.head(), df.describe(), df.info()).
For visualization, prefer matplotlib or seaborn depending on complexity.

技能把 Cline 从通用助手变成了解你领域的专家。从你经常重复的某个任务的一个技能开始，测试它，并迭代描述直到它可靠触发。

.clineignore（即将弃用）

注意：.clineignore 即将被弃用。它过滤的是 Cline 自动加载的内容，但不是安全或访问控制边界：被忽略的文件仍可以通过显式 @ 提及或 shell 命令被读取，Cline 正在把它从受支持的功能中移除。你仍可以继续使用同一个文件，并通过 PreToolUse hook 获得比原来更强的、被强制执行的限制：官方提供了 PreToolUse_ClineignoreGuard.sh 示例脚本（位于 cline 仓库的 sdk/examples/hooks/），只要文件读取（read_files）、编辑（editor、apply_patch）或 shell 命令（run_commands）指向匹配 .clineignore 的文件，它就主动阻止该工具调用，并且还会阻止对 .clineignore 本身的修改。该脚本需要 jq 和 git（git 只用作模式匹配器，你的工作区不必是 git 仓库）。

安装：VS Code 扩展里，hooks 放在 .clinerules/hooks/（工作区）或 ~/Documents/Cline/Hooks/（全局），必须严格以事件名命名且无文件扩展名，并需要 shebang 和可执行位：

mkdir -p .clinerules/hooks
curl -o .clinerules/hooks/PreToolUse https://raw.githubusercontent.com/cline/cline/main/sdk/examples/hooks/PreToolUse_ClineignoreGuard.sh
chmod +x .clinerules/hooks/PreToolUse

然后在 Cline 的功能设置里勾选 Enable Hooks。CLI 从工作区的 .cline/hooks/（或全局的 ~/.cline/hooks/，或自定义的 --hooks-dir）发现 hooks：

mkdir -p .cline/hooks
curl -o .cline/hooks/PreToolUse.sh https://raw.githubusercontent.com/cline/cline/main/sdk/examples/hooks/PreToolUse_ClineignoreGuard.sh
chmod +x .cline/hooks/PreToolUse.sh

在工作区根目录添加 .clineignore 文件列出要保护的文件，模式使用 .gitignore 语法（目录、glob 和 ! 否定都可用），例如 .env、.env.*、secrets/、*.pem。Cline 试图触及匹配的文件时，hook 在工具调用运行之前取消它：文件从不被访问，当前任务运行停止；在扩展里你会看到 PreToolUse hook 行后面跟着 Aborted 状态，在 CLI 里运行结束，发送后续消息继续对话。hook 在输出里记录阻止原因（如 {"cancel": true, "errorMessage": "Blocked read_files: .env matched a .clineignore pattern, so Cline may not access it. ..."}）。

这个 hook 只覆盖 .clineignore 原本做的一部分，却强制执行得更多：它阻止文件读取、编辑和 shell 命令，但不过滤搜索或文件列表结果，所以它是访问控制边界而不是减少上下文的工具（原来的 .clineignore 正相反）；被取消的工具调用会停止当前任务运行并显示原因；shell 保护是保守的 token 检查而不是完整的 shell 解析器，能抓住 cat .env 这样直接的访问，但足够有创意的命令仍可能漏过；路径按词法规范化但不解析符号链接，预先存在的、指向被忽略文件的符号链接别名不会被抓住，所以也要把这些别名加进 .clineignore；在 CLI 里，hooks 在 --yolo 模式下被禁用，要用 --act 或 --plan。

原始的 .clineignore 参考（为现有用户保留）：.clineignore 告诉 Cline 分析你的代码库时跳过哪些文件和目录，工作方式像 .gitignore：在项目根目录创建名为 .clineignore 的文件，加入你想排除的文件的模式。没有它，Cline 可能把整个项目加载进上下文，包括依赖、构建产物和生成的文件，这浪费 token、增加成本并可能把有用的上下文挤出窗口；添加 .clineignore 可以把你起始的上下文从 200k+ token 降到 50k 以下，意味着更快的响应、更低的成本，以及能有效使用更小更便宜的模型。示例：

# Dependencies
node_modules/
**/node_modules/
# Build outputs
/build/
/dist/
/.next/
/out/
# Testing artifacts
/coverage/
# Environment variables
.env
.env.*
# Large data files
*.csv
*.xlsx
*.sqlite
# Generated/minified code
*.min.js
*.map

模式语法与 .gitignore 相同：node_modules/（node_modules 目录）、**/node_modules/（任意深度的 node_modules）、*.csv（所有 CSV 文件）、/build/（仅项目根的 build 目录）、*.env.*（.env.local、.env.production 这样的文件）、!important.csv（例外：不忽略这个文件）；以 # 开头的行是注释，空行被忽略。建议排除：几乎总是排除包管理器目录（node_modules/、vendor/、.venv/）、构建产物（dist/、build/、.next/、out/）、覆盖率报告（coverage/）和很大的锁文件；存在时排除大数据文件（.csv、.xlsx、.sqlite、.parquet）、二进制资产（图片、字体、视频）、生成的代码（API 客户端、protobuf 输出、压缩的 bundle）和带密钥的环境文件（.env、.env.local）；保持可访问：你正在处理的源代码、Cline 需要理解的配置文件（tsconfig.json、package.json）、文档和 README、测试文件（Cline 经常需要它们作上下文）。Cline 扫描项目构建上下文时，用你的 .clineignore 模式检查每个文件路径，匹配的文件被排除在：任务开始时 Cline 看到的文件列表、对话期间的自动上下文收集、以及 Cline 寻找相关代码时的搜索结果之外。显式的 @ 提及仍然绕过这些规则（例如即使 node_modules/ 被忽略，@/node_modules/some-package/index.js 仍然读取该文件），忽略规则控制的是自动加载而不是显式访问。.clineignore 与 .gitignore 是分开的：被 Git 跟踪但与 Cline 无关的文件（如大的测试 fixture 或数据文件），即使不在 .gitignore 里也应放进 .clineignore。技巧：添加 .clineignore 后检查任务标题里的 token 用量，差别通常很显著；如果 Cline 似乎缺少某个文件的上下文，检查它是否被你的忽略模式排除；对 monorepo 或多根工作区，每个工作区根可以有自己的 .clineignore。