双工具协同实践¶

本文你会学到：

• 🤔 为什么两者可以在同一台电脑上协同工作
• 🗂️ 扩展体系（Skills / Hooks / MCP / Instructions）哪些可以共享、哪些要各自维护
• 📌 防止配置冗余的单一来源策略
• 🎯 不同任务场景下如何选择工具

🚀 上手路径：三步落地¶

如果你是第一次做双工具协同，按这个顺序落地即可，不要一上来就搭全套：

第一天：在项目根创建一份 CLAUDE.md，删除（或改为符号链接）已有的 .github/copilot-instructions.md

第一周：把共用的 MCP 配置迁到 .mcp.json，凭证换成环境变量

第一月：根据团队实际痛点再考虑 Skills 和 Hooks

大部分团队用好前两步已经足够。

🤔 为什么两者值得同时使用？¶

GitHub Copilot CLI 和 Claude Code 并不是互相替代的关系，它们在设计哲学上有明显分工：

• Copilot CLI 强调 AI 与人类的职责分工——每一步都可以审批确认，内置 GitHub MCP，对 Issue / PR / CI 的原生集成无需额外配置
• Claude Code 强调代理自主性——Sub-agents 并行执行、百万 token 上下文窗口，适合跨越多文件的复杂任务

两者共同遵循 MCP 协议、AGENTS.md 跨平台规范，以及部分相同的扩展目录格式。这意味着你不需要为两个工具各维护一套配置——大多数扩展只需写一份，两者都能读到。

⚙️ 扩展体系协同概览¶

全局层

项目层

共享能力分级¶

可直接共享（高价值）

• 项目指令文件：CLAUDE.md 同时被两个工具读取，维护一份即可
• MCP 服务器配置：.mcp.json 的 mcpServers 字段 schema 完全兼容
• Skills：.claude/skills/ 目录两者均自动加载
• Hooks：.claude/settings.json 的 hooks 字段两者均识别

部分可共享（需注意）

