A Universal Steering/Rules File Solution for Multiple AI Coding Tools

Solution Overview

Store all coding standards in .ai/rules/ as Markdown files. Each AI assistant references the same rule files through its own configuration, providing a single source of truth without duplication.

Recommended Directory Structure

project-root/
├── .ai/                     ← universal AI rules (tool‑agnostic)
│   ├── rules/
│   │   ├── naming-conventions.md   ← naming conventions
│   │   ├── architecture.md        ← layered architecture guidelines
│   │   ├── code-style.md          ← code style rules
│   │   ├── security.md            ← secure coding
│   │   └── tech-stack.md          ← technology stack description
│   └── README.md                ← documentation
├── .kiro/                     ← Kiro‑specific configuration
│   ├── steering/
│   │   └── coding-standards.md   ← includes rules via #[[file:]] syntax
│   └── hooks/
│       └── pre-write-check.kiro.hook   ← hook prompt referencing the rules
├── .github/
│   └── copilot-instructions.md   ← Copilot configuration (merged rules)
├── .cursorrules                 ← Cursor configuration (merged rules)
├── .windsurfrules                ← Windsurf configuration (merged rules)
└── .qoder/rules/                ← Qodo configuration (can be split by topic)

Roles of Files

1. .ai/rules/ – Rule Repository

Markdown files that define naming conventions, architecture, code style, security, and tech‑stack guidelines. Example .ai/rules/naming-conventions.md:

# Java Naming Conventions

## Class Naming
| Type | Rule | Example |
|------|------|---------|
| Entity | PascalCase | `DeliveryRecordMaster` |
| DTO | Ends with Dto | `UserQueryDto` |
| Service Interface | BusinessName + Service | `OrderService` |
| Service Implementation | InterfaceName + Impl | `OrderServiceImpl` |
| Controller | Ends with Controller | `OrderController` |
| Mapper | Ends with Mapper | `OrderMapper` |
| Enum | Ends with Enum | `OrderStatusEnum` |
| Utility | Ends with Utils/Util | `DateUtils` |

## Method Naming
| Operation | Prefix | Example |
|-----------|--------|---------|
| Single query | find/get | `findById` |
| List query | list | `listByStatus` |
| Create | save/insert | `saveOrder` |
| Update | update | `updateStatus` |
| Delete | delete | `deleteById` |
| Validate | check/validate | `checkStock` |
| Boolean check | is/has/can | `isExpired` |

## Variable Naming
- camelCase, no pinyin
- Boolean variables start with is/has/can
- Collections use plural or List/Map suffix
- Constants are ALL_CAPS with underscores

2. .kiro/steering/ – Kiro Reference

Kiro steering files include the rule repository using the #[[file:]] syntax. Example .kiro/steering/coding-standards.md:

---
inclusion: auto
---
# Code Standards

All generated or modified code must follow these rules.

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

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

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

Kiro automatically loads the referenced rules into each conversation context.

3. .kiro/hooks/ – Write Interception

The hook prompt can be minimal because the steering file already provides full context. Example hook definition:

{
  "enabled": true,
  "name": "Pre-write Standards Check",
  "version": "1.0.0",
  "description": "Check code against .ai/rules before writing",
  "when": {"type": "preToolUse", "toolTypes": ["write"]},
  "then": {"type": "askAgent", "prompt": "Before writing, verify naming, architecture, annotations, logging, and exception handling against the loaded steering rules. Fix any violations before proceeding."}
}

4. Other Tools – Content Synchronization

For tools that cannot reference files directly, the rule files are merged into a single document. Target configuration files:

.github/copilot-instructions.md – merged rules

.cursorrules – merged rules

.windsurfrules – merged rules

.qoder/rules/*.md – can be split by topic

Sync Script Example

A Node.js script concatenates all Markdown rule files and writes the result to each tool’s configuration file.

// 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/ -->

';

function loadRules() {
  const files = fs.readdirSync(RULES_DIR)
    .filter(f => f.endsWith('.md'))
    .sort();
  return files.map(f => fs.readFileSync(path.join(RULES_DIR, f), 'utf-8').trim())
    .join('

---

');
}

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('
All AI tool configs updated from .ai/rules/');

Run the script with node scripts/sync-ai-rules.js. It can be added to a Git pre‑commit hook or CI pipeline to guarantee instant propagation of rule changes.

Implementation Steps

Create .ai/rules/ and split existing standards into separate Markdown files.

Configure .kiro/steering/ to reference the rule files using #[[file:]] and set inclusion: auto.

Simplify Hook prompts because the full rule set is loaded via steering.

Write the sync script to generate .github/copilot-instructions.md, .cursorrules, and .windsurfrules from the source rules.

Optionally add CI checks to ensure configuration files stay in sync with the source.

Summary

Single source of truth for rules with a tool‑specific adaptation layer.

Change once, all tools update automatically.

Rule changes flow through Git PRs and affect every AI tool.

Each tool can add extra configuration on top of the common rules.

Applicable to any team, language, and combination of AI coding assistants.