From 0bb116cd2c9214a5b326f50055ec377683a10cba Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Mon, 2 Feb 2026 09:04:00 +0100
Subject: [PATCH] docs: add Multi-IDE Configuration Sync pattern (v3.20.9)

Added comprehensive documentation for maintaining consistent AI instructions
across multiple coding tools (Claude Code, Cursor, Copilot, etc.).

Changes:
- guide/ai-ecosystem.md: New "Multi-IDE Configuration Sync" section (L1256-1329)
  - Problem statement with config file comparison table
  - Solution 1: Native @import for Claude Code (recommended)
  - Solution 2: Script-based generation for multi-IDE teams (bash example)
  - AGENTS.md support status clarification + workaround (symlink)
  - Compatibility matrix with external tool references
- machine-readable/reference.yaml: Added 2 index entries
  - ai_ecosystem_multi_ide_sync: guide/ai-ecosystem.md:1256
  - agents_md_support_status: guide/ai-ecosystem.md:1322
- CHANGELOG.md: Documented addition in [Unreleased] section
- VERSION: Bumped from 3.20.8 to 3.20.9 (patch)
- Auto-synced version across README, cheatsheet, ultimate-guide

Total: +91 insertions, -8 deletions (74 lines net content addition)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md                    |  7 ++++
 README.md                       |  2 +-
 VERSION                         |  2 +-
 guide/ai-ecosystem.md           | 74 +++++++++++++++++++++++++++++++++
 guide/cheatsheet.md             |  4 +-
 guide/ultimate-guide.md         |  4 +-
 machine-readable/reference.yaml |  6 ++-
 7 files changed, 91 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2dfbe9c..34da912 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- **Multi-IDE Configuration Sync Pattern** — Documented strategies for maintaining consistent AI instructions across multiple coding tools (Claude Code, Cursor, Copilot) in `guide/ai-ecosystem.md:1256-1329`
