夜雨聆风不同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/ 的内容合并输出：
.github/copilot-instructions.md | ||
.cursorrules | ||
.windsurfrules | ||
.qoder/rules/*.md |
四、同步脚本示例
创建一个脚本自动将规则源文件同步到各工具的配置中：
// scripts/sync-ai-rules.jsconst 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 检查
（可选），确保配置文件与源文件同步