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

不同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：

# 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：

--- 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 文件已经提供了完整上下文：

{"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/的内容合并输出：

四、同步脚本示例

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

// scripts/sync-ai-rules.jsconstfs=require('fs');constpath=require('path');constRULES_DIR='.ai/rules';constHEADER='<!-- AUTO-GENERATED: Do not edit. Source: .ai/rules/ -->\n\n';// 读取所有规则文件并合并functionloadRules(){constfiles=fs.readdirSync(RULES_DIR).filter(f=>f.endsWith('.md')).sort();returnfiles.map(f=>{constcontent=fs.readFileSync(path.join(RULES_DIR,f),'utf-8');returncontent.trim();}).join('\n\n---\n\n');}construles=loadRules();constoutput=HEADER+rules;// 同步到各工具配置consttargets=['.github/copilot-instructions.md','.cursorrules','.windsurfrules',];targets.forEach(target=>{constdir=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 流程中，确保规则始终同步。

五、实施步骤

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

六、总结