跨端工程实践：AI双工具（Claude Code / Cursor）忽略规则与行为规约

在 AI 协同编程的工业级实践中，独立开发者与团队经常面临两大痛点：一是忽略边界不清晰导致 Token 账单失控；二是缺乏环境与代码质量约束，导致 AI 写出无法通过前端校验（Lint）或破坏后端架构的面条代码。

本文将提供一套彻底抽离具体业务、支持前后端分离技术栈的通用 Ignore 过滤模板，并针对 Claude Code 与 Cursor 的不同运行特性，将前端与后端的规约与命令进行彻底的拆分布局，打造出一套既互通、又各司其职的全局契约。

☕ 篇章一：后端专属（Java/Maven）AI 协同工程化配置底座

本篇专门针对 Java / Maven / Gradle 技术栈的后端开发仓库，提供一键复制的通用 AI 忽略规则与双工具规约模板。

🛡️ 1. 后端通用忽略配置：.claudeignore / .cursorignore

请在后端项目根目录下，分别创建 .claudeignore 和 .cursorignore 文件，并写入以下纯净配置：

text

# ==============================================================================
# Java 后端通用 AI 忽略配置文件 (适用于 .claudeignore 和 .cursorignore)
# 核心目的：切断编译垃圾与大数据文件，严控 Token 成本，提升 AI 响应速度
# ==============================================================================

# ------------------------------------------------------------------------------
# 1. 核心构建产物与编译输出（Token 吞噬重灾区）
# ------------------------------------------------------------------------------
**/target/
**/build/
**/out/
**/*.class
**/*.jar
**/*.war
**/*.ear

# ------------------------------------------------------------------------------
# 2. 依赖管理包
# ------------------------------------------------------------------------------
**/.gradle/
**/.mvn/
**/vendor/

# ------------------------------------------------------------------------------
# 3. 日志、运行时数据与本地流水
# ------------------------------------------------------------------------------
**/logs/
**/*.log
**/data/
**/db/
**/*.db
**/*.sqlite
**/*.kryo
**/*.bin

