config-export

config-export

将 CLAUDE.md 和 ai-context/ 导出为适用于 GitHub Copilot、Google Gemini 和 Cursor 的原生指令文件。

触发词：/config-export、导出配置、Copilot 指令、Gemini 配置、Cursor 规则

---

用途

config-export 会读取源配置包，让用户选择一个或多个目标 AI 助手，通过大模型转换生成特定工具的指令文件，显示试运行预览，并将经确认的文件写入其规范位置。它绝不会修改源文件，也不会在未经用户明确确认的情况下写入文件。

两种源模式：

• 核心模式（存在 core/ 时优先使用）： agent-config 仓库中与工具无关的 core/ 目录（persona、protocols、methodology、format-types）是唯一真实来源。由于 core/ 已经没有需剥离的内容（没有 ~/.claude/ 路径或斜杠命令），繁重的 STRIP 前置说明可简化为精简的防护说明——请参阅下方的“核心模式下的 STRIP”。通过仓库根目录是否存在 core/PORTABILITY.md 来检测。
• 项目模式（备用）： 如步骤 1 所述，使用使用方项目的 CLAUDE.md 和 ai-context/ 文件。没有 core/ 时使用此模式（即下游使用方项目，而非 agent-config 仓库本身）。

---

流程

步骤 1 — 收集源文件