• 忽略文件：Claude Code 默认复用 .gitignore。如需在此之外额外排除（例如 .env.local 参与 git 但不希望 AI 读），在 .claude/settings.json 的 permissions.deny 中声明，而不是新增 .claudeignore。Copilot CLI 直接读 .gitignore
• 自定义斜杠命令：Claude Code 的 ~/.claude/commands/*.md 是其专有机制，Copilot CLI 无完全对等方案，只能手动引用 prompt 片段
• 环境变量：项目级 .env（非密钥部分）两者均可读取，凭证类环境变量各自独立

不能共享

📋 指令层：消除冗余的单一来源策略¶

项目级规范：只写一份 CLAUDE.md¶

最容易产生冗余的地方是项目规范。你可能有这样的疑问：

我用 Copilot CLI 时应该维护 .github/copilot-instructions.md，用 Claude Code 时应该维护 CLAUDE.md——两份文件要同步，太麻烦了。

实际上不需要两份。根据 Copilot CLI 的文档，仓库根目录的 CLAUDE.md 会被 Copilot CLI 自动读取，效果与 AGENTS.md 完全相同。

如果你更倾向于以 AGENTS.md 作为开放规范的统一源（未来迁移其他 AI CLI 更方便），也可以反向建立符号链接：

1
2
3
4
5

# 以 AGENTS.md 为源，CLAUDE.md 作为符号链接
ln -s AGENTS.md CLAUDE.md

# 全局层同理
ln -s ~/.copilot/AGENTS.md ~/.claude/CLAUDE.md

两种方向都可行，关键是**只维护一份**，另一份用符号链接指向它。

推荐结构（项目级）：

1
2
3
4
5
6

项目根目录/
├── CLAUDE.md            ← 单一来源，两个工具都读
└── .github/
    └── instructions/    ← 仅放路径特定指令（按文件类型/目录细化规范）
        ├── typescript.instructions.md
        └── tests.instructions.md

不要同时维护 CLAUDE.md 和 .github/copilot-instructions.md，内容重复不仅需要人工同步，还会双倍消耗上下文 token。较新版本的 Copilot CLI 已支持自动去重（具体版本以官方文档为准），但语义冗余仍然存在。

📊 内容归属决策表¶

在展开具体策略前，先用这张表确定"一条信息应该放哪里"——这是后续两节（三文件同步 + Monorepo 分层）共同遵循的总纲：

三文件同步 和 Monorepo 分层是同一套体系在不同规模下的应用——前者是简单场景，后者是复杂场景。

📄 三文件同步：以 docs/ 为权威来源¶

同时维护 README.md + CLAUDE.md + copilot-instructions.md 时，三份文件极易内容重叠、更新时漏掉一份。根本解法是把"谁是权威来源"按信息类型切分清楚。

推荐目录结构

1
2
3
4
5
6
7
8
9

项目根目录/
├── README.md                     # 面向人类：项目介绍、安装、使用
├── docs/
│   ├── ARCHITECTURE.md           # 架构、技术栈（人和 AI 共用）
│   ├── CONVENTIONS.md            # 代码约定、命名规则（人和 AI 共用）
│   └── COMMANDS.md               # 常用命令（测试 / 构建 / lint）
├── CLAUDE.md                     # 仅 Claude 特有的偏好 / 提醒
└── .github/
    └── copilot-instructions.md   # 仅 Copilot 特有的偏好 / 提醒

docs/ 里的文件是权威来源，CLAUDE.md 和 copilot-instructions.md 都**引用**它们，不复制内容。

README.md（只给人看，不写 AI 指令）

在 README 里塞"请遵循 xxx"之类的 AI 指令，会让人类读者困惑，也让 README 失焦。只写项目入口，链接到 docs/：

1
2
3
4

## 开发者文档
- 架构说明：docs/ARCHITECTURE.md
- 代码约定：docs/CONVENTIONS.md
- 常用命令：docs/COMMANDS.md

CLAUDE.md（只写 Claude 特有内容，用 @ 引用共享文档）

Claude Code 支持 @文件路径 语法，会自动把引用的文件加载进上下文，无需复制内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Claude Code 工作指引

请先阅读以下文件了解项目：
- @docs/ARCHITECTURE.md
- @docs/CONVENTIONS.md
- @docs/COMMANDS.md

## Claude 特定约定
- 修改任何 migration 文件前先询问
- 新增依赖前说明理由
- 提交信息用中文，遵循 Conventional Commits

.github/copilot-instructions.md（只写 Copilot 特有内容）

Copilot CLI 没有 @ 引用机制，但在需要时会读取被提到的文件路径：

1
2
3
4
5
6
7
8

# Copilot 工作指引

项目架构见 docs/ARCHITECTURE.md
代码约定见 docs/CONVENTIONS.md
常用命令见 docs/COMMANDS.md

## Copilot 特定约定
- 生成代码前优先参考现有模式

效果：更新技术栈只改 docs/ARCHITECTURE.md 一处，三个地方自然同步，不会漂移。

进阶：用生成脚本代替手动引用（不推荐作为默认方案）

@ 引用是懒加载机制，比拼接文件更省 token，默认应优先使用引用方式。以下场景才考虑生成脚本：

1. 目标工具不支持文件引用
2. CI 机器人需要单文件投喂
3. 需要给非 AI 系统（如合规审计）产出快照

1
2
3
4
5
6
7
8

#!/bin/bash
# 拼装 CLAUDE.md：共享文档 + Claude 特有尾部
cat docs/ARCHITECTURE.md docs/CONVENTIONS.md docs/COMMANDS.md > CLAUDE.md
cat .claude/claude-specific.md >> CLAUDE.md

# 拼装 copilot-instructions.md：共享文档 + Copilot 特有尾部
cat docs/ARCHITECTURE.md docs/CONVENTIONS.md docs/COMMANDS.md > .github/copilot-instructions.md
cat .github/copilot-specific.md >> .github/copilot-instructions.md

⚠️ 生成产物建议加入 .gitignore 并在 pre-commit 时再生成，避免 PR diff 噪音。如果生成产物参与 Git，还需要在 CI 里跑一遍脚本，维护成本明显高于引用方式。

目录级规范：各有所长¶

全局个人配置：各自有侧重¶

这两份全局文件不能共享，但写法应该互补而非重复：

1
2
3
4
5

~/.claude/CLAUDE.md  → 给 Claude Code 的个人规范
    关注：角色定义、回复语言、思考风格、输出格式、会话持续规则

~/.copilot/copilot-instructions.md  → 给 Copilot CLI 的个人偏好
    关注：语言偏好、编码风格个人倾向（项目规范在项目级写）

🧩 Skills：共用一套工作流¶

共享目录结构¶

把所有 Skill 放在 .claude/skills/，两个工具都会自动加载：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

项目根目录/
└── .claude/
    └── skills/
        ├── code-review/
        │   └── SKILL.md        ← Claude Code 和 Copilot CLI 都自动加载
        ├── doc-generator/
        │   └── SKILL.md
        └── e2e-testing/
            ├── SKILL.md
            └── example.ts      ← 辅助文件，两者都能引用

个人级全局 Skill 放在 ~/.claude/skills/，同样两者共享。

Frontmatter 写法：核心字段通用，高级字段各自处理¶

两者的 SKILL.md 格式高度兼容，name 和 description 是通用字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

---
name: code-review
description: 代码审查。当用户要求审查代码、检查代码质量或进行安全审计时自动激活。
disable-model-invocation: false
---

# 代码审查规范

## 审查维度
1. 类型安全与空值处理
2. 错误处理（禁止 catch 后静默忽略）
3. 安全性（SQL 注入、XSS、路径遍历）
4. 性能（N+1 查询、不必要的全表扫描）

## 输出格式
- 📍 位置（文件:行号）
- 🏷️ 类别
- 📝 问题描述
- ✅ 修复建议

disable-model-invocation、model、effort、context: fork 等 Claude Code 专有字段，Copilot CLI 会忽略但不报错，不影响使用。

🪝 Hooks：共用 settings.json¶

写在 .claude/settings.json，两者均读¶

.claude/settings.json 中的 hooks 字段被两个工具共同识别。推荐使用 Claude Code 的嵌套 matcher/hooks 格式——较新版本的 Copilot CLI 已完全兼容（具体版本以官方文档为准）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILEPATH\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/check-dangerous-cmd.sh"
          }
        ]
      }
    ]
  }
}

Hook 配置分层¶

⚠️ 不要在 .claude/settings.json 和 .github/hooks/ 中写同一个逻辑，会触发两次。

🔌 MCP：共用 .mcp.json¶

项目级 MCP：写一份，两者共用¶

.mcp.json（项目根目录）是两个工具的共同 MCP 配置文件：

1
2
3
4
5
6
7
8
9

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

全局 MCP：分别配置¶

需要某个 MCP 服务器只在一个工具中使用时，放到对应的全局配置中，不要放进 .mcp.json。

🔐 密钥与凭证的边界¶

.mcp.json 会提交 Git，是最容易翻车的地方，值得单独关注：

.mcp.json 中只能出现 ${ENV_VAR} 形式的占位符，真实值写在本地 .env 或操作系统 keychain。团队共用密钥用 1Password / Vault 等工具下发，绝不提交 Git——哪怕是"临时测试"。

推荐在仓库根目录放 .env.example 示范环境变量命名，新人 clone 后复制为 .env 填入实际值即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "mcpServers": {
    "my-service": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "API_KEY": "${MY_SERVICE_API_KEY}"
      }
    }
  }
}

🗂️ 推荐共享策略总结¶

根据以上各节的分析，最终推荐三条落地原则：

1. 项目指令文件：选定一份，符号链接另一份 以 CLAUDE.md 或 AGENTS.md 二选一作为事实源（推荐 CLAUDE.md，Claude Code 和 Copilot CLI 均自动识别），另一侧用 ln -s 指向它。新团队成员无论用哪个工具都能读到统一规范。

2. MCP 配置集中管理 把团队共用的 MCP 服务器（GitHub、文件系统、数据库等通用工具）统一放在项目根目录的 .mcp.json 并提交 Git。工具专有或含密钥的 MCP 单独放在各自的全局配置中（~/.claude.json / ~/.copilot/mcp-config.json），通过环境变量引用 API key，不硬编码。

3. 全局个人偏好各自维护，内容互补而非重复 ~/.claude/CLAUDE.md 侧重 Claude Code 专有特性（角色定义、Sub-agents 触发词、会话持续规则）；~/.copilot/copilot-instructions.md 侧重 Copilot CLI 特有约定。两份文件不求一致，但不要相互复制导致语义冗余。

🎯 任务分工：选对工具事半功倍¶

真正决定工具选择的核心因素是**任务的可中断性**：

场景速查

🏗️ Monorepo / 多仓库场景：分层上下文管理¶

多仓库场景下，AI 工具面临一个三角矛盾：需要全局视野来协调跨项目任务，又需要局部细节来干活，还不能每次把所有文档都塞进上下文。解决方案是把文档像代码一样做模块化——分层加载 + 按需引用。

推荐目录结构¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

workspace/
├── README.md                       # 工作区总览：有哪些项目、怎么协同
├── CLAUDE.md                       # 根级 AI 指引：路由 + 跨项目规则
├── .github/copilot-instructions.md # 同上，给 Copilot
├── docs/
│   ├── ARCHITECTURE.md             # 全局架构：服务拓扑、数据流
│   ├── CONVENTIONS.md              # 跨项目共享约定
│   └── WORKFLOWS.md                # 跨项目工作流（联调、发布）
├── apps/
│   ├── web-frontend/
│   │   ├── README.md               # 这个前端的介绍
│   │   ├── CLAUDE.md               # 前端特定的 AI 指引
│   │   └── docs/CONVENTIONS.md     # 前端特定约定（覆盖全局）
│   └── api-backend/
│       ├── README.md
│       ├── CLAUDE.md
│       └── docs/
├── packages/
│   ├── shared-types/               # 前后端共享的 API 契约
│   │   ├── README.md
│   │   └── CLAUDE.md               # 可选，简单库可不写
│   └── ui-components/
└── services/
    └── auth-service/
        ├── README.md
        └── CLAUDE.md

Claude Code 的分层加载特性¶

Claude Code 会**自动向上递归查找 CLAUDE.md**——当你在 apps/web-frontend/ 下工作时，它同时加载：

• apps/web-frontend/CLAUDE.md（局部，覆盖优先）
• workspace/CLAUDE.md（根级，全局规则）

利用这个机制，根级写全局规则，子项目级写特殊规则，自然形成局部覆盖全局的层叠效果。

根级 CLAUDE.md：只当"调度台"¶

根目录的 CLAUDE.md 不写实现细节，只做三件事——列项目地图、写跨项目规则、引用共享文档：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Workspace AI 指引

## 项目地图
本工作区包含以下子项目，进入对应目录前请先阅读其 CLAUDE.md：
- apps/web-frontend/      — React 前端，见 @apps/web-frontend/CLAUDE.md
- apps/api-backend/       — Go 后端 API，见 @apps/api-backend/CLAUDE.md
- packages/shared-types/  — TS 类型定义（前后端共用）
- services/auth-service/  — 独立鉴权微服务

## 跨项目全局规则
- 共享类型**必须**放 packages/shared-types，禁止在 app 里重复定义
- API 契约变更需同步更新 shared-types 并通知前后端
- 跨项目重构前先检查 docs/ARCHITECTURE.md 的依赖关系

## 工作流
- 全局架构：@docs/ARCHITECTURE.md
- 联调/发布：@docs/WORKFLOWS.md
- 通用约定：@docs/CONVENTIONS.md

## 路由提示
用户问题涉及单个子项目时，优先读该子项目的 CLAUDE.md，
不要把所有子项目文档都加载进来。

子项目 CLAUDE.md：聚焦局部¶

子项目 CLAUDE.md 只写这个项目自己的事——技术栈、特定约定、常用命令、与其他项目的关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# web-frontend AI 指引

## 技术栈
Next.js 14 App Router + TypeScript + Tailwind + TanStack Query

## 本项目特定约定
- 组件用函数式，禁用 class 组件
- 状态管理优先 React Query，全局状态用 Zustand
- 样式只用 Tailwind，禁止写 .css 文件
- API 调用必须用 packages/shared-types 的类型

## 常用命令
pnpm dev / pnpm test / pnpm build

## 与其他项目的关系
- 调用 apps/api-backend 的 REST API（见 src/lib/api-client.ts）
- 使用 packages/ui-components 的组件
- 鉴权对接 services/auth-service（OIDC 流程）

Copilot CLI 的适配¶

Copilot CLI 的 .github/copilot-instructions.md **不会**像 Claude Code 那样自动分层加载，需要手动处理：

Claude Code 在多仓库场景的原生支持明显更强——这也是它更适合跨项目复杂任务的原因之一。

四条防冗余硬规则¶

规则一：README.md 永远不写 AI 指令 子项目 README 就是给人看的——介绍这个模块做什么、怎么跑起来。AI 指令统一走 CLAUDE.md。

规则二：全局信息只在根 docs/ 写一次 "用什么数据库"、"服务怎么部署"这类跨项目事实，只在 docs/ARCHITECTURE.md 写。子项目 CLAUDE.md 里引用：完整架构见 @../../docs/ARCHITECTURE.md。

规则三：局部信息只在子项目写 前端用什么 UI 库，不要污染根 CLAUDE.md。根 CLAUDE.md 只负责"告诉 AI 去哪找"，不负责"AI 该知道什么"。

规则四：跨项目契约单独放一处，代码即文档 前后端共享的 API schema、事件格式、错误码——最容易两边各写一份造成漂移。正确做法是放 packages/shared-types 或 OpenAPI 文件里，两边 CLAUDE.md 都指向它。

上下文预算¶

AI 工具的上下文窗口再大也是有限的，尤其在大 monorepo 里。给 CLAUDE.md 设个硬性预算：

• 根 CLAUDE.md：不超过 100 行 — 只做路由和全局规则
• 子项目 CLAUDE.md：不超过 200 行 — 聚焦本项目
• 超出就拆到 docs/ 下，按需用 @ 引用

这样无论 AI 在哪个子目录工作，加载的上下文都是精准的、不冗余的。

决策树：一条信息该放哪里？¶

面对一条新内容，问三个问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

给谁看？
├── 只给人看       → README.md
├── 只给 AI 看     → CLAUDE.md
└── 都需要看       → docs/ARCHITECTURE.md 或 docs/CONVENTIONS.md

作用范围？
├── 全局（跨项目） → 根目录 docs/ 或根目录 CLAUDE.md
└── 单项目局部    → 子项目 CLAUDE.md

是否是跨项目契约？
├── 是             → packages/ 或 docs/，两边 @引用
└── 否             → 放在实际负责该逻辑的子项目下

🚫 防冗余检查清单¶

在添加新配置前，先过一遍这个清单。建议把下方脚本挂到 pre-commit 或 CI，比人工勾选可靠得多：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#!/bin/bash
# 检查双工具配置是否存在常见冗余
set -e

if [ -f "CLAUDE.md" ] && [ -f ".github/copilot-instructions.md" ] \
   && [ ! -L ".github/copilot-instructions.md" ]; then
  echo "⚠️  CLAUDE.md 与 copilot-instructions.md 同时存在且非符号链接"
fi

if [ -f ".mcp.json" ]; then
  if grep -qE '"(api[_-]?key|token|secret)"\s*:\s*"[^$]' .mcp.json; then
    echo "⚠️  .mcp.json 中疑似硬编码密钥，应改用环境变量"
  fi
fi

# 检查 hooks 是否双份定义
if [ -f ".claude/settings.json" ] && [ -d ".github/hooks" ]; then
  echo "ℹ️  .claude/settings.json 和 .github/hooks/ 同时存在，请确认没有重复逻辑"
fi

人工检查清单

指令类

• 我是否同时维护了 CLAUDE.md 和 .github/copilot-instructions.md？→ 只保留 CLAUDE.md
• 我是否在多个层级（全局、项目、子目录）写了重复的规则？→ 合并到最高覆盖层级
• 路径特定规范是否已从 CLAUDE.md 拆到 .github/instructions/*.instructions.md？→ 减少两者的固定上下文占用

Skills 类

• Skills 是放在 .github/skills/ 还是 .claude/skills/？→ 统一放 .claude/skills/（两者共享）
• 是否有两个 Skill 做同一件事？→ 合并为一个，description 覆盖两个触发场景

Hooks 类

• 同一逻辑是否同时出现在 settings.json 和 .github/hooks/ 中？→ 删掉其中一份
• Hook 脚本是否产生了大量 stdout？→ 重定向到文件，避免污染上下文

MCP 类

• 团队共用的 MCP 是否放在 .mcp.json 并提交了 Git？→ 应该放在此处
• 含 API Key 的 MCP 是否误提交了 Git？→ 放到各自工具的全局配置中，或用环境变量替代

⚠️ 什么情况下不要共享¶

共享配置在大多数项目中利大于弊，但以下场景**共享反而是负担**，直接用默认路径即可：

不要过度工程化——只在团队协作的、长期维护的项目中引入完整共享体系。