# ------------------------------------------------------------------------------
# 4. IDE、编辑器及系统特定配置
# ------------------------------------------------------------------------------
.git/
.idea/
.vscode/
**/*.iml
.DS_Store
Thumbs.db

# ------------------------------------------------------------------------------
# 5. 非代码的大型多媒体与办公文档
# ------------------------------------------------------------------------------
**/docs/
**/*.pdf
**/*.docx
**/*.xlsx

请谨慎使用此类代码。

🤖 2. 后端 Claude Code 全局契约：CLAUDE.md

请在后端项目根目录下创建 CLAUDE.md 文件（适用于终端驱动的 Claude Code 命令行工具）：

markdown

# CLAUDE.md - 后端开发指南与行为准则

## 1. 核心流程：实质性代码修改前置确认机制
- **触发条件**：在涉及多文件修改、业务行为变更、配置语义调整、或非平凡重构（Non-trivial Refactoring）等**实质性**代码改动前。
- **前置动作**：AI 必须**先给出简短的修改计划**，明确列出：
  1. 准备修改的文件路径与清单。
  2. 期望达到的核心业务目的。
  3. **明确界定并写出“不打算触碰/改动”的边界与范围**。
- **执行原则**：计划给出后，**在单次交互中以概要形式告知用户即可，若用户未提出异议或任务本身具有连续性，AI 可在同一轮对话中连贯执行，避免因死板等待中断自动化流水线**。
- **唯一例外**：若用户明确指出“不要擅自改动，列出计划等我确认”，或者改动范围将超过整个模块的架构边界时，则必须绝对静默等待。

## 2. BACKEND：Java 后端开发规范
- **设计思想**：坚持**面向接口编程**。代码必须符合“高内聚、低耦合”的编程思想，严格遵循**开闭原则（OCP）**，符合**单一职责原则**，确保系统易维护、易拓展。
- **设计模式**：拒绝平铺直叙的代码。在面对复杂或多分支的业务场景时，**必须合理运用符合当下语境的设计模式**（如策略、工厂、观察者、单例等）进行优雅解耦。
- **规模限制**：严格控制文件体积。**单个 Java 类文件的总行数尽量控制在 500 行以内**。当代码趋向臃肿时，AI 必须主动提出类拆分或逻辑提取方案。
- **命名规范**：严格遵循标准小驼峰命名（lowerCamelCase），全局常量大写加下划线。
- **单元测试特例**：为保证测试报告和失败日志的可读性，测试方法名**允许并推荐使用下划线分段法**，格式统一为：`被测方法_测试场景_预期结果`（例如：`methodName_scenario_expectedBehavior`）。严禁在测试类中编写逻辑复杂的外部依赖夹具，优先使用断言库原生机制。

## 3. 常用开发命令集 (环境兼容: Git Bash)
```bash
# 清理并重新编译项目
mvn clean compile

# 打包项目（包含运行测试）
mvn clean package

# 打包项目（跳过测试）
mvn clean package -DskipTests

# 运行全部单元测试
mvn test

# 运行指定的单个测试类
mvn test -Dtest=YourTestClassName
```

请谨慎使用此类代码。

🎯 3. 后端 Cursor 动态规则：.cursor/rules/global-rules.mdc

请在后端项目根目录下创建 .cursor/rules/global-rules.mdc 文件（适用于 Cursor 编辑器环境）：

markdown

---
description: 后端架构设计、编码质量控制与实质性改动前置确认规范
globs: **/*.java, **/pom.xml, **/*.gradle
alwaysApply: true
---

# 后端开发规约 (Java 精简版)

## 1. 实质性改动前置确认机制
- **触发条件**：在涉及多文件修改、业务行为变更、配置语义调整、或非平凡重构前。
- **前置动作**：AI 必须先给出简短计划（明确包含改动路径、业务目的、以及不打算动的范围）。
- **执行原则**：计划给出时，在单次交互中以概要形式告知用户即可。若用户未提出异议或任务本身具有连续性，AI 可在同一轮对话中连贯执行，避免中断自动化流水线。
- **唯一例外**：若用户明确指出“等我确认后再改”，或者改动范围将超过整个模块的架构边界时，必须绝对静默等待。

## 2. Java 后端质量防御
- **设计思想**：坚持**面向接口编程**。代码必须符合“高内聚、低耦合”的编程思想，严格遵循**开闭原则（OCP）**，符合**单一职责原则**，确保系统易维护、易拓展。
- **设计模式**：拒绝平铺直叙的代码。在面对复杂或多分支的业务场景时，**必须合理运用符合当下语境的设计模式**（如策略、工厂、观察者、单例等）进行优雅解耦。
- **规模限制**：严格控制文件体积。**单个 Java 类文件的总行数尽量控制在 500 行以内**。当代码趋向臃肿时，AI 必须主动提出类拆分或逻辑提取方案。
- **命名规范**：严格遵循标准小驼峰命名（lowerCamelCase），全局常量大写加下划线。
- **单元测试特例**：为保证测试报告和失败日志的可读性，测试方法名**允许并推荐使用下划线分段法**，格式统一为：`被测方法_测试场景_预期结果`（例如：`methodName_scenario_expectedBehavior`）。严禁在测试类中编写逻辑复杂的外部依赖夹具，优先使用断言库原生机制。

请谨慎使用此类代码。

🎨 篇章二：前端专属（Vue/React/Node）AI 协同工程化配置底座

本篇专门针对 Vue / React / Node.js 技术栈的前端开发仓库，提供一键复制的通用 AI 忽略规则与双工具规约模板。

🛡️ 1. 前端通用忽略配置：.claudeignore / .cursorignore

请在前端项目根目录下，分别创建 .claudeignore 和 .cursorignore 文件，并写入以下纯净配置：

text

# ==============================================================================
# 前端通用 AI 忽略配置文件 (适用于 .claudeignore 和 .cursorignore)
# 核心目的：切断巨型依赖与打包缓存，严控 Token 成本，提升 AI 响应速度
# ==============================================================================

# ------------------------------------------------------------------------------
# 1. 核心构建产物与编译输出（Token 吞噬重灾区）
# ------------------------------------------------------------------------------
**/dist/
**/out/
**/.next/
**/.nuxt/
**/.pnpm-store/