首先检测模式： 如果仓库根目录存在 core/PORTABILITY.md，则使用核心模式：将 core/instructions/*.md、core/protocols/*.md、core/methodology/*.md 和 core/format-types.md 打包为源文件。跳过下方针对 CLAUDE.md 和 ai-context 的防护步骤（它们仅适用于项目模式），并继续步骤 2。在转换上下文中注明“核心模式 — 中立源”。

否则，使用项目模式并应用下方的防护步骤。

防护 — 没有 CLAUDE.md： 如果当前工作目录中不存在 CLAUDE.md，向用户提供两种路径：

No CLAUDE.md found in the current directory.

Choose an option:
  1. project-setup first  — run /project-setup to scaffold CLAUDE.md + ai-context/ in this project,
                            then re-run /config-export (recommended for new projects with SDD workflow)
  2. SDD bootstrap         — generate a minimal .github/copilot-instructions.md from the global SDD
                            template only (no project-specific stack or conventions)

Enter 1 or 2 (or press Enter to cancel):

• 如果用户选择 1：输出 Run /project-setup, then re-run /config-export 并停止。不写入任何文件。
• 如果用户选择 2：仅使用全局 SDD 方法论作为源文件包（跳过 ai-context/ 收集；在转换上下文中注明“No project CLAUDE.md — bootstrap mode”）。
• 如果用户取消：输出 Export cancelled — no files written 并停止。

防护 — 没有 ai-context/： 如果不存在 ai-context/ 目录，输出：

WARNING: ai-context/ not found — export quality will be lower; only CLAUDE.md will be used as source

继续；仅使用 CLAUDE.md 已足够。

按优先级顺序读取并打包源文件：

#	文件	必需？	缺失时的处理
1	CLAUDE.md	是	停止（参见上方防护步骤）
2	ai-context/stack.md	否	跳过；在转换上下文中注明“stack.md 不可用”
3	ai-context/architecture.md	否	跳过；在转换上下文中注明“architecture.md 不可用”
4	ai-context/conventions.md	否	跳过；在转换上下文中注明“conventions.md 不可用”
5	ai-context/known-issues.md	否	缺失时静默跳过

所有存在的文件都会在开始任何转换前读入上下文包。

---

步骤 2 — 目标选择

如果用户通过 CLI 参数提供了目标（例如，/config-export copilot），则跳过交互式菜单，直接使用该目标进入步骤 3。

否则，显示目标菜单：

Available export targets:

  1. copilot  →  .github/copilot-instructions.md
  2. gemini   →  GEMINI.md
  3. codex    →  AGENTS.md
  4. cursor   →  .cursor/rules/conventions.mdc
               →  .cursor/rules/stack.mdc
               →  .cursor/rules/architecture.mdc
               (adapter spec: adapters/cursor/target.md)
  5. agents   →  per-tool custom-agent render (deterministic)
               →  copilot: .github/agents/<name>.agent.md
               →  cursor:  .cursor/rules/agent-<name>.mdc

Enter targets (comma-separated numbers or names, or "all"):

确定性委派（agents + 命令模式）：agents 目标和命令模式（步骤 3-CMD）属于确定性的信封包装，由独立拆分器提供唯一实现。Bash 可用时，将渲染工作委派给 core/scripts/config-export.sh <tool> <target-project-dir> --constructs=agents（或 --constructs=commands），不要在当前上下文中重新实现包装逻辑——一个实现，零偏差。只有在脚本无法运行时，才回退到当前上下文中的确定性流程（遵循 adapters/<tool>/target.md 的信封部分和 command-mode.md）。Agent 信封规范：adapters/copilot/target.md §「Agent envelope」、adapters/cursor/target.md §「Agent envelope (PROVISIONAL)」。

拒绝 Claude 目标： 如果用户请求的目标是 claude 或 CLAUDE.md，请回复：

The Claude target is not supported in V1 — refresh CLAUDE.md manually

不要写入任何文件；根据用户的选择重新显示菜单或停止。

---

步骤 3 — 试运行生成与确认

对于每个选定的目标，应用对应的转换提示词（完整提示词见 transformation-prompts.md——请参阅下方的「转换提示词」）。然后：

1. 显示每个文件的完整生成内容及其目标路径。
2. 如果目标输出文件已存在于其规范路径，则在确认提示之前发出警告：

   WARNING: Overwriting existing file: <path>
   

3. 提示用户：

   Write these files? [y/N]
   

   默认值为 N。
4. 如果用户的回复不是 y，则正常退出：

   Export cancelled — no files written
   

   不会写入任何文件。
5. 如果用户回复 y，则继续执行步骤 4。

转换提示词（按目标）

完整的转换规范——Shared STRIP 前置提示词以及四个按目标划分的 STRIP/ADAPT/RETAIN/FORMAT 提示词——位于 transformation-prompts.md，以使 此 SKILL.md 保持在 450 行预算内（docs/config-guidelines.md 原则 4）。 生成任何目标之前都要读取该文件——下方的摘要仅供参考，并非规范本身。提示词是通过当前上下文中的大模型推理应用的自指令；不涉及外部 API 调用或子进程。

目标	输出	转换核心
copilot	.github/copilot-instructions.md — 单个扁平文件，H2 章节顺序固定	移除 Claude Code 机制和 Plan Mode；将 SDD 工作流调整为声明式文本，并加入 ## Active SDD Coaching Instructions；## Rules 尽可能保持最高一致性（优先保证一致性，而非简洁）
gemini	项目根目录下的 GEMINI.md — 类似 CLAUDE.md 的 H2/H3 层级结构	移除 SDD DAG 和 Claude 专属的制品存储；将命令表改为文本，不包含斜杠命令
codex	项目根目录下的 AGENTS.md — 扁平结构，预算约 32 KiB，由 Codex 按根目录→当前工作目录合并	与 Copilot 相同的内容规范；将 SDD 工作流改为声明式文本
cursor	.cursor/rules/{conventions,stack,architecture}.mdc — 恰好三个领域文件	按领域拆分；遵循 MDC 前置内容规范（description/globs/alwaysApply；无法推断模式时使用 globs: ""——切勿猜测）

所有目标：应用 Shared STRIP 前置提示词（核心模式下的轻量防护），以生成文件横幅开头（见步骤 4），日期为当天，编码为 UTF-8 且无 BOM。

---

第 3 步 — 命令模式（可调用的 SDD 命令）

命令模式会将 SDD 流水线技能呈现为 Copilot、 Gemini 和 Codex 的可调用命令（通过 /config-export --commands 选择）。它会对中立逻辑进行确定性的封装（参见 ADR-006），并由 BLOCKING STRIP 守卫控制；守卫通过后，会注入每个文件仅执行一次的记忆契约前导内容。

完整的命令模式契约——源范围、各工具封装表、STRIP 守卫以及记忆契约前导内容注入——位于 command-mode.md，以确保此 SKILL.md 不超过 450 行 （docs/config-guidelines.md 原则 4）。运行命令模式前请先阅读。

第 4 步 — 写入文件

对于每个已确认的目标：

1. 如果所需目录不存在，则静默创建：

   • Copilot：.github/
   • Cursor：.cursor/rules/
   • Gemini：无需目录（文件位于项目根目录）
   • Codex：无需目录（AGENTS.md 位于项目根目录）
   • 除非创建失败，否则不要输出任何目录创建相关信息。

2. 将生成的文件写入其规范路径，并在文件开头添加生成文件横幅：

   将 YYYY-MM-DD 替换为今天的日期。

3. 覆盖规范路径下的任何现有文件——这是幂等行为。覆盖时不会报错。

---

第 5 步 — 摘要

所有已确认的文件写入后，打印摘要表：

Export complete — files written:

  File                                  Status
  ──────────────────────────────────    ───────
  .github/copilot-instructions.md       written
  GEMINI.md                             written
  AGENTS.md                             written
  .cursor/rules/conventions.mdc         written
  .cursor/rules/stack.mdc               written
  .cursor/rules/architecture.mdc        written

（仅包含本次运行中已写入目标对应的行。）

然后附上快照提醒：

Exported files are snapshots. Re-run /config-export after significant changes to CLAUDE.md or ai-context/

---

规则

• 如果当前工作目录（CWD）中没有找到 CLAUDE.md，则技能 MUST 在写入任何文件之前显示双路径菜单（project-setup 或 bootstrap）；硬 ERROR 路径不是默认选项
• 即使不存在项目 CLAUDE.md，Bootstrap 模式（选项 2）也 MUST 生成有效的 Copilot instructions 文件，其中包含完整的 SDD 工作流和指导说明
• Copilot 转换 MUST NOT 移除 SDD 阶段工作流或制品路径——必须将其改写为散文和 Copilot 指导说明
• Copilot 输出中 MUST 始终包含 ## SDD Development Workflow 和 ## Active SDD Coaching Instructions 两个部分（无论来自 project 模式还是 bootstrap 模式）
• Dry-run 预览 MUST 在任何文件写入之前进行——没有可跳过 dry-run 的标志
• 覆盖警告 MUST 在 dry-run 步骤中出现（用户确认之前），而不是之后
• 技能 MUST NOT 修改 CLAUDE.md 或任何 ai-context/ 文件——对所有源文件均为只读
• 目录创建（.github/、.cursor/rules/）MUST 保持静默——除非创建失败，否则不输出任何相关信息
• V1 不支持 Claude 目标（CLAUDE.md）——请回复已定义的拒绝消息；不要为该目标写入任何文件
• 所有生成的文件 MUST 使用 UTF-8 编码且不带 BOM
• 每个 Cursor .mdc 文件 MUST 包含有效的 YAML frontmatter，字段为 description、globs 和 alwaysApply
• Cursor .mdc 文件名 MUST 是有效的 slug：仅包含小写字母、数字和连字符，并使用 .mdc 扩展名
• Copilot 输出 MUST 是位于 .github/copilot-instructions.md 的单个文件——不得拆分
• Gemini 输出 MUST 是位于项目根目录 GEMINI.md 的单个文件——不得放在子目录中
• 如果无法推断出有意义的模式，Cursor MDC 文件中的 globs 字段 MUST 使用 ""——绝不可猜测
• 生成文件中的所有内容 MUST 不含 Claude Code 专属执行语法：不得调用 Task 工具，不得使用子 Agent 模式，不得包含 ~/.claude/skills/ 文件路径
• Copilot MUST 转换 SDD 内容（工作流、阶段、制品）——剥离规则仅适用于 Claude Code 执行层语法；所有目标均保留并转换 SDD 方法论
• 任何目标都不得收到 CLAUDE.md 的逐字副本