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>
2026-02-02 09:04:00 +01:00 · 2026-02-02 09:04:00 +01:00 · 0bb116cd2c
commit 0bb116cd2c
parent d5375e32a5
7 changed files with 91 additions and 8 deletions
--- 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
--- 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,
--- a/2
+++ b/2
@ -1 +1 @@
-3.20.8
+3.20.9
--- 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:
--- 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*
--- 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
--- 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)"
 @ -1 +1 @@
 .20.8
 .20.9