不同AI工具中通用 Steering/Rules 文件方案详解

一、方案思路

核心理念：规则内容作为"单一事实来源"（Single Source of Truth）独立维护，各 AI 工具以各自的配置方式引用同一份规则。

复制代码

┌─────────────────────────────────────────────┐
│          .ai/rules/coding-standards.md       │  ← 单一事实来源
└──────────────────────┬──────────────────────┘
                       │
        ┌──────────────┼──────────────────┐
        ▼              ▼                  ▼
┌──────────────┐ ┌───────────────┐ ┌────────────────┐
│ .kiro/       │ │ .github/      │ │ .cursorrules   │
│ steering/    │ │ copilot-      │ │                │
│ hooks/       │ │ instructions  │ │                │
└──────────────┘ └───────────────┘ └────────────────┘
   Kiro 使用         Copilot 使用      Cursor 使用

二、推荐的目录结构

复制代码

项目根目录/
├── .ai/                              ← 通用 AI 规则（工具无关）
│   ├── rules/
│   │   ├── naming-conventions.md     ← 命名规范
│   │   ├── architecture.md           ← 分层架构约定
│   │   ├── code-style.md             ← 代码风格
│   │   ├── security.md               ← 安全编码
│   │   └── tech-stack.md             ← 技术栈说明
│   └── README.md                     ← 说明文档
│
├── .kiro/                            ← Kiro 专用配置
│   ├── steering/
│   │   └── coding-standards.md       ← 引用 .ai/rules/ 内容
│   └── hooks/
│       └── pre-write-check.kiro.hook ← Hook 的 prompt 引用规则
│
├── .github/
│   └── copilot-instructions.md       ← Copilot 配置，内容同步自 .ai/
│
├── .cursorrules                      ← Cursor 配置，内容同步自 .ai/
├── .windsurfrules                    ← Windsurf 配置
└── .qoder/rules/                     ← Qodo 配置

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

三、各文件的角色和关系

1. `.ai/rules/` --- 规则本体（工具无关）

这是规则的"源文件"，用标准 Markdown 编写，任何人和工具都可以阅读。

示例 .ai/rules/naming-conventions.md：

markdown 复制代码

# Java 命名规范

## 类命名

| 类型 | 规则 | 示例 |
|------|------|------|
| 实体类 | 名词，大驼峰 | `DeliveryRecordMaster` |
| DTO | 以 Dto 结尾 | `UserQueryDto` |
| Service 接口 | 业务名 + Service | `OrderService` |
| Service 实现 | 接口名 + Impl | `OrderServiceImpl` |
| Controller | 以 Controller 结尾 | `OrderController` |
| Mapper | 以 Mapper 结尾 | `OrderMapper` |
| 枚举 | 以 Enum 结尾 | `OrderStatusEnum` |
| 工具类 | 以 Utils/Util 结尾 | `DateUtils` |

## 方法命名

| 操作 | 前缀 | 示例 |
|------|------|------|
| 查询单个 | find/get | `findById` |
| 查询列表 | list | `listByStatus` |
| 新增 | save/insert | `saveOrder` |
| 更新 | update | `updateStatus` |
| 删除 | delete | `deleteById` |
| 校验 | check/validate | `checkStock` |
| 布尔判断 | is/has/can | `isExpired` |

## 变量命名

- 小驼峰，禁止拼音
- 布尔变量：is/has/can 开头
- 集合变量：使用复数或 List/Map 后缀
- 常量：全大写下划线分隔

2. `.kiro/steering/` --- Kiro 的引用方式

Kiro 的 Steering 文件可以通过 #[[file:]] 语法直接引用规则源文件：

.kiro/steering/coding-standards.md：

markdown 复制代码

---
inclusion: auto
---

# 代码规范

本项目遵循以下编码规范，所有代码生成和修改必须符合这些规则。

## 命名规范

#[[file:.ai/rules/naming-conventions.md]]

## 架构约定

#[[file:.ai/rules/architecture.md]]

## 代码风格

#[[file:.ai/rules/code-style.md]]

这样 Kiro 会自动加载这些规则到每次对话上下文中。

3. `.kiro/hooks/` --- 写入拦截

Hook 文件的 prompt 可以精简为关键检查点，因为 Steering 文件已经提供了完整上下文：

json 复制代码

{
  "enabled": true,
  "name": "Pre-write Standards Check",
  "version": "1.0.0",
  "description": "写入前检查代码是否符合 .ai/rules/ 中定义的规范",
  "when": {
    "type": "preToolUse",
    "toolTypes": ["write"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "在写入前，对照 steering 中加载的编码规范逐项检查：命名规范、分层约定、注解使用、日志规范、异常处理。如有不符合的地方，修正后再写入。"
  }
}

4. 其他工具的配置文件 --- 内容同步

对于不支持文件引用的工具，把 .ai/rules/ 的内容合并输出：

工具	配置文件	同步方式
GitHub Copilot	`.github/copilot-instructions.md`	合并所有规则为一个文件
Cursor	`.cursorrules`	同上
Windsurf	`.windsurfrules`	同上
Qodo	`.qoder/rules/*.md`	可按主题分文件

四、同步脚本示例

创建一个脚本自动将规则源文件同步到各工具的配置中：

javascript 复制代码

// scripts/sync-ai-rules.js
const fs = require('fs');
const path = require('path');

const RULES_DIR = '.ai/rules';
const HEADER = '<!-- AUTO-GENERATED: Do not edit. Source: .ai/rules/ -->\n\n';

// 读取所有规则文件并合并
function loadRules() {
  const files = fs.readdirSync(RULES_DIR).filter(f => f.endsWith('.md')).sort();
  return files.map(f => {
    const content = fs.readFileSync(path.join(RULES_DIR, f), 'utf-8');
    return content.trim();
  }).join('\n\n---\n\n');
}

const rules = loadRules();
const output = HEADER + rules;

// 同步到各工具配置
const targets = [
  '.github/copilot-instructions.md',
  '.cursorrules',
  '.windsurfrules',
];

targets.forEach(target => {
  const dir = path.dirname(target);
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
  fs.writeFileSync(target, output, 'utf-8');
  console.log(`✅ Synced to ${target}`);
});

console.log('\nAll AI tool configs updated from .ai/rules/');

运行：node scripts/sync-ai-rules.js

可以把这个脚本加到 Git 的 pre-commit hook 或 CI 流程中，确保规则始终同步。

五、实施步骤

创建 .ai/rules/ 目录，将现有规则按主题拆分为独立 Markdown 文件
配置 .kiro/steering/ ，使用 #[[file:]] 引用规则文件，设置 inclusion: auto
精简 Hook 的 prompt，因为规则已通过 steering 加载
编写同步脚本 ，输出到 .github/copilot-instructions.md、.cursorrules 等
加入 CI 检查（可选），确保配置文件与源文件同步

六、总结

维度	说明
核心思想	规则单一来源 + 各工具适配层
维护成本	改一处，所有工具自动同步
团队协作	规则变更通过 Git PR 审核，对全部 AI 工具生效
灵活性	每个工具可以在通用规则基础上追加特有配置
适用范围	任何团队、任何语言、任何 AI 编程工具组合

不同AI工具中通用 Steering/Rules 文件方案详解