# ------------------------------------------------------------------------------
# 2. 依赖管理包（绝对禁止 AI 检索的三方库）
# ------------------------------------------------------------------------------
**/node_modules/
**/bower_components/

# ------------------------------------------------------------------------------
# 3. 日志与本地缓存
# ------------------------------------------------------------------------------
**/logs/
**/*.log
**/.eslintcache
**/.stylelintcache

# ------------------------------------------------------------------------------
# 4. IDE、编辑器及系统特定配置
# ------------------------------------------------------------------------------
.git/
.idea/
.vscode/
.DS_Store
Thumbs.db

# ------------------------------------------------------------------------------
# 5. 非代码的大型多媒体与办公文档
# ------------------------------------------------------------------------------
**/docs/
**/*.pdf
**/*.png
**/*.jpg
**/*.jpeg
**/*.gif
**/*.svg

请谨慎使用此类代码。

🤖 2. 前端 Claude Code 全局契约：CLAUDE.md

请在前端项目根目录下创建 CLAUDE.md 文件（适用于终端驱动的 Claude Code 命令行工具）：

markdown

# CLAUDE.md - 前端开发指南与行为准则

## 1. 核心流程：实质性代码修改前置确认机制
- **触发条件**：在涉及多文件修改、业务行为变更、配置语义调整、或非平凡重构（Non-trivial Refactoring）等**实质性**代码改动前。
- **前置动作**：AI 必须**先给出简短的修改计划**，明确列出：
  1. 准备修改的文件路径与清单。
  2. 期望达到的核心业务目的。
  3. **明确界定并写出“不打算触碰/改动”的边界与范围**。
- **执行原则**：计划给出后，**在单次交互中以概要形式告知用户即可，若用户未提出异议或任务本身具有连续性，AI 可在同一轮对话中连贯执行，避免因死板等待中断自动化流水线**。
- **唯一例外**：若用户明确指出“不要擅自改动，列出计划等我确认”，或者改动范围将超过整个模块的架构边界时，则必须绝对静默等待。

## 2. FRONTEND：前端开发规范与工程约束
- **设计思想**：坚持**面向接口编程**。代码必须符合“高内聚、低耦合”的编程思想，严格遵循**开闭原则（OCP）**，符合**单一职责原则**，确保系统易维护、易拓展。
- **设计模式**：拒绝平铺直叙的代码。在面对复杂或多分支的业务场景时，**必须合理运用符合当下语境的设计模式**（如策略、工厂、观察者、单例等）进行优雅解耦。
- **单一职责**：所有前端页面、路由组件及公共 UI 组件必须做到**职责单一**。杜绝在单个文件中堆砌不相关的横切业务逻辑。
- **规模限制**：严格控制文件体积。**单个 Vue/React 组件或页面的总行数尽量控制在 500 行以内**。当组件趋向臃肿时，AI 必须主动提出组件拆分或架构抽离方案。
- **结构化约束**：严禁在组件内部直接编排巨型的硬编码表单项、配置文件或魔术字符串。必须将复杂的工具函数提取到独立的 `utils` 目录，将表单/列表配置项抽离到单独的 `constants` 或配置文件中。
- **质量控制**：必须严格遵循项目的 ESLint、Prettier 以及官方风格指南规范（如 Vue Style Guide）。AI 生成或修改前端代码后，**必须主动检查或运行代码校验工具**，确保不出现任何未定义变量、缩进错误或类型悬空问题。

