AI 辅助开发的工程体系：从定规则到基础设施

AI 辅助开发的工程体系：从定规则到基础设施

摘要：本文介绍了一套工程化的 AI 辅助开发规则管理体系。针对多工具（Claude、Cursor、CodeBuddy、Qoder）配置不统一的问题，提出以 .claude/ 目录为唯一真实源，通过软链接实现跨平台规则共享。文章详细区分了规则（Rules）与技能（Skills）的概念，对比了各平台配置文件格式，提供了从统一配置、创建软链接、Git 管理到 Windows 兼容性的完整实操方案，并分享了规则分层管理、版本控制和持续改进的最佳实践。

上一篇讲了怎么给 Claude 定规则。但规则写好了只是第一步——实际开发中，你大概率不止用一个工具。

我自己日常是 Claude Code 做复杂任务，Cursor 做日常编码，国内环境还会用到 CodeBuddy 和 Qoder。每个工具的规则配置格式都不一样：Claude 用 CLAUDE.md，Cursor 用 .cursorrules 或 .cursor/rules/，CodeBuddy 和 Qoder 也都支持项目级的规则文件配置。

最开始是每个工具各配各的，改一次规则要改三遍。后来实在受不了，折腾出一套工程化的方案。

---

先搞清一个概念：规则和技能不是一回事

规则（Rules）是"怎么写代码"的约束——命名规范、异常处理方式、日志格式。它影响的是 AI 每次生成代码的行为。

技能（Skills）是"怎么完成特定任务"的流程——比如"新建一个 React 项目"、"生成 PDF 报告"、"部署到测试环境"。它是一整套可执行的步骤、脚本和资源。

Anthropic 在 2025 年 10 月正式推出了 Claude Skills 功能，并在 12 月推出了 Agent Skills 开放标准，让 Skill 不再限 Claude 独有。Cursor 的 Nightly 版也已经支持。

这个趋势很有意思——Skill 正在成为 AI 时代的应用层。就像模型是 CPU，Agent Runtime 是操作系统，Skill 就是上面跑的应用软件。

---

各平台的配置文件对比

先把各家怎么配规则、怎么配技能列清楚：

┌─────────────────────────────────────────────────────────────────┐
│                   各平台配置文件对比                               │
│                                                                 │
│  平台       规则配置              技能配置                         │
│  ──────     ──────────            ──────────                    │
│  Claude     CLAUDE.md             .claude/skills/<name>/        │
│  (Code)     .claude/rules/        SKILL.md + scripts/           │
│             .claude/settings.json                               │
│                                                                 │
│  Cursor     .cursorrules          .cursor/skills/               │
│             .cursor/rules/        .mdc 文件（Markdown + 元数据）  │
│                                                                 │
│  CodeBuddy  项目级规则文件        Skills（SKILL.md 格式）          │
│             CLAUDE.md 兼容                                      │
│                                                                 │
│  Qoder      项目级规则文件        支持 CLAUDE.md 风格配置           │
│             CLAUDE.md 兼容                                      │
└─────────────────────────────────────────────────────────────────┘

核心问题：格式各不相同，但内容高度重叠。你团队的 Java 编码规范，在哪个平台都是一样的规范，没必要维护多份。

---

我的方案：.claude/ 作为统一源

决策过程其实不复杂：

1. Claude 的 .claude/ 目录结构最清晰——rules/ 放规则、skills/ 放技能、settings.json 放配置
2. Cursor 原生支持读取第三方配置（设置里开 "Include third-party Plugins, Skills, and other configs" 后会自动扫描 .claude/skills/）
3. 所以把 .claude/ 作为唯一真实源，其他工具通过软链接指向它

项目根目录/
├── .claude/                    ← 唯一真实源（Git 追踪这个）
│   ├── CLAUDE.md
│   ├── rules/
│   │   ├── java.md
│   │   ├── test.md
│   │   └── security.md
│   ├── skills/
│   │   ├── web-builder/
│   │   │   ├── SKILL.md
│   │   │   └── scripts/
│   │   └── pdf-processor/
│   │       ├── SKILL.md
│   │       └── scripts/
│   └── settings.json
│
├── .cursorrules                ← 软链接 → .claude/CLAUDE.md
├── .cursor/rules               ← 软链接 → .claude/rules/
└── .cursor/skills              ← 软链接 → .claude/skills/

这个决策的权衡：为什么选 .claude/ 而不是 .cursor/？因为 Claude 的规则分层设计更成熟——CLAUDE.md 放核心规则（200 行以内），领域规则拆到 .claude/rules/ 独立文件，用 @ 引用。这个分层思路比把所有东西塞进一个 .cursorrules 文件更可持续。

---

实操步骤

第一步：把规则文件统一到 .claude/

如果之前规则散落在各处，先搬到 .claude/：

