# Multi-Editor Agent Configuration

> One repo, 8 config files, zero drift. Keep every AI coding tool aligned with one canonical source.

## When to Use

- Setting up a new repo for AI-assisted development
- Switching between AI editors (Cursor one day, Claude Code the next)
- After architectural changes that affect agent behavior
- When different team members use different AI tools

## The Pattern

Maintain **one canonical source** (AGENTS.md) and derive all editor-specific configs from it.

```
AGENTS.md                           ← CANONICAL SOURCE (human-maintained)
  │
  ├── CLAUDE.md                     ← Claude Code (Anthropic)
  ├── .cursorrules                  ← Cursor AI
  ├── .windsurfrules                ← Windsurf / Codeium
  ├── .github/copilot-instructions.md ← GitHub Copilot
  ├── .clinerules                   ← Cline / Roo Code
  ├── .aider.conf.yml               ← Aider
  └── .editorconfig                 ← All editors (formatting only)
```

## The 8 Files

### 1. AGENTS.md (500+ lines, full detail)

The master document. Contains everything: identity, layout, rules, patterns, pitfalls.

### 2. CLAUDE.md (~100 lines)

Claude Code reads this automatically. Focus on:

- Key constraints and conventions
- Build/test commands
- Common pitfalls
- Link to AGENTS.md for full context

```markdown
# CLAUDE.md

Read AGENTS.md for full context. Key rules:

## Build & Test

- `pnpm build && pnpm test && pnpm typecheck`

## Conventions

- ESM everywhere, .js extensions in imports
- Never use console.log — use req.log
- Commit: type(scope): description

## Common Pitfalls

1. Vitest globals cause tsc errors → exclude test files in tsconfig
2. pnpm workspace deps use "workspace:\*"
```

### 3. .cursorrules (~80 lines)

Cursor reads this per-project. Rules format:

```
# Project Rules

You are working on <project-name>, a <description>.

## Key Rules
- Always use ESM imports with .js extensions
- Never use console.log
- Every Cosmos document needs productId field

## File Structure
<brief layout>

## Commands
- Build: pnpm build
- Test: pnpm test
```

### 4. .windsurfrules (~80 lines)

Same format as .cursorrules. Windsurf reads it automatically.

### 5. .github/copilot-instructions.md

Copilot reads this from the .github directory:

```markdown
# Copilot Instructions

## Coding Standards

- TypeScript strict mode, ESM
- Zod for validation
- Fastify for services

## Do Not

- Use console.log
- Use any type
- Hardcode secrets
```

### 6. .clinerules

For Cline/Roo Code (VS Code extension). Same format as cursorrules.

### 7. .aider.conf.yml

Minimal config pointing to AGENTS.md:

```yaml
read: AGENTS.md
lint-cmd: pnpm typecheck
test-cmd: pnpm test
auto-commits: false
```

### 8. .editorconfig

Universal formatting (all editors respect this):

```ini
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{py,pyi}]
indent_size = 4

[*.md]
trim_trailing_whitespace = false
```

## Automation: The /update-agent-docs Workflow

Create a workflow that regenerates all 8 files from AGENTS.md:

```markdown
---
description: Regenerate AI agent docs across workspace
---

1. Read AGENTS.md in each repo
2. For each repo, regenerate:
   - CLAUDE.md (build commands + key rules + pitfalls)
   - .cursorrules (condensed rules)
   - .windsurfrules (same as cursorrules)
   - .github/copilot-instructions.md (adapted)
   - .clinerules (condensed)
3. Commit: `docs: regenerate agent configs from AGENTS.md`
```

## Anti-Patterns

- **Maintaining 8 files independently** — They will drift. Always derive from AGENTS.md
- **Putting everything in .cursorrules** — It has soft limits; keep it concise, link to AGENTS.md
- **Ignoring .editorconfig** — It's the one file ALL editors (not just AI) respect
- **Not updating after architecture changes** — Stale rules cause more harm than no rules

## Real-World Example

Across a 5-repo workspace, this pattern ensures that switching from Windsurf to Claude Code to Cursor produces consistent agent behavior. The `/update-agent-docs` workflow was run monthly, touching all 3 main repos × 8 files = 24 files in one commit.

## Related Skills

- [01 — AGENTS.md Pattern](./01-agents-md-pattern.md)
- [04 — Workflow Definitions](./04-workflow-definitions.md)
- [06 — Multi-Session Continuity](./06-multi-session-continuity.md)