## 3. 常用开发命令集 (环境兼容: Git Bash)
```bash
# 安装项目依赖 (以 pnpm 为例，可根据项目实际替换为 npm/yarn)
pnpm install

# 启动本地开发服务器
pnpm dev

# 执行前端代码 Lint 检查与格式化自动修正
pnpm lint

# 生产环境打包构建
pnpm build

# 运行前端单元测试
pnpm test
```

请谨慎使用此类代码。

🎯 3. 前端 Cursor 动态规则：.cursor/rules/global-rules.mdc

请在前端项目根目录下创建 .cursor/rules/global-rules.mdc 文件（适用于 Cursor 编辑器环境）：

markdown

---
description: 前端架构设计、编码质量控制、UI组件防臃肿与实质性改动前置确认规范
globs: **/*.js, **/*.ts, **/*.vue, **/*.jsx, **/*.tsx, **/package.json
alwaysApply: true
---

# 前端开发规约 (前端精简版)

## 1. 实质性改动前置确认机制
- **触发条件**：在涉及多文件修改、业务行为变更、配置语义调整、或非平凡重构前。
- **前置动作**：AI 必须先给出简短计划（明确包含改动路径、业务目的、以及不打算动的范围）。
- **执行原则**：计划给出时，在单次交互中以概要形式告知用户即可。若用户未提出异议或任务本身具有连续性，AI 可在同一轮对话中连贯执行，避免中断自动化流水线。
- **唯一例外**：若用户明确指出“等我确认后再改”，或者改动范围将超过整个模块的架构边界时，必须绝对静默等待。

## 2. 前端质量与架构防御
- **设计思想**：坚持**面向接口编程**。代码必须符合“高内聚、低耦合”的编程思想，严格遵循**开闭原则（OCP）**，符合**单一职责原则**，确保系统易维护、易拓展。
- **设计模式**：拒绝平铺直叙的代码。在面对复杂或多分支的业务场景时，**必须合理运用符合当下语境的设计模式**（如策略、工厂、观察者、单例等）进行优雅解耦。
- **单一职责**：每一个页面、每一个 UI 组件都必须职责单一，单个文件的总行数尽量控制在 500 行以内。一旦代码趋向肥胖，必须主动进行组件化抽离。
- **解耦约束**：复杂的业务逻辑、工具函数、超长表单配置项、Echarts 配置项等，必须从 UI 视图组件中主动抽离到独立的 `utils` 或 `constants` 文件夹中。
- **规范校验**：严格遵循项目已有的 ESLint / Prettier 规范。AI 修改前端代码时，杜绝产生未定义变量或格式混乱，确保 Lint 工具畅通无阻。

请谨慎使用此类代码。

🏆 四、 标准初始化工作流

为了将这套通用配置发挥到极致，在任何新旧项目落地时，团队成员应严格遵循以下三步法： 🏃‍♂️

• 第一步：筑牢防线 🧱（人类手动）：拷贝第一板块对应的通用 Ignore 过滤列表（后端或前端），分别在项目根目录下存为 .claudeignore 和 .cursorignore。必须在呼叫 AI 之前完成此步骤，以锁定 Token 边界。

• 第二步：生成底座 🏗️（工具自动）：在终端运行 Claude Code 的 /init，让它在干净的环境里安全识别技术栈基础环境。

• 第三步：注入灵魂 🧬（人类覆盖）：用第二板块对应的 CLAUDE.md 覆盖 Claude Code 自动生成的同名文件；如果是 Cursor 环境，则在 .cursor/rules/ 下创建 global-rules.mdc 并写入第三板块对应的规则内容。

通过这样清晰的前后端分离和工具分工，Claude Code 完美继承了攻坚克难的“命令行自动化”超能力，而 Cursor 则继承了精简、强大的“编辑器内编码质量控制”超能力。在降本增效的同时，真正确保了前后端代码的干净与优雅。 🌟