不同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.github/copilot-instructions.md合并所有规则为一个文件Cursor.cursorrules同上Windsurf.windsurfrules同上Qodo.qoder/rules/*.md可按主题分文件四、同步脚本示例创建一个脚本自动将规则源文件同步到各工具的配置中// scripts/sync-ai-rules.jsconstfsrequire(fs);constpathrequire(path);constRULES_DIR.ai/rules;constHEADER!-- AUTO-GENERATED: Do not edit. Source: .ai/rules/ --\n\n;// 读取所有规则文件并合并functionloadRules(){constfilesfs.readdirSync(RULES_DIR).filter(ff.endsWith(.md)).sort();returnfiles.map(f{constcontentfs.readFileSync(path.join(RULES_DIR,f),utf-8);returncontent.trim();}).join(\n\n---\n\n);}construlesloadRules();constoutputHEADERrules;// 同步到各工具配置consttargets[.github/copilot-instructions.md,.cursorrules,.windsurfrules,];targets.forEach(target{constdirpath.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 编程工具组合