mkdir -p .claude/rules
# 把之前各处的规则搬过来
mv .cursorrules .claude/CLAUDE.md 2>/dev/null
mv .cursor/rules/* .claude/rules/ 2>/dev/null

第二步：创建软链接

# Cursor 规则软链接
ln -s .claude/CLAUDE.md .cursorrules
ln -s .claude/rules .cursor/rules

创建完验证一下：

ls -la .cursorrules
# 应该显示：.cursorrules -> .claude/CLAUDE.md

第三步：配置 Git

这是最容易踩坑的地方。Git 对软链接的处理要看场景：

如果你用的是 macOS/Linux，Git 默认会把软链接存为符号链接提交，这没问题——但 clone 到 Windows 上就炸了。

如果团队有 Windows 用户，建议用 .gitattributes 强制行为：

# .gitattributes
.claude/rules/* -text
.claude/skills/* -text

或者更简单的方案：软链接不进 Git，只进 .claude/ 的真实文件。每个开发者 clone 后自己跑一个 setup.sh 创建本地软链接。

第四步：Cursor 设置里开启第三方配置

打开 Cursor 设置，搜索 "Include third-party Plugins, Skills, and other configs"，打开它。这样 Cursor 会自动扫描 .claude/skills/ 并识别里面的 Skill，不需要额外配置。

---

Skill 文件格式：Claude vs Cursor

这块很多人问，直接对比一下。

Claude 的 SKILL.md：

---
name: web-builder
description: 用 React + Tailwind 快速搭建前端页面。包含初始化、开发、打包流程。
---# Web Builder1. 运行 `scripts/init.sh <project-name>`
2. 编辑生成的代码
3. 运行 `scripts/bundle.sh` 打包为单 HTML

Cursor 的 .mdc 文件（放在 .cursor/skills/ 下）：

---
name: web-builder
description: 用 React + Tailwind 快速搭建前端页面
globs: **/*.{tsx,jsx,css}
---相同内容...

差异很小：Claude 用 SKILL.md（放在技能目录里），Cursor 用 .mdc 文件（直接放在 skills 目录下）。核心内容——描述、步骤、脚本——完全通用。

参考： Anthropic 官方文档 agentskills.io 和 Cursor Skills 文档 都在朝统一标准方向走。

---

踩坑：Windows 软链接 + Git GUI 不识别

这个坑是我实际遇到的。

在 macOS 上配得好好的，团队里有个用 Windows + 某 Git GUI 工具的同事 clone 后报错——工具不识别软链接，把 .cursorrules 当成普通文件读取，内容是 .claude/CLAUDE.md 这个路径字符串，不是规则内容本身。

排查过程：

1. 先确认 Git 提交了什么——git ls-files -s .cursorrules 显示是 symlink 类型（120000）
2. 在 Windows 命令行 dir 看，软链接确实存在
3. 但那个 Git GUI 工具读的是文件内容，不是跟随软链接

解决方案：放弃了全团队统一用软链接的方案，改用 setup.sh 脚本让每个人本地创建。Git 里只追踪 .claude/ 的真实文件，软链接路径写进 .gitignore。

#!/bin/bash
# setup.sh - 每个开发者 clone 后执行一次
ln -sf .claude/CLAUDE.md .cursorrules
ln -sf .claude/rules .cursor/rules
ln -sf .claude/skills .cursor/skills

这不是最优解，但是最稳的解。

---

规则的版本管理和持续改进

规则文件进了 Git 之后，几个实用的习惯：

给规则文件加版本号注释。在 CLAUDE.md 顶部加一行：

<!-- v2.3 | 最后更新: 2026-06-21 | 维护人: @tangyuewei -->

每次改了规则更新版本号和日期。这样 code review 的时候能看到规则在演进，也能回溯"这个规则是什么时候加的、为什么加"。

建立规则变更的 checklist。每次 code review 发现新的团队共识，走三步：

1. 确认这个共识值得写成规则（不是临时方案）
2. 更新 .claude/ 下的对应文件
3. 通知团队成员跑 git pull

听起来麻烦，但实际执行下来，一个月也就改个两三次，每次几分钟。

关注规则使用率。这个目前没有自动化工具，靠手动观察——如果某个 Skill 三个月没被 Claude 调用过，大概率可以删了。如果某条规则从来没被违反过，说明 Claude 已经内化了，也可以考虑精简。

---

一个完整的规则分层案例

以我们的 Java 项目为例，规则是这样分的：

L1 团队级（.claude/CLAUDE.md，几乎不改）：

## 基础约定
- Java 17, Spring Boot 3.2.x
- 业务异常统一抛 BusinessException
- 日志用 @Slf4j
- Controller 返回统一用 BaseResponse 包装

L2 技术栈级（.claude/rules/java.md，换框架时改）：

## MyBatis-Plus 规范
- Mapper 继承 BaseMapper
- 复杂查询用 QueryWrapper
- 分页用 Page 对象

L3 项目级（.claude/rules/project.md，经常改）：

## 本次迭代特殊要求
- 新增的 user-preference 表字段必须加索引
- 老接口兼容期保留旧字段

分层的好处是：L1 稳定，L2 跟技术栈走，L3 灵活变。改 L3 不影响 L1/L2，换技术栈只动 L2。

---

写在最后

这套体系的核心就一条：把 .claude/ 作为唯一真实源，其他工具通过软链接或配置指向它。规则分层管理，技能文件跨平台通用。

不需要一次性全配好，先从 CLAUDE.md 开始，用顺手了再加 rules，最后上 skills。一步一步来，比一上来就搞全套靠谱得多。

---

tangyuewei，从后端出发，用 AI 拓展到全栈的工程师。