AI 编码助手配置体系

保留你熟悉的 CLI/IDE，让 Claude Code、Gemini CLI、Codex、Cursor 开箱即用

按费力度从低到高，用最少操作获得最大帮助

不是提示词集合，而是一套可维护的 AI 协作配置系统。

适合谁

• 同时使用 Claude Code、Gemini CLI、Codex、Cursor 中的一种或多种 CLI/IDE
• 不想在每个 session 里重复交代技术栈、项目结构和编码规范
• 希望把团队协作方式沉淀成可维护的 rules、skills 和 workflow
• 想降低 AI 常见翻车和危险操作风险

核心收益

• 一次维护，四套工具分别同步到各自用户级入口
• 分层加载（rules 常驻 + skills 按需 + workflow 显式调用），减少常驻上下文负担
• 内置防御性规则，降低修改测试适配错误、危险命令、过度重构等常见问题
• 保留你熟悉的 CLI，不强迫切换到新的交互方式

本项目的重点不是继续堆更长的提示词，而是把长期会反复出现的协作约定拆成可维护的结构：全局原则、审批规则、语言技能和任务 workflow 各司其职。

快速部署

一键同步（推荐）

macOS/Linux：

./tools/sync-config.sh

Windows：

tools\sync-config.bat

脚本会自动同步四套配置：