+  - **Problem statement**: Table comparing config files (CLAUDE.md, .cursorrules, AGENTS.md, .github/copilot-instructions.md) — without sync, each drifts independently causing inconsistent AI behavior
+  - **Solution 1**: Native @import (recommended for Claude Code solo usage) — no build step, maintained by Anthropic, but Cursor doesn't support it
+  - **Solution 2**: Script-based generation for multi-IDE teams — source of truth in `docs/ai-instructions/` compiled into tool-specific configs via bash/node sync scripts
+  - **AGENTS.md Support Status**: Clarified Claude Code does NOT natively support AGENTS.md ([GitHub issue #6235](https://github.com/anthropics/claude-code/issues/6235), 171 comments, open as of Feb 2026) — workaround via symlink documented
+  - **Compatibility matrix**: AGENTS.md standard supported by Cursor, Windsurf, Cline, GitHub Copilot (see [AI Coding Agents Matrix](https://coding-agents-matrix.dev))
+  - **Machine-readable index**: Added `ai_ecosystem_multi_ide_sync` and `agents_md_support_status` entries to `reference.yaml`
 - **Resource Evaluation: Addy Osmani LinkedIn Post** (scored 2/5, Marginal - Tracking mention only) — Post about Anthropic study (17% comprehension gap) evaluated but not integrated due to 100% overlap with primary source already documented (`docs/resource-evaluations/addy-osmani-linkedin-anthropic-study.md`)
   - **Content**: LinkedIn post (Feb 1, 2026, 246K reach) citing Shen & Tamkin 2026 study on AI-assisted learning
   - **Key claims verified**: 17% comprehension gap, 2-minute productivity gain, "thinking partner vs code vending machine" framing
diff --git a/README.md b/README.md
index 390ce35..c71d54a 100644
--- a/README.md
+++ b/README.md
@@ -485,7 +485,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
 ---
 
-*Version 3.20.8 | February 2026 | Crafted with Claude*
+*Version 3.20.9 | February 2026 | Crafted with Claude*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
diff --git a/VERSION b/VERSION
index c927331..61459b3 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-3.20.8
+3.20.9
diff --git a/guide/ai-ecosystem.md b/guide/ai-ecosystem.md
index d3e9bc3..b67356f 100644
--- a/guide/ai-ecosystem.md
+++ b/guide/ai-ecosystem.md
@@ -1253,6 +1253,80 @@ Cursor's `.cursor/rules` can mirror your CLAUDE.md:
 - Components use render props for flexibility
 ```
 
+### Multi-IDE Configuration Sync
+
+When your team uses multiple AI coding tools (Claude Code + Cursor + Copilot), maintaining consistent conventions across all tools becomes a challenge.
+
+#### The Problem
+
+| Tool | Config File | Format |
+|------|-------------|--------|
+| Claude Code | `CLAUDE.md` | Markdown + @imports |
+| Cursor | `.cursorrules` | Plain markdown |
+| Codex/ChatGPT | `AGENTS.md` | AGENTS.md standard |
+| Copilot | `.github/copilot-instructions.md` | GitHub-specific |
+
+**Without sync**: Each file drifts independently → inconsistent AI behavior across tools.
+
+#### Solution 1: Native @import (Recommended for Claude Code)
+
+Claude Code supports `@path/to/file.md` imports natively:
+
+```markdown
+# CLAUDE.md
+@docs/conventions/coding-standards.md
+@docs/conventions/architecture.md
+```
+
+**Pros**: Native, no build step, maintained by Anthropic
+**Cons**: Cursor/.cursorrules doesn't support @import
+
+#### Solution 2: Script-Based Generation (Multi-IDE Teams)
+
+For teams needing **identical conventions across all IDEs**:
+
+```
+docs/ai-instructions/           # Source of truth
+├── core.md                     # Shared conventions
+├── claude-specific.md          # Claude Code additions
+├── cursor-specific.md          # Cursor additions
+└── codex-specific.md           # AGENTS.md additions
+
+        ↓ sync script (bash/node)
+
+CLAUDE.md     = core + claude-specific
+.cursorrules  = core + cursor-specific
+AGENTS.md     = core + codex-specific
+```
+
+**Example sync script** (bash):
+
+```bash
+#!/bin/bash
+CORE="docs/ai-instructions/core.md"
+
+cat "$CORE" > CLAUDE.md
+echo -e "\n---\n" >> CLAUDE.md
+cat "docs/ai-instructions/claude-specific.md" >> CLAUDE.md
+
+cat "$CORE" > .cursorrules
+echo -e "\n---\n" >> .cursorrules
+cat "docs/ai-instructions/cursor-specific.md" >> .cursorrules
+```
+
+**When to use this approach**:
+- Team with mixed IDE preferences (Claude Code + Cursor + VS Code)
+- Need to enforce identical conventions across all tools
+- CI/CD validation of AI instructions
+
+#### ⚠️ AGENTS.md Support Status
+
+**Claude Code does NOT natively support AGENTS.md** ([GitHub issue #6235](https://github.com/anthropics/claude-code/issues/6235), 171 comments, still open as of Feb 2026).
+
+**Workaround**: Symlink `ln -s AGENTS.md .claude/CLAUDE.md`
+
+The AGENTS.md standard is supported by: Cursor, Windsurf, Cline, GitHub Copilot. See [AI Coding Agents Matrix](https://coding-agents-matrix.dev) for full compatibility.
+
 ### Export from IDE to Claude
 
 When you need Claude's deeper analysis:
diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md
index 5165791..671592c 100644
--- a/guide/cheatsheet.md
+++ b/guide/cheatsheet.md
@@ -6,7 +6,7 @@
 
 **Written with**: Claude (Anthropic)
 
-**Version**: 3.20.8 | **Last Updated**: January 2026
+**Version**: 3.20.9 | **Last Updated**: January 2026
 
 ---
 
@@ -484,4 +484,4 @@ where.exe claude; claude doctor; claude mcp list
 
 **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
 
-*Last updated: January 2026 | Version 3.20.8*
+*Last updated: January 2026 | Version 3.20.9*
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index bba9079..190b8c5 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -10,7 +10,7 @@
 
 **Last updated**: January 2026
 
-**Version**: 3.20.8
+**Version**: 3.20.9
 
 ---
 
@@ -16438,4 +16438,4 @@ We'll evaluate and add it to this section if it meets quality criteria.
 
 **Contributions**: Issues and PRs welcome.
 
-**Last updated**: January 2026 | **Version**: 3.20.8
+**Last updated**: January 2026 | **Version**: 3.20.9
diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml
index e26830a..bc17474 100644
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@@ -3,7 +3,7 @@
 # Source: guide/ultimate-guide.md
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
-version: "3.20.8"
+version: "3.20.9"
 updated: "2026-02-01"
 
 # ════════════════════════════════════════════════════════════════
@@ -500,6 +500,8 @@ deep_dive:
   ai_ecosystem_goose: "guide/ai-ecosystem.md:1116"
   ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132"
   ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1208"
+  ai_ecosystem_multi_ide_sync: "guide/ai-ecosystem.md:1256"
+  agents_md_support_status: "guide/ai-ecosystem.md:1322"
   # Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25
   architecture_diagrams_input: "guide/ai-ecosystem.md:1379"
   architecture_diagrams_mcp_tools:
@@ -927,7 +929,7 @@ ecosystem:
       - "Cross-links modified → Update all 4 repos"
     history:
       - date: "2026-01-20"
-        event: "Code Landing sync v3.20.8, 66 templates, cross-links"
+        event: "Code Landing sync v3.20.9, 66 templates, cross-links"
         commit: "5b5ce62"
       - date: "2026-01-20"
         event: "Cowork Landing fix (paths, README, UI badges)"