前端 AI Agent Context Engineering 方法论
适用工具：Claude Code、Codex、Cursor 等现代 AI Coding Agent
核心理念：从"教 AI 写单段代码"升级为"多层次上下文工程"
核心机制：两种视角看提示词层级
视角一：运行时视角（AI 底层机制）
从 AI 的实际运行来看，提示词只有两层：
┌─────────────────────────────────┐
│ System Prompt（系统提示词） │ ← 会话启动时注入，整个会话不变
│ 全局设定 + 项目规范 + 工具定义 │
├─────────────────────────────────┤
│ User Message（会话提示词） │ ← 每轮对话动态拼接
│ 用户输入 + @文件上下文 + 历史消息 │
└─────────────────────────────────┘
- 系统提示词：AI 启动时一次性注入，定义了"你是谁、你能做什么、禁止做什么"。Claude Code 会将
settings.json中的全局配置 + 项目根目录的CLAUDE.md拼接后注入。 - 会话提示词：每一轮对话中用户说的内容、拖入的文件、前几轮的对话历史。它是动态的、每轮都在变。
一句话：运行时就是两层——系统层定义边界，会话层驱动行为。
视角二：维护视角（工程师配置管理）
但对于前端工程师的日常维护，更实用的分法是 三层：
| 层级 | 作用域 | 存放位置 | 是否提交 Git | 谁维护 |
|---|---|---|---|---|
| 全局层 | 你所有项目 | ~/.claude/settings.json |
❌ 不提交 | 你自己 |
| 项目层 | 当前项目 | 项目根目录 CLAUDE.md |
✅ 提交 | 你和团队 |
| 任务层 | 单次对话 | 对话输入框 | ❌ | 你自己 |
为什么要拆开？ 全局层和项目层虽然运行时都进了 System Prompt，但它们的维护边界完全不同：
- 团队换包管理器从 npm 到 pnpm？→ 改
CLAUDE.md，不动你的全局配置 - 你个人想用简体中文回复？→ 改你自己的全局配置，不影响团队其他人
- 某个项目锁定 React 18、另一个项目锁定 React 19？→ 各自的
CLAUDE.md各写各的
冲突解决策略：项目层 > 全局层。当你的全局偏好与项目规范冲突时，Agent 优先遵循项目规范。
视角三：两种视角的统一
维护视角（三层） 运行时视角（两层）
───────────────── ──────────────────
┌──────────┐ ┌──────────────┐
│ 全局层 │───┐ │ │
└──────────┘ ├─拼接──→ │ System │
┌──────────┐ │ │ Prompt │
│ 项目层 │───┘ │ │
└──────────┘ ├──────────────┤
┌──────────┐ │ User │
│ 任务层 │────对应──→ │ Message │
└──────────┘ └──────────────┘
结论：运行时两层（系统 vs 会话），维护时三层（全局 vs 项目 vs 任务）。前者回答"AI 怎么理解"，后者回答"我该把这段配置写在哪里"。
各工具配置文件路径速查
Claude Code:
全局：~/.claude/settings.json（或通过 /config 命令配置）
项目：.claude/settings.json + 项目根目录 CLAUDE.md
Codex:
项目：AGENTS.md 或 agents/ 目录下分文件
Cursor:
全局：Cursor Settings > Rules for AI
项目：.cursorrules 或 .cursor/rules/
一、 全局提示词 — 个人铁律
配置位置：Claude Code 中通过
/config命令或在~/.claude/settings.json中写入。
你是一个极度严谨、高效的资深前端架构师智能体。在与我交互和操作文件时，必须严格遵守以下全局法则：
1. 交互与表达规范：
- 拒绝废话，不要长篇大论地解释基础语法，直接展示核心代码变更。
- 所有代码注释、commit message、文档和回复均使用简体中文。
- 在修改代码前，如果影响范围较大，必须先简述计划并等待我确认。
2. 终端命令与工具规范：
- 本地包管理器默认为 pnpm，除非项目中存在 package-lock.json 或 yarn.lock。
- 严禁擅自升级、降级或安装第三方依赖。如需安装，必须先询问我。
- 代码修改完成后，必须主动运行项目本地的 lint 或 type-check 命令验证正确性。
3. 安全与代码底线：
- 绝对禁止读取、修改、或通过任何形式暴露 .env、.env.local 等敏感密钥文件。
- 生成的代码严禁包含任何硬编码的 API 密钥、密码或 Token。
- 严禁删除现有的错误日志（console.error / debugger）或为了省事用 any 抹平 TypeScript 类型。
二、 Vue 3 项目层规范 — CLAUDE.md 模板
适用场景：Vue 3 + Vite + TypeScript + Pinia 技术栈。
使用方式：将以下内容保存为项目根目录的CLAUDE.md。
# Vue 3 项目工程规范
## 1. 核心技术栈
- 框架: Vue 3（Composition API）
- 构建工具: Vite
- 语言: TypeScript（严格模式，strict: true）
- 状态管理: Pinia（Setup Store 写法，禁止 Options Store）
- 包管理器: pnpm
- 样式方案: Tailwind CSS / UnoCSS（按项目实际选型填写）
## 2. 构建与脚本命令
| 命令 | 用途 |
|------|------|
| `pnpm install` | 安装依赖 |
| `pnpm dev` | 启动开发服务器 |
| `pnpm build` | 生产构建 |
| `pnpm lint` | ESLint 代码检查 |
| `pnpm type-check` | TypeScript 类型检查 |
## 3. 代码编写严格规范
### 3.1 组件书写
- 必须使用 `<script setup lang="ts">` 语法糖。
- 严格禁止使用 Options API（`data`、`methods`、`computed` 选项式写法）。
- 组件文件名使用 PascalCase（如 `UserProfile.vue`）。
### 3.2 响应式与类型
- 优先使用 `ref()` 声明所有响应式数据。
- 仅在高度聚合的表单对象（>5 个关联字段，且不涉及解构场景）时使用 `reactive()`。
- 必须为 `ref` 显式标注泛型类型：`ref<Type>(initialValue)`。
- 严禁使用 `any` 类型，不确定类型时使用 `unknown` + 类型守卫。
### 3.3 组件通信
- Props 必须显式声明：`defineProps<{ ... }>()`。
- Emits 必须显式声明：`defineEmits<{ ... }>()`。
- 严禁在子组件中直接修改 props 传入的值，必须通过 emit 通知父组件修改。
- 跨层级通信优先使用 Pinia Store，避免 prop drilling 超过 3 层。
### 3.4 Composables 命名与组织
- Composable 函数必须以 `use` 开头（如 `useAuth`、`useDebounce`）。
- Composable 文件放在 `src/composables/` 目录下，文件名与函数名一致。
- 每个 Composable 必须返回明确的类型接口，不依赖类型推断。
### 3.5 性能与最佳实践
- 复杂计算必须使用 `computed()`，不得在模板中写复杂表达式。
- `v-for` 必须绑定唯一 `:key`，且禁止与 `v-if` 写在同一元素上（先用 computed 过滤数据）。
- 大列表（>100 项）使用虚拟滚动或分页。
- 路由懒加载：`() => import('./views/XXX.vue')`。
## 4. 任务完成标准
- 每次新增或修改组件后，必须运行 `pnpm type-check` 确保零报错。
- 涉及状态管理变更时必须运行 `pnpm lint`。
- 新组件必须有对应的 Props/Emits 类型导出，供父组件使用。
## 5. Agent 自我更新规则
- 当项目中新增核心依赖、变更状态管理方案、或调整构建工具链时，Agent 必须在完成代码变更后同步更新本文件的"核心技术栈"部分。
- 当发现本文件中的规则与当前代码实践明显不一致时，必须向开发者确认，不得擅自修改 CLAUDE.md。
Vue 3 高频任务层 Prompt 示例
在 src/components/ 下新建 DataChart.vue：
1. 使用 <script setup lang="ts"> 语法，引入 ECharts。
2. onMounted 中初始化图表，onUnmounted 中调用 dispose() 安全销毁实例防止内存泄漏。
3. 使用 watch 深度监听 props.chartData 的变化，动态调用 setOption 更新图表。
4. Props 类型：chartData: SeriesData[]，chartOptions?: EChartsOption，需导出供父组件使用。
三、 React 项目层规范 — CLAUDE.md 模板
适用场景：React 19 + Next.js 15(App Router) 或 Vite + React Router + TypeScript。
使用方式：将以下内容保存为项目根目录的CLAUDE.md。
# React 项目工程规范
## 1. 核心技术栈
- 框架: React 19
- 元框架: Next.js 15（App Router）或 Vite + React Router v7（按实际选型填写）
- 语言: TypeScript（strict: true）
- 包管理器: pnpm
- 状态管理: 小型项目使用 Context + useReducer；中大型项目使用 Zustand
- 数据获取: TanStack Query v5（服务端状态） + fetch / ky（客户端请求）
- 数据校验: Zod（运行时类型校验）
- 样式方案: Tailwind CSS / CSS Modules（按项目实际选型填写）
## 2. 构建与脚本命令
| 命令 | 用途 |
|------|------|
| `pnpm install` | 安装依赖 |
| `pnpm dev` | 启动开发服务器 |
| `pnpm build` | 生产构建 |
| `pnpm lint` | ESLint 代码检查 |
| `pnpm type-check` | TypeScript 类型检查 |
## 3. 代码编写严格规范
### 3.1 组件定义
- 必须使用函数式组件（FC），搭配 TypeScript 显式 Props 类型。
- 绝对禁止使用 Class 组件。
- 组件文件名使用 PascalCase（如 `UserProfile.tsx`）。
- 每个文件只导出一个组件，辅助函数放在单独文件中或组件文件底部。
### 3.2 RSC 与 Client 边界（Next.js 项目）
- 默认采用 Server Components（RSC）。
- 仅在需要以下能力时，在文件首行添加 `"use client"` 指令：
- DOM 事件处理（onClick、onChange 等）
- React Hooks（useState、useEffect 等）
- 浏览器 API（localStorage、window、navigator 等）
- 第三方仅客户端库（如 ECharts、D3 等）
- 尽可能将交互逻辑下沉到叶子组件，保持父级为 Server Component。
### 3.3 Hooks 规范
- `useEffect` 必须补齐完整的依赖项数组，禁止使用 `// eslint-disable-next-line` 绕过检查。
- 自定义 Hook 必须以 `use` 开头，放在 `src/hooks/` 目录下。
- 仅在经过性能分析确认存在瓶颈时，才使用 `useMemo` / `useCallback`。默认不使用。
### 3.4 类型系统
- 严禁使用 `any` 类型。不确定时使用 `unknown` + 类型守卫。
- Props 类型必须命名导出：`export type UserProfileProps = { ... }`。
- API 响应数据必须使用 Zod Schema 校验，不信任任何服务端返回的形状。
### 3.5 状态管理选择决策树
组件内部状态 → useState
父子间传递（1-2层） → Props drilling（直接传递）
跨组件共享（3+层） → Context + useReducer（轻量）/ Zustand（复杂）
服务端数据缓存 → TanStack Query
URL 状态 → Next.js searchParams / useSearchParams
表单状态 → React Hook Form + Zod
### 3.6 性能与最佳实践
- 列表渲染必须绑定唯一 `key`，禁止使用数组 index 作为 key（除非列表是静态的、不会重新排序或增删）。
- 图片使用 Next.js `<Image>` 组件（Next.js 项目）或原生懒加载 `loading="lazy"`。
- 动态导入大组件：`dynamic(() => import('./HeavyComponent'))`。
- 服务端数据变更后必须调用 `revalidatePath` 或 `revalidateTag` 刷新缓存。
## 4. 任务完成标准
- 修改或新增代码后，必须运行 `pnpm lint` 确保零告警。
- 所有异步数据交互必须通过 Zod Schema 校验。
- 新组件必须有对应的 Props 类型导出。
## 5. Agent 自我更新规则
- 当项目中新增核心依赖、变更状态管理方案、或调整构建工具链时，Agent 必须在完成代码变更后同步更新本文件的"核心技术栈"部分。
- 当发现本文件中的规则与当前代码实践明显不一致时，必须向开发者确认，不得擅自修改 CLAUDE.md。
React 高频任务层 Prompt 示例
在 src/hooks/ 下编写 useDebounceEffect.ts：
1. 接收参数：effect 回调、delay 延迟毫秒数、deps 依赖数组。
2. 内部使用 useEffect + setTimeout 实现防抖，依赖更新或组件卸载时清除定时器。
3. 返回一个 cancel 函数供外部手动取消。
4. 导出完整的 TypeScript 类型签名。
四、 前端工程师使用 Agent 的避坑指南
1. 多层提示词冲突时，项目层优先
Agent 运行时会将全局提示词和项目层 CLAUDE.md 拼接。如果全局写了 pnpm，但当前项目 CLAUDE.md 写了 npm run dev，Agent 会优先遵循项目层规范。这正是分层设计的价值所在。
2. 给 AI 看代码，而不是让 AI 猜代码
在让 Agent 修改某功能前，先用 @file 或直接拖入相关文件作为上下文。典型的反模式：
❌ "帮我改一下登录逻辑。"
Agent 不知道你的登录逻辑在哪、怎么写的、用了什么库，只能靠猜测。
✅ "帮我改一下
src/features/auth/LoginForm.tsx里的登录逻辑，这里还有相关的useAuth.tshook 和auth.schema.ts。"
3. 防范 AI 幻觉，锁定技术大版本
AI 很容易混淆新旧语法差异：
| 易混淆场景 | 应对方案 |
|---|---|
| React 18 vs 19 | 在 CLAUDE.md 中明确写死 React 19 |
| Vue 2 vs Vue 3 | 写死 Composition API only，禁止 Options API |
| Next.js Pages vs App Router | 写死 App Router，禁止 getServerSideProps 等旧 API |
| Tailwind v3 vs v4 | 写死大版本号，防止引入新/旧类名 |
| ECharts 4 vs 5 | 写死 import * as echarts 方式 |
4. 小步快跑，原子化迭代
不要让 Agent 一次性重构过于复杂的链路。正确的开发循环：
明确计划 → 编写代码 → 自动运行 Lint/Type-check → 确认无误 → 下一原子步骤
每一步的改动应该可以被一句话描述清楚。如果一个改动需要用"和"连接多个动词，就应该拆分为多个原子步骤。
5. CLAUDE.md 本身也需要维护
这是一个常被忽略的点。CLAUDE.md 和代码一样会腐烂：
- 当你给项目加了 Zustand，就应该更新
CLAUDE.md里的状态管理方案 - 当你从 Vite 迁移到 Turbopack，就应该更新构建工具
- 可以要求 Agent 在完成涉及基础设施变更的任务后，主动提醒你更新
CLAUDE.md
6. 自然语言措辞至关重要
在 CLAUDE.md 中写规则时，措辞直接影响 AI 的遵守程度：
| ❌ 弱约束（AI 常忽略） | ✅ 强约束（AI 严格遵循） |
|---|---|
尽量使用 ref() |
必须使用 ref()，禁止… |
| 建议补齐依赖数组 | 必须补齐完整依赖项数组 |
最好避免使用 any |
严禁使用 any 类型 |
| 优先使用 pnpm | 默认使用 pnpm，除非项目存在… |
五、 快速检查清单
在项目启动时，确认以下各项已就绪：
浙公网安备 33010602011771号