• .claude/ → ~/.claude/
• .gemini/ → ~/.gemini/
• .codex/global/AGENTS.md → ~/.codex/AGENTS.md（受管区块合并）
• .codex/global/rules/ → ~/.codex/rules/
• .codex/skills/ → ~/.agents/skills/
• .codex/profiles/*.toml → ~/.codex/config.toml（受管区块合并）
• .cursor/rules/*.mdc → ~/.cursor/rules/（兼容性同步，项目内 .cursor/rules/ 仍是主路径）
• .cursor/skills/* → ~/.cursor/skills/
• .cursor/commands/*.md → ~/.cursor/skills/{name}/SKILL.md（命令式技能兼容层）
• .cursor/templates/* → ~/.cursor/templates/

其中 Codex 采用增量部署：

• 不会整体覆盖 ~/.codex/
• 不会动 auth.json、history.jsonl、日志、sqlite、cache 等运行态文件
• 只维护当前项目负责的 AGENTS 受管区块、cc-* rules 和 cc-* skills

各工具的部署特性：

• Claude Code：同步到 ~/.claude/，并保留历史对话记录和个人配置
• Gemini CLI：同步到 ~/.gemini/，并保留认证信息（如 oauth_creds.json）和运行时数据
• Codex：对 ~/.codex/AGENTS.md 和 ~/.codex/config.toml 使用受管区块合并；只管理 ~/.codex/rules/ 与 ~/.agents/skills/ 下当前项目同步出去的 cc-* 内容；不改用户已有默认模型、provider 或 base_url
• Cursor：项目内 .cursor/rules/ 仍是主路径；脚本会把 skills、templates 和命令式技能兼容层同步到用户级目录，并将 .cursor/rules/*.mdc 兼容性同步到 ~/.cursor/rules/；保留 ~/.cursor 下的 settings、extensions、cache 等运行态文件

支持的工具

• 适合谁
• 核心收益
• 快速部署
• 支持的工具
• 项目定位
• Part 1: Claude Code
  • 快速开始
  • 常见场景速查
  • ToolSearch 支持
  • 目录结构
• Part 2: Gemini CLI
  • 快速开始
  • 前端场景速查
• Part 3: Codex
• Part 4: Cursor
  • 快速开始
  • Commands
  • 目录结构
• 参考资料
• 社区与支持
• 许可声明

项目定位

使用架构

本项目                      用户目录                               其他项目
├── .claude/  ──覆盖──>    ~/.claude/  <──读取──                 .claude/ (空)
├── .gemini/  ──覆盖──>    ~/.gemini/  <──读取──                 .gemini/ (空)
├── .codex/   ──增量部署──> ~/.codex/ + ~/.agents/skills/ <──读取── .codex/ (空)
└── .cursor/  ──项目内 rules + 用户级兼容同步──> ~/.cursor/skills/ + ~/.cursor/templates/ <──读取── .cursor/ (空)

• 本项目：配置开发/维护环境，不参与实际业务开发
• 用户目录：实际生效的配置
• 其他项目：配置目录为空，自动使用用户目录配置

四套配置的关系

四者相互独立：

• Claude Code 只读取 ~/.claude/，不读取 ~/.gemini/
• Gemini CLI 只读取 ~/.gemini/，不读取 ~/.claude/
• Codex 的全局入口是 ~/.codex/AGENTS.md、~/.codex/rules/ 和 ~/.agents/skills/
• Cursor 以当前项目 .cursor/rules/ 为主；跨项目复用的技能和命令式技能主要通过 ~/.cursor/skills/ 提供
• 配置内容可能相似（如禁止行为、技术栈偏好），但这不是重复，而是各自需要的独立配置

配置能力差异

规则同步方式：

• Claude Code：规则拆分到 rules/ 目录，按文件组织；技能放 skills/ 按需加载
• Gemini CLI：核心规则在 GEMINI.md；详细规范通过 skills/ 按需激活（v0.24.0+）
• Codex：全局仅保留极薄 AGENTS.md 和审批 rules；绝大多数通用规范放进 skills，通过渐进式披露按需加载
• Cursor：规则用 .mdc 格式支持 alwaysApply / globs / 智能匹配；技能通过 description 语义匹配按需加载；用户级 ~/.cursor/rules/ 同步仅作为兼容性补充

如需在多个工具间同步规则（如禁止行尾注释），需分别在 .claude/rules/bash-style.md、.gemini/GEMINI.md、.cursor/rules/bash-style.mdc 中维护。

Part 1: Claude Code 配置

1. 快速开始

1.1 零费力（自动生效）- Rules

你需要做什么：什么都不用做

这些规则始终自动加载，在后台默默保护你：

效果示例：

• Claude 不会修改测试来适配错误代码
• 执行 sysctl 等危险命令前会提示风险和回滚方案
• 新增命令后会提醒你更新 README

1.2 低费力（自动触发）- Skills

你需要做什么：正常写代码

操作相关文件时自动加载对应的开发规范：

效果示例：

• 写 Go 代码时，自动遵循 Effective Go 规范
• 写 Vue 组件时，自动使用 Composition API + TypeScript
• 不操作这些文件时，不消耗额外 token

1.3 中费力（显式调用）- Commands

你需要做什么：输入 /命令名

高频命令（日常使用）

中频命令（按需使用）

低频命令（特定场景）

1.4 Claude Code 推荐插件（声明式安装）

本项目通过 .claude/plugins.json 声明了推荐的插件。

推荐安装方式：
运行 ./tools/sync-config.sh，脚本会自动检测缺失的插件并引导你一键安装。

手动安装：

claude plugin install context7@claude-plugins-official
claude plugin install frontend-design@claude-plugins-official
# ... 其他插件同理

2. 常见场景速查

遇到 Bug？
├─ 简单 Bug → /fix 问题描述
└─ 复杂 Bug → /fix debug 问题描述

代码审查？
├─ 快速看看 → /review quick
├─ 正式审查 → /review
└─ 安全审查 → /review security

新功能？
├─ 完整流程 → /new-feature 功能名
└─ 只要设计 → /design doc 模块名

系统优化？
├─ 全量评估 → /optimize
├─ 仅性能 → /optimize perf
├─ 仅代码质量 → /optimize code
└─ 仅 UX → /optimize ux

3. 综合补丁工具

补丁项一览

支持的安装方式

bun 官方二进制 / npm / pnpm / Homebrew / VS Code / Cursor

使用方法

1. 一键全部补丁（推荐）

/patch

2. 查看全部补丁状态

/patch status

3. 单独管理某项补丁

/patch toolsearch    # ToolSearch 域名解除
/patch cache         # 1h Prompt Cache
/patch tui           # 交互式 TUI（Chrome/Context/Auth/Collapse）
/patch restore       # 还原 patch-claude.py 管理的补丁

注意：Claude Code 更新后补丁会被覆盖，需重新执行 /patch。

4. 最佳实践

4.1 让自动化为你工作

• 不要干预 Rules：它们在后台保护你，比如防止 Claude 修改测试
• 不要手动加载 Skills：操作相关文件时自动生效
• 相信防御机制：复杂任务会自动要求确认计划后再执行

4.2 避免的做法

• ❌ 不要绕过 Rules 的保护机制
• ❌ 不要在简单任务上使用复杂命令
• ❌ 不要忽略文档同步提醒

4.3 上下文管理（省 token）

• 一个 session 一个任务，避免"顺便再帮我..."加速上下文膨胀
• 旁路问题用 /btw，问答不写入对话历史，不消耗上下文
• 长任务在 60-70% 时主动 /compact，compact 前先把关键决策记到任务文件
• 大文件用 Grep 定位 + Read 局部读取，避免整文件加载

5. 常见问题

Q: 为什么 Claude 总是先说明计划再执行？

A: 这是 claude-code-defensive.md 规则的要求。复杂任务（超过 3 个步骤或涉及多个文件）必须先说明计划，等你确认后再执行。这是为了防止 Claude 盲目修改代码。

Q: 为什么执行系统命令时 Claude 会问很多问题？

A: 这是 ops-safety.md 规则的要求。危险命令（如 sysctl、iptables）必须说明影响范围、风险等级和回滚方案。这是为了防止误操作导致系统故障。

Q: 为什么 Claude 提醒我更新文档？

A: 这是 doc-sync.md 规则的要求。当你修改了配置（commands/skills/rules）或项目结构时，会提醒你同步更新相关文档，保持文档与代码一致。

Q: 如何添加新的语言支持？

A: 在 .claude/skills/ 下创建新目录（如 rust-dev/），添加 SKILL.md 文件定义触发条件和规范内容，然后更新本文档。

6. 目录结构

.claude/
├── CLAUDE.md                     # 核心配置：身份、偏好、技术栈
├── rules/                        # 规则：始终加载（精简版）
│   ├── claude-code-defensive.md  # 防御性规则
│   ├── ops-safety.md             # 运维安全（核心）
│   ├── doc-sync.md               # 文档同步
│   ├── bash-style.md             # Bash 核心规范
│   └── date-calc.md              # 日期计算规则
├── skills/                       # 技能：按需加载（完整版）
│   ├── go-dev/
│   ├── java-dev/
│   ├── frontend-dev/
│   ├── python-dev/
│   ├── bash-style/               # Bash 完整规范
│   ├── ops-safety/               # 运维安全完整规范
│   ├── redis-safety/             # Redis 安全与性能规范
│   ├── size-check/               # 代码简化 + 文件行数扫描
│   └── ruanzhu/                  # 软著源代码生成
├── commands/                     # 命令：显式调用
│   ├── fix.md                    # 快速修复 / 系统化调试
│   ├── review.md                 # 代码审查（full/quick/security）
│   ├── design.md                 # 技术设计（doc/checklist）
│   ├── requirement.md            # 需求分析（doc/interrogate）
│   ├── optimize.md               # 系统优化（full/ux/perf/code）
│   ├── check-toolsearch.md      # ToolSearch 可用性检查
│   ├── ruanzhu.md                # 软著源代码 DOCX 生成
│   ├── status.md
│   └── ...
└── templates/                    # 模板文件
    └── ruanzhu/                  # 软著生成脚本

tools/                            # 工具脚本（不同步到 ~/.claude/）
├── patch-toolsearch.py           # ToolSearch 域名限制解除补丁
├── sync-config.sh                # 配置同步脚本（macOS/Linux）
└── sync-config.bat               # 配置同步脚本（Windows）

核心概念

Rules 与 Skills 的关键区别

重要：Rules 的 paths frontmatter 只是语义提示，不影响加载。

最佳实践：

• Rules 保持精简（核心禁止项），详细规范放 Skills
• 例如 bash-style：rules 放 37 行核心规则，skills 放 200+ 行完整规范

设计理念

1. 按需加载：语言规范用 Skills，只在操作相关文件时加载，节省 tokens
2. 规则溯源：每次回复声明依据的规则/技能，便于追踪和调整
3. 简洁优先：CLAUDE.md 只放身份/偏好，具体约束放 rules

7. 开发指南

LSP 服务器配置（v2.0.67+ 支持）

前提：需安装 @anthropic-ai/[email protected] 或更高版本。

安装命令

# Go
go install golang.org/x/tools/gopls@latest

# TypeScript/JavaScript + Vue
npm install -g typescript typescript-language-server @vue/language-server

# Python
npm install -g pyright

# Java (macOS)
brew install jdtls

LSP 使用策略

LSP 的核心优势是"精准打击"——查找定义时只返回相关代码，而非整个文件，可节省大量 Token。

注意事项

• 环境就绪：使用前确保依赖已安装（npm install / go mod download）
• 避免过度依赖：复杂逻辑需要读取完整文件上下文
• LSP 失败时：退回到读取文件的方式

修改现有配置

1. 在 .claude/ 下修改对应文件
2. 在本项目目录启动 Claude Code 测试
3. 验证功能符合预期
4. 复制到 ~/.claude/ 正式使用

新增命令（Command）

1. 创建 .claude/commands/<name>.md
2. 编写 frontmatter（description）和内容
3. 测试 /<name> 命令
4. 更新本文档的命令列表

命令模板：

---
description: 命令的简要描述
---

命令的详细说明和执行逻辑。

## 输入

「$ARGUMENTS」— 用户输入的参数

## 流程

### 第 1 步：...
### 第 2 步：...

## 输出格式

...

新增技能（Skill）

1. 创建 .claude/skills/<name>/SKILL.md
2. 编写 frontmatter（name、description）和内容
3. 可选：添加 references/ 目录存放详细参考
4. 测试触发是否正确
5. 更新本文档的技能列表

技能模板：

---
name: skill-name
description: 当用户操作 xxx 文件时触发。提供 xxx 开发规范。
---

# 技能名称

## 核心规范

...

## 详细参考

详细内容见 `references/` 目录。

测试验证

# 在本项目目录启动 Claude Code
cd /path/to/cc-use-exp
claude

# 测试命令
> /fix 测试问题

# 测试技能（操作相关文件类型）
> 帮我看看这个 Go 代码有什么问题

# 检查配置加载
> /memory

Part 2: Gemini CLI 配置（前端设计）

定位：Gemini CLI 专注于前端设计和开发，技术栈为 Vue 3 + TypeScript + Element Plus。

1. 快速开始

1.1 零费力（自动生效）- GEMINI.md

你需要做什么：什么都不用做

GEMINI.md 自动加载，提供以下保护：

效果示例：

• Gemini 不会生成"AI 风格"的炫酷 UI
• 默认使用 Element Plus 主题，保持企业后台风格
• 自动使用 Composition API + TypeScript

1.2 低费力（自动触发）- Skills

你需要做什么：正常写代码

修改对应语言的文件或调整页面布局时，Gemini 会自动激活对应技能（独立维护在 .gemini/skills/，语义与其他工具保持一致）：

效果示例：

• 修改 Vue 组件时，自动保护数据绑定和事件不被意外修改
• 调整布局时，确保间距使用 4px 倍数、与其他页面一致
• 开发 Go 或 Java 代码时，Gemini CLI 同样能提供专业的编码规范支持

1.3 中费力（显式调用）- Commands

你需要做什么：输入 /命令名

1.4 Gemini CLI 推荐扩展（声明式安装）

本项目通过 .gemini/extensions.json 声明了推荐的扩展。

推荐安装方式：
运行 ./tools/sync-config.sh，脚本会自动检测缺失的扩展并引导你一键安装。

手动一键安装：

gemini extensions install https://github.com/upstash/context7 && \
gemini extensions install https://github.com/ChromeDevTools/chrome-devtools-mcp

更多扩展请访问：Gemini Extensions 商店

2. 前端场景速查

布局问题？
├─ 简单调整 → /fix 问题描述
├─ 整体重构 → /layout 文件路径
└─ 一致性检查 → /layout-check

组件开发？
├─ 新组件 → 描述需求，让 Gemini 生成
└─ 改现有 → 先 /quick-review 或 /code-review，再修改

样式问题？
├─ 单个元素 → /fix 样式描述
└─ 整体风格 → 检查是否符合 Element Plus 规范

3. 最佳实践

3.1 UI 风格约束

后台管理系统（默认风格）

严格禁止：

• ❌ 蓝紫色霓虹渐变、发光描边
• ❌ 玻璃拟态（glassmorphism）
• ❌ 赛博风、暗黑科技风
• ❌ 大面积渐变、装饰性几何图形
• ❌ UI 文案中使用 emoji

3.2 Vue 组件规范

<!-- ✅ 推荐写法 -->
<script setup lang="ts">
import { ref, computed } from 'vue'
import type { User } from '@/types'

const props = defineProps<{
  userId: number
}>()

const loading = ref(false)
const user = ref<User | null>(null)
</script>

<template>
  <div class="user-card">
    <!-- 内容 -->
  </div>
</template>

<style scoped>
.user-card {
  padding: 16px;
}
</style>

3.3 MCP 工具使用

Context7 查询示例：

帮我查一下 Element Plus 的 Table 组件如何实现可编辑单元格

3.4 避免的做法

• ❌ 不要让 Gemini 自由发挥 UI 设计
• ❌ 不要忽略 Element Plus 现有组件
• ❌ 不要在简单问题上用复杂命令
• ❌ 不要跳过代码审查直接提交

4. 常见问题

Q: Gemini 生成的 UI 太花哨怎么办？

A: GEMINI.md 中已有 UI 风格约束。如果还是生成花哨样式，可以明确说：

请使用 Element Plus 默认主题，保持简洁的后台管理风格，不要使用渐变和装饰性元素

Q: 如何让 Gemini 查最新的 Vue 文档？

A: Gemini 会自动调用 Context7 查询文档。你也可以直接说：

帮我查一下 Vue 3 的 defineModel 怎么用

Q: /layout 命令支持什么输入？

A: 支持以下输入方式：

• 文件路径：/layout src/views/Home.vue
• URL：/layout https://example.com
• 描述需求：/layout 把这个页面改成左右两栏布局

Q: 组件太复杂，Gemini 生成不完整怎么办？

A: 分步骤处理：

1. 先让 Gemini 生成组件框架
2. 逐个功能点完善
3. 最后 /code-review 检查

5. 目录结构

.gemini/
├── .env.example        # 网络代理配置模板（需重命名为 .env）
├── GEMINI.md           # 核心规则（通过 @import 引入 rules）
├── settings.json       # 用户设置
├── policies/           # 安全策略（允许 git 等命令执行）
│   ├── git-rules.toml
│   └── help-rules.toml
├── rules/              # 规则：通过 @import 始终加载
│   ├── defensive.md        # 防御性编码规范
│   ├── doc-sync.md         # 文档同步规范
│   ├── ops-safety.md       # 运维安全规范
│   ├── file-size-limit.md  # 文件行数限制
│   └── frontend-style.md   # 前端规范补充
├── skills/             # 技能：按需激活（v0.24.0+）
│   ├── bash-style/
│   ├── frontend-safety/
│   ├── go-dev/
│   ├── java-dev/
│   ├── ops-safety/
│   └── python-dev/
└── commands/           # 自定义命令（.toml 格式）
    ├── layout.toml         # 布局重构
    ├── layout-check.toml   # 布局一致性检查
    ├── vue-split.toml      # Vue 文件拆分
    ├── fix.toml            # 快速修复
    ├── debug.toml          # 系统化调试
    ├── code-review.toml    # 正式审查
    ├── quick-review.toml   # 快速审查
    ├── commit-msg.toml     # 生成 commit message
    └── patch-http.toml     # 解除 HTTP Base URL 限制
├── scripts/            # 辅助脚本
    └── patch-http.sh       # 补丁执行脚本

6. 配置层级

Gemini CLI 支持层级配置，优先级从低到高：

1. 系统默认 → /etc/gemini-cli/
2. 用户全局 → ~/.gemini/
3. 项目级 → <project>/.gemini/
4. 环境变量
5. 命令行参数

GEMINI.md 同样支持层级：

• 全局：~/.gemini/GEMINI.md
• 项目：<project>/GEMINI.md
• 子目录：<subdir>/GEMINI.md

7. 认证配置

Gemini CLI 需要认证才能使用，支持两种认证方式。

认证方式对比

建议：edu 账号或企业账号优先使用 OAuth 登录，可获得更高的使用配额。

方式 A：OAuth 登录（推荐 edu/企业账号）

首次启动时会自动跳转浏览器认证：

gemini
# 浏览器会打开 Google 登录页面
# 登录后授权即可，之后会自动保存凭证

认证信息保存在 ~/.gemini/ 目录下，后续启动无需重复认证。

方式 B：API Key（推荐个人账号）

获取 API Key

1. 访问 Google AI Studio
2. 登录 Google 账号
3. 点击 "Create API Key" 创建密钥
4. 复制生成的密钥

配置 API Key

# 将密钥写入 ~/.gemini/.env（推荐）
echo 'GEMINI_API_KEY="你的API密钥"' >> ~/.gemini/.env

或者添加到 shell 配置文件：

# ~/.zshrc 或 ~/.bashrc
export GEMINI_API_KEY="你的API密钥"

# 重新加载配置
source ~/.zshrc

验证认证

gemini
# 如果不再跳转浏览器认证，说明配置成功

注意：API Key 是敏感信息，请勿提交到代码仓库或分享给他人。

7.3 网络与代理配置（国内用户必看）

如果在使用过程中遇到 gemini-3.1-pro-preview 等大模型连接超时，或 npx 安装/执行 MCP 扩展极度卡顿，这通常是网络原因导致。

本项目提供了一份防污染的代理配置模板 .gemini/.env.example。

使用方法：

1. 复制模板并重命名为 .env：

   cp .gemini/.env.example .gemini/.env
   

2. 修改 .env 文件，填入你本地科学上网客户端（如 Clash Verge）的代理端口：

   HTTP_PROXY=http://127.0.0.1:你的端口
   HTTPS_PROXY=http://127.0.0.1:你的端口
   # 默认已配置 NO_PROXY 排除 localhost 和 .npmmirror.com 以实现直连加速
   NO_PROXY=localhost,127.0.0.1,.npmmirror.com
   

(注：.gemini/.env 已被加入 .gitignore，不会泄露你的个人网络环境)

Part 3: Codex 配置

定位：Codex 采用“极薄全局 AGENTS + 审批 rules + 渐进式 skills”的通用方案。项目内 .codex/ 是权威源，用户级是部署产物。

1. 快速开始

首次使用或更新 .codex/ 后，在项目根目录执行：

• macOS/Linux: ./tools/sync-config.sh
• Windows: tools\sync-config.bat

脚本会把 .codex/ 分发到 Codex 官方支持的用户级入口：

为什么不是直接复制到 ~/.codex/？

因为 ~/.codex/ 同时还是 Codex 的运行态目录，会包含认证、历史、日志和缓存。项目只同步受管配置，不覆盖运行态文件。

1.1 零费力（自动生效）- Global AGENTS + Rules

你需要做什么：同步一次配置，然后正常使用 Codex

这些内容在 Codex 启动后自动生效：

效果示例：

• Codex 会优先先读代码、配置和脚本，再下结论
• 默认使用简体中文回复，代码、命令、日志和报错保持原文
• 遇到危险命令或越权执行时，会进入审批控制
• 只读排查命令会尽量低摩擦放行，例如 docker ps、kubectl get pods、systemctl status nginx
• 可以按任务复杂度切换 codex -p cc-balanced 或 codex -p cc-deep

1.2 低费力（自动触发）- Implicit Skills

你需要做什么：正常描述任务，或直接操作相关语言文件

这些技能允许隐式触发，适合日常编码和环境敏感场景：

效果示例：

• 写 Go、Java、Python 或前端代码时，会自动带上对应语言规范
• 修改脚本或命令片段时，会补充 Bash 风格约束
• 涉及部署、数据库、服务操作时，会优先考虑安全和回滚

1.3 中费力（显式调用）- Workflow Skills

你需要做什么：在 Codex 对话里输入 $skill-name

Codex 的显式 workflow skill 不走 Claude Code 的 /命令 风格。本项目统一按 Codex Skills 的显式调用方式使用，例如：$commit-msg、$optimize perf、$new-feature 用户导出功能。其中 review 和 status 为避免与 Codex 内置能力混淆，保留 cc- 前缀：$cc-review、$cc-status。

注意：$review quick 更可能命中 Codex 内置 review 能力，而不是本仓库定义的 cc-review skill。若你希望使用本项目约定的中文化审查格式和输出结构，请明确使用 $cc-review quick。

如果刚同步完 skills 但没看到新入口，重启 Codex 即可。

高频 skill（日常使用）

中频 skill（按需使用）

低频 skill（特定场景）

2. 常见场景速查

遇到 Bug？
├─ 简单 Bug → $fix 问题描述
└─ 复杂问题排查 → $fix debug 问题描述

代码审查？
├─ 快速看看 → $cc-review quick
├─ 正式审查 → $cc-review
└─ 安全审查 → $cc-review security

新功能？
├─ 完整流程 → $new-feature 功能名
└─ 只要设计 → $design doc 模块名

系统优化？
├─ 全量评估 → $optimize
├─ 仅性能 → $optimize perf
├─ 仅代码质量 → $optimize code
└─ 仅 UX → $optimize ux

配置是否生效？
└─ 查看状态 → $cc-status

3. 渐进式披露设计

Codex 配置按三层拆分：

skills 又分为两类：

• 隐式技能：如 cc-core-defensive、cc-go-dev、cc-frontend-dev，普通编码场景可自动命中
• 显式 workflow skills：目录仍保留 cc-* 前缀，但显式调用名尽量使用短名，如 fix、design、requirement、size-check、commit-msg、optimize、new-feature、project-init；review 和 status 暂保留 cc-* 以避免与 Codex 内置命令混淆

新增的显式 workflow skills 主要覆盖：

说明：Codex 相关脚手架模板不再集中放在根 .codex/templates/；project-init 需要的 AGENTS.md、Docker、compose、restart 等资源跟随 skill 放在 cc-project-init/assets/，这样同步后即可直接使用。

Profile 模式

项目内还维护了 3 个 Codex profile：

使用方式：

codex -p cc-fast-api
codex exec -p cc-balanced "review this change"
codex -p cc-deep

说明：这里的 cc-fast-api 是项目自定义的快 profile，适合 API key 场景；它不是把用户默认配置切到官方 Fast mode credits。这样可以在不动顶层默认配置的前提下，按需切换速度与深度。

4. 目录结构

.codex/
├── global/
│   ├── AGENTS.md
│   └── rules/
│       ├── cc-safe-default.rules
│       └── cc-dangerous-ops.rules
├── profiles/
│   ├── cc-fast-api.toml
│   ├── cc-balanced.toml
│   └── cc-deep.toml
├── skills/
│   ├── cc-core-defensive/
│   ├── cc-bash-style/
│   ├── cc-ops-safety/
│   ├── cc-go-dev/
│   ├── cc-java-dev/
│   ├── cc-frontend-dev/
│   ├── cc-python-dev/
│   ├── cc-fix/
│   ├── cc-review/
│   ├── cc-design/
│   ├── cc-requirement/
│   ├── cc-size-check/
│   ├── cc-commit-msg/
│   ├── cc-optimize/
│   ├── cc-status/
│   ├── cc-new-feature/
│   └── cc-project-init/
├── templates/
├── tasks/
└── manifests/
    └── sync-map.md

关键原则

• .codex/ 是项目级权威源
• ~/.codex/ 和 ~/.agents/skills/ 是部署产物
• ~/.codex/config.toml 只增量合并本项目的具名 profiles，不覆盖用户当前默认值
• AGENTS.md 必须薄，语言与流程细节交给 skills
• 不要把“世界观设定”“亲密关系口吻”“玩笑切换词”这类长篇人格 prompt 塞进 .codex/global/AGENTS.md；如确有风格偏好，只保留 1-2 条轻量交互原则，并默认专业输出
• rules 应优先区分“检查类”与“修改类”命令：只读排查尽量放行，变更动作保持确认
• rules 只负责审批和危险动作控制，不承载编码规范

Part 4: Cursor 配置

定位：Cursor 采用“项目内 rules + skills 按需语义匹配 + 命令式技能兼容同步”的方案。项目内 .cursor/rules/ 是主路径；用户级主要复用 ~/.cursor/skills/ 和 ~/.cursor/templates/。

1. 快速开始

首次使用或更新 .cursor/ 后，在项目根目录执行：

• macOS/Linux: ./tools/sync-config.sh
• Windows: tools\sync-config.bat

脚本会把 .cursor/ 中适合跨项目复用的内容分发到 Cursor 的用户级目录：

另外，脚本仍会把 .cursor/rules/*.mdc 兼容性同步到 ~/.cursor/rules/，但项目内 .cursor/rules/ 仍是主路径；跨项目个人偏好优先放 Cursor Settings 的 User Rules。

1.1 零费力（自动生效）- Rules

你需要做什么：在项目内保留 .cursor/rules/，同步一次 skills/templates，然后正常使用 Cursor

这些规则放在当前项目 .cursor/rules/ 中时会自动生效：

Cursor 规则类型说明：

1.2 低费力（自动触发）- Skills

你需要做什么：正常写代码

Cursor Agent 会根据技能的 description 语义匹配，自动加载对应技能：

1.3 Cursor 与其他工具的差异

1.4 主动调用 - Commands

你需要做什么：在 Cursor 对话中输入 /命令名

当前为兼容跨项目复用，命令会同步成 ~/.cursor/skills/{name}/SKILL.md，以 / 前缀触发：

2. 常见场景速查

3. 最佳实践

3.1 规则分层

• Always Apply（defensive）：核心防御规则，每次对话都加载
• Glob 匹配：按文件类型触发，不操作相关文件时不消耗 token
• Skills：更详细的规范，由 Agent 根据语义按需加载
• Commands：显式 /命令 调用，按需触发工作流

3.2 与其他工具共用

本项目的 Cursor 配置与 Claude Code、Gemini CLI、Codex 各自独立。规则内容语义一致，但格式适配各工具的原生机制。

3.3 避免的做法

• ❌ 不要手动修改 ~/.cursor/skills/ 中由本项目同步的文件；~/.cursor/rules/ 若存在，也只应视为兼容性补充（会被同步覆盖，以 manifest 文件 .cc-use-exp-managed 追踪）
• ❌ 不要把其他规则设为 Always Apply（除 defensive 外，其他规则按需加载更省 token）
• ✅ 添加个人规则/技能时，避免与本项目文件同名

4. 目录结构

.cursor/
├── rules/                       # 规则：.mdc 格式
│   ├── defensive.mdc            # 防御性规则（Always Apply）
│   ├── ops-safety.mdc           # 运维安全（Glob 匹配）
│   ├── bash-style.mdc           # Bash 核心规范（Glob 匹配）
│   ├── doc-sync.mdc             # 文档同步（Glob 匹配）
│   ├── date-calc.mdc            # 日期计算（Glob 匹配）
│   └── file-size-limit.mdc      # 文件行数限制（Glob 匹配）
├── skills/                      # 技能：SKILL.md 格式（自动语义匹配）
│   ├── go-dev/
│   ├── java-dev/
│   ├── frontend-dev/
│   ├── python-dev/
│   ├── bash-style/
│   ├── ops-safety/
│   ├── redis-safety/
│   ├── size-check/
│   ├── ruanzhu/
│   └── ui-ux-pro-max/
├── commands/                    # 命令：单 .md 文件（/命令 触发）
│   ├── fix.md                   # /fix
│   ├── review.md                # /review
│   ├── commit-msg.md            # /commit-msg
│   ├── new-feature.md           # /new-feature
│   ├── design.md                # /design
│   ├── requirement.md           # /requirement
│   ├── optimize.md              # /optimize
│   ├── style-extract.md         # /style-extract
│   ├── project-init.md          # /project-init
│   ├── project-scan.md          # /project-scan
│   ├── ruanzhu.md               # /ruanzhu
│   └── status.md                # /status
└── templates/                   # 模板文件
    └── ruanzhu/                 # 软著生成脚本

部署映射

参考资料

Claude Code

• Claude Code 官方文档

Gemini CLI

• Gemini CLI 官方文档
• Gemini CLI GitHub
• Gemini CLI 认证指南
• Vue 3 官方文档
• Element Plus 文档

Codex

• OpenAI Codex 文档
• Codex 配置基础
• Codex Skills
• Codex AGENTS.md 指南
• Codex Rules

Cursor

• Cursor 官方文档
• Cursor Rules 配置
• Cursor Agent Skills

社区与支持

GitHub

• Issues - 报告问题
• Pull Requests - 贡献代码
• CONTRIBUTING.md - 贡献流程与授权条款
• CLA.md - 单独签署的贡献授权协议模板
• TRADEMARK.md - 项目名称、Logo 与品牌使用规则
• docs/licensing/historical-rights-checklist.md - 历史贡献清权清单

联系作者

许可声明

本项目采用 PolyForm Noncommercial 1.0.0 发布；公开许可证仅覆盖非商业用途。任何商业使用、企业内部生产使用、面向客户交付或托管服务，均应事先获得维护者的单独商业授权。

这是一份 source-available 非商用许可证，不属于 OSI 定义下的开源许可证。

商业授权咨询：[email protected]

详见 LICENSE

项目附带的 NOTICE 用于保留版权、来源和商业授权联系信息。

项目名称、Logo、封面图和其他品牌元素不随源码许可自动授权，详见 TRADEMARK.md。

许可 FAQ

说明：这里的 FAQ 是项目维护者对当前许可策略的使用指引，不替代正式法律意见。

本项目当前通过 CONTRIBUTING.md 约定默认贡献条款，并提供 CLA.md 作为可单独签署的正式授权模板。对非琐碎外部贡献，维护者可在合并前要求先签署 CLA。

Star History

Contributors