从提示词工程到上下文工程：构建AI就绪的项目心智模型

1. 从“提示词工程”到“上下文工程”：为什么你的提示词是最小的问题

最近在一个客户项目上，我遇到了一个再熟悉不过的场景。全新的代码库，没有任何AI工具链配置，团队里的一位开发者问我：“你是怎么让AI产出那么好的结果的？”我看了看他的屏幕。他打开了Claude——在浏览器里，没有任何项目上下文，每一个新任务都开一个全新的聊天窗口。

这就是问题所在。不是工具，不是模型，甚至不是提示词本身。缺失的是结构。

经过一年在真实项目中每天使用AI，我确信：区分“AI还不错”和“AI从根本上改变了我的工作方式”的，不是那个完美的提示词。而是你在AI回答第一个问题之前，为它构建的上下文。

我称之为上下文工程。这不是一个时髦的新术语，而是一个实实在在的工作流范式转变。过去一年，我作为自由职业的全栈开发者，穿梭于不同的Vue/Nuxt、TypeScript项目，这套方法让我将AI从一个偶尔有用的“智能助手”，变成了一个真正理解项目、能独立完成复杂任务的“初级开发者伙伴”。很多人把时间花在琢磨“如何问得更好”，而我发现，把时间花在“如何让AI知道得更多”上，回报要高得多。

2. 核心思路拆解：为什么结构比措辞更重要

2.1 提示词的局限性：一次性的、脆弱的沟通

我们通常与AI的交互模式是“一问一答”。每次提问，我们都在试图从头构建一个临时的、不稳定的心智模型。你需要告诉它：“我们用的是Tailwind，不是内联样式；我们的设计系统主色是#3B82F6；所有文本都必须走i18n翻译文件……”下一次提问，哪怕只是十分钟后，你又得重复一遍，或者指望AI能“记住”之前的对话。这种模式有几个致命缺陷：

1. 不一致性：你不可能每次都用完全相同的措辞描述规则。今天说“别用any类型”，明天说“避免使用TypeScript的any”，AI可能会产生微妙的解读差异。
2. 信息冗余与疲劳：反复解释基础规则消耗大量认知资源和聊天窗口的宝贵token。
3. 缺乏系统性：临时口述的规则是零散的，容易遗漏关键约束，比如数据模型的关系、特定的业务逻辑边界（“什么我们坚决不做”）。

2.2 上下文工程的核心理念：构建可复用、可演进的项目心智

上下文工程的核心思想，是将AI视为项目的一个新成员。你不会指望一个新同事仅凭你口头交代的几句话就能完美工作，你会给他看项目文档、代码规范、设计稿和产品需求文档。对AI也应如此。

我的方法是将所有稳定的、结构化的项目知识，沉淀到一系列Markdown文件中。这些文件构成了项目的“官方上下文”，任何AI会话都可以基于此展开。这带来了几个根本性的优势：

• 一致性保证：规则被白纸黑字地定义，AI每次读取的都是同一份“法律条文”，产出自然一致。
• 一次编写，永久受益：初期投入时间创建这些文件，后续每个任务都无需重复解释，节省的时间呈指数级增长。
• 知识可演进：当项目规则更新（比如设计系统色板变更），你只需更新对应的上下文文件，所有未来的AI会话都会自动遵循新规。
• 降低心智负担：开发者无需在每次交互时都扮演“项目百科全书”，可以更专注于描述具体的、一次性的任务逻辑。

3. 核心文件系统：构建你的项目“AI手册”

这套系统的基石是几个核心的Markdown文件。它们各有分工，共同构成了项目的完整上下文。

3.1CLAUDE.md：项目的“技术宪法”

当我用Claude Code（或其他具备文件读取能力的AI编码工具）开始一个新项目时，第一件事就是创建CLAUDE.md。这不是一个可选项，而是项目初始化的一部分，优先级高于写第一个组件。

这个文件的目标是：包含一个新开发者入职第一天需要知道的所有技术细节。它不是代码注释的堆砌，而是高层次的、决策性的描述。

一个典型的CLAUDE.md结构如下：

# 项目技术上下文：{项目名称} ## 技术栈与版本 - **前端框架**: Vue 3.4+ with Composition API, `<script setup>`语法 - **构建工具**: Vite 5.0+, 仅使用ESBuild进行生产构建 - **样式方案**: Tailwind CSS 3.4+， 使用`@apply`提取组件类，禁止行内`style` - **类型系统**: TypeScript 5.3+， 严格模式(`strict: true`)，禁止使用`any`类型 - **状态管理**: Pinia 2.1+， 遵循“一个Store对应一个业务域”原则 - **代码规范**: ESLint (`@vue/eslint-config-typescript`), Prettier， 提交前必须通过 - **包管理器**: pnpm 8.0+， 使用workspace管理monorepo ## 项目结构与设计决策

src/ ├── components/ # 通用组件，按功能而非页面划分 │ ├── ui/ # 纯展示型基础UI组件 (Button, Card, Modal) │ └── business/ # 带业务逻辑的复合组件 ├── composables/ # 组合式函数，以use前缀命名 ├── layouts/ # 布局组件 ├── pages/ # 路由页面组件 ├── stores/ # Pinia Store ├── types/ # 全局TypeScript类型定义 └── utils/ # 纯工具函数，不包含业务逻辑

*为什么这样划分？* 将`ui/`与`business/`分离，确保基础组件零业务依赖，可跨项目复用。`composables/`存放可复用的响应式逻辑。 ## 设计系统（具体数值） - **色彩系统**: - 主色: `#3B82F6` (Blue-500) - 成功: `#10B981` (Green-500) - 警告: `#F59E0B` (Amber-500) - 错误: `#EF4444` (Red-500) - 背景: `#F9FAFB` (Gray-50) - 文字-主要: `#111827` (Gray-900) - **间距尺度**: 基于`0.25rem` (4px) 增量。组件间距通常为`4, 8, 12, 16, 24, 32, 48, 64`。 - **字体与排版**: - 主字体: `Inter` (来自Google Fonts) - 代码字体: `JetBrains Mono` - 基础行高: `1.5` - **重要规则**: 中文与英文、数字间使用一个空格。连接号使用**全角破折号（——）**，禁止使用英文em dash（—）或半角减号（-）。 ## 强制性编码规则 以下规则必须始终遵守，无需在每次提示中重复： 1. **TypeScript**: 始终启用严格模式。为所有函数参数和返回值显式定义类型。禁止`any`，必要时使用`unknown`或更精确的类型。 2. **样式**: 所有样式必须通过Tailwind工具类或`@layer components`中定义的类实现。禁止在Vue单文件组件的`<style>`块中编写全局样式或行内`style`属性。 3. **国际化**: 所有面向用户的文本字符串**不得**硬编码在组件中。必须定义在`src/locales/`下的JSON文件内，并通过`useI18n()`组合式函数引用。 4. **ESLint**: 提交代码前，必须在项目根目录运行`pnpm lint`并通过。禁止使用`/* eslint-disable */`注释，除非附有详细的豁免理由。 5. **组件设计**: 组件遵循单一职责原则。超过200行的组件应考虑拆分为子组件或组合式函数。 6. **错误处理**: 所有异步操作（API调用、文件读取）必须使用`try/catch`包裹，或使用`Promise.catch`处理错误。静默失败是不允许的。 ## 外部资源与配置 - **API基础URL**: `https://api.project.com/v1` - **设计稿链接**: [Figma项目链接] - **部署环境**: - 预览环境: `https://staging.project.com` - 生产环境: `https://app.project.com` - **重要账户**（仅列别名，不包含真实凭证）: - 日志查看: Kibana (内部链接) - 错误监控: Sentry项目 `frontend-{project-name}`

实操心得：CLAUDE.md不是一成不变的。随着项目演进，你需要不断更新它。我习惯在每次引入新的技术决策或遇到因规则不清导致的AI“失误”后，立即更新此文件。把它当作一份活的文档。

3.2PRODUCT_SPEC.md：产品的“灵魂指南”

如果说CLAUDE.md定义了“如何建造”，那么PRODUCT_SPEC.md就定义了“建造什么”以及“为什么这么建”。我第一次创建这个文件，是因为发现：如果我三周没碰一个项目，自己重新上手都需要时间“进入状态”。AI更需要这个“状态”。

这个文件帮助AI理解产品的业务上下文和设计意图，避免它基于纯技术合理性做出违背产品目标的建议。

PRODUCT_SPEC.md内容大纲：

# 产品规格与愿景：{产品名称} ## 核心价值主张 我们为{目标用户群体}解决{核心痛点}。与{竞品X}不同，我们的差异化优势在于{关键差异点}。用户选择我们的首要原因是{首要原因}。 ## 用户画像与核心任务 1. **主要用户：{角色A}** - 目标：快速完成{任务A}，关注效率和准确性。 - 使用场景：每天使用，单次会话5-10分钟。 - 痛点：现有工具流程繁琐，错误率高。 2. **次要用户：{角色B}** - 目标：分析{数据B}，做出决策。 - 使用场景：每周使用，单次会话30分钟以上。 - 痛点：数据分散，缺乏可视化洞察。 ## 现有功能与设计决策 - **功能A：仪表盘** - *做了什么*：聚合关键指标，以卡片形式展示。 - *为什么这么做*：因为主要用户需要“一眼看到”整体状态，而不是深入分析。因此我们牺牲了自定义维度，换取了加载速度和视觉清晰度。 - *技术实现备注*：数据每5分钟缓存一次，以提升性能。AI在建议新图表时，需考虑此缓存策略。 - **功能B：报告导出** - *做了什么*：仅支持PDF导出，格式固定。 - *为什么这么做*：用户反馈表明，95%的导出需求是为了打印或邮件发送附件，PDF是最通用格式。支持Excel会增加30%的开发复杂度，但需求仅占5%。 - *技术实现备注*：使用服务端生成PDF以确保格式一致性。客户端仅触发生成和下载。 ## 我们刻意不构建的功能（及原因） 这是最关键的部分之一。如果你不告诉AI“我们选择不做X”，那么当X在技术上显得合理时，AI很可能会建议甚至实现它。 1. **实时协同编辑**：我们的用户场景是异步、独立工作，实时协同带来的技术复杂度和成本远超其带来的用户价值。 2. **移动端原生应用**：数据分析类任务主要在桌面端完成。我们的响应式Web应用已能满足移动端查看需求，开发独立App的ROI过低。 3. **自定义插件/脚本系统**：目标用户非技术背景比例高，开放系统会增加他们的认知负担和我们的支持成本。高级功能通过API满足。 4. **深色模式**：经用户调研和A/B测试，我们的数据可视化图表在浅色背景下可读性显著更高。因此暂不提供深色主题。 ## 品牌与交互基调 - **语调**：专业、辅助性、避免过于活泼。错误信息应指导用户如何解决，而非仅仅告知失败。 - **动画原则**：仅用于提供状态反馈（如加载、成功）和引导注意力。禁止装饰性动画。 - **空状态设计**：每个列表或数据区域必须有设计过的空状态，提供明确的下一步行动指引（如“创建您的第一个项目”按钮）。

注意事项：在编写“刻意不构建的功能”时，要像对待产品需求一样认真。每一条都应该有经过深思熟虑的理由（用户研究、数据、成本分析）。这能极大地约束AI的“创意发散”，让它始终在正确的产品边界内思考。

3.3 技能文件：将重复工作流封装为“宏”

这是最被低估，但对我效率提升最大的一环。每个项目都有一些固定流程的任务。例如：

• 发布一篇新博客文章后：验证Frontmatter、运行排版检查、生成中英文版本、提交到特定分支。
• 完成一个新功能后：运行完整的测试套件、执行Lint检查、对关键UI变化进行截图、在项目管理工具中更新状态。

过去，我需要在每个相关提示词的末尾加上：“别忘了运行测试和Lint，然后截图更新到工单。”现在，我将这些工作流定义成独立的“技能文件”。

示例：skills/publish-blog-post.md

# 技能：发布博客文章 ## 触发条件 当需要发布一篇新的博客文章时，使用此技能。 ## 前置检查清单 在开始发布流程前，请确保： 1. 文章Markdown文件位于 `content/blog/` 目录下，文件名格式为 `YYYY-MM-DD-slug.md`。 2. 文章包含完整的Frontmatter： ```yaml --- title: "文章标题" date: YYYY-MM-DD description: "文章摘要" category: "分类" tags: ["标签1", "标签2"] --- ``` 3. 文章内容已通过拼写和语法检查（可使用工具如 `vale`）。 ## 发布步骤 请按顺序执行以下操作： 1. **验证Frontmatter**：运行 `pnpm run blog:validate {文件名}`，确保所有必填字段格式正确。 2. **运行排版检查**：执行 `pnpm run blog:typography {文件名}`，自动修正中文排版问题（如空格、引号、破折号）。 3. **生成摘要**：如果Frontmatter中`description`字段为空，请基于文章前150字生成一个简洁的摘要并更新。 4. **创建翻译占位符**：在 `content/blog/i18n/` 下创建对应的 `{slug}.json` 文件，包含 `title` 和 `description` 的英文键值对。 5. **提交更改**：使用Git，提交信息格式为 `“blog: publish post on {文章主题}”`。 6. **触发部署**：将更改推送到 `main` 分支。我们的CI/CD管道会自动构建并部署到预览环境。 7. **通知**：在团队沟通工具的 `#blog` 频道中发布一条消息，包含文章标题、链接和简短介绍。 ## 常见问题处理 - *如果排版检查失败*：根据工具输出的建议手动修正，然后重新运行步骤2。 - *如果Frontmatter验证失败*：根据错误信息修正YAML格式，确保缩进和冒号使用正确。 - *如果Git推送被拒绝*：先执行 `git pull --rebase origin main` 解决可能的冲突，再推送。

在具体的AI任务提示中，我只需要简单提及：“请撰写一篇关于Vue 3响应式原理的博客，并使用publish-blog-post技能。” AI就会自动加载该技能文件，并遵循其中定义的标准流程执行。

实操心得：技能文件极大地减少了“保姆式”提示。AI从需要一步步指挥的“实习生”，变成了知道标准作业程序（SOP）的“熟练工”。创建技能文件的最佳时机，是当你发现自己在不同对话中第三次重复描述同一个多步骤任务时。

3.4 数据模型规约：在写代码前先定义“真理”

这是我用教训换来的经验。我曾让AI实现一个涉及多张数据库表的新功能。结果代码能跑，但数据模型是错的。不是语法错误，而是那种“三个月后肯定会出问题”的设计错误：缺失约束、该用1:N的关系做成了N:M、一个字段语义上应该放在另一张表里。

从此以后，在让AI进行任何数据库相关的工作之前，我会先写一份简单的数据模型规约。用自然语言描述，不需要特定的DSL。

示例：电商订单模型规约

# 数据模型规约：订单系统 ## 表：`users` (用户) - `id`: UUID, 主键，默认使用 `gen_random_uuid()` - `email`: VARCHAR(255), 唯一索引，非空 - `hashed_password`: TEXT, 非空 (存储bcrypt哈希值) - `full_name`: VARCHAR(100) - `created_at`: TIMESTAMPTZ, 非空，默认 `NOW()` - `updated_at`: TIMESTAMPTZ, 非空，默认 `NOW()`，通过触发器更新 ## 表：`products` (产品) - `id`: UUID, 主键 - `sku`: VARCHAR(50), 唯一索引，非空 (库存单位编码) - `name`: VARCHAR(200), 非空 - `description`: TEXT - `price_cents`: INTEGER, 非空 (始终以分为单位存储，避免浮点数精度问题) - `stock_quantity`: INTEGER, 非空，默认 0 - `is_active`: BOOLEAN, 非空，默认 true (软删除标志) ## 表：`orders` (订单) - 核心表 - `id`: UUID, 主键 - `user_id`: UUID, 非空，外键引用 `users(id)` ON DELETE RESTRICT (订单必须属于一个有效用户) - `status`: VARCHAR(20), 非空，检查约束 `status IN ('pending', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded')` - `total_amount_cents`: INTEGER, 非空 (订单总金额，以分为单位) - `shipping_address`: JSONB, 非空 (存储完整的收货地址JSON，避免关联表过度复杂化) - `created_at`: TIMESTAMPTZ, 非空，默认 `NOW()` - `paid_at`: TIMESTAMPTZ (可为空，支付完成时填入) ## 表：`order_items` (订单项) - `id`: UUID, 主键 - `order_id`: UUID, 非空，外键引用 `orders(id)` ON DELETE CASCADE (订单删除则项随之删除) - `product_id`: UUID, 非空，外键引用 `products(id)` ON DELETE RESTRICT (防止引用失效产品) - `quantity`: INTEGER, 非空，检查约束 `quantity > 0` - `unit_price_cents`: INTEGER, 非空 (下单时的单价快照，与产品当前价格解耦) - `subtotal_cents`: INTEGER, 非空 (计算字段：`quantity * unit_price_cents`) ## 关系定义 1. **用户-订单**: 一对多 (`1:N`)。一个用户可以有多个订单，一个订单只属于一个用户。 2. **订单-订单项**: 一对多 (`1:N`)。一个订单包含多个订单项，一个订单项只属于一个订单。 3. **产品-订单项**: 一对多 (`1:N`)。一个产品可以出现在多个订单项中（作为被购买的商品），一个订单项引用一个特定的产品。 ## 业务规则 - 订单总金额 (`orders.total_amount_cents`) 应等于其下所有订单项小计 (`order_items.subtotal_cents`) 之和。此逻辑应在应用层或数据库触发器中强制保证。 - 订单状态流转是单向的：`pending` -> `processing` -> `shipped` -> `delivered`。`cancelled` 和 `refunded` 可以从 `pending` 或 `processing` 状态转入。 - `order_items.unit_price_cents` 是下单时的价格快照，后续产品价格 (`products.price_cents`) 变动不影响历史订单。

花15分钟写下这样的规约，可以避免未来数小时甚至数天的重构和调试。AI基于这份清晰的“蓝图”生成的SQL迁移文件、TypeScript类型定义、ORM模型和API接口，在结构正确性上会有质的飞跃。

4. 实操流程：将上下文工程融入日常开发

理解了核心文件后，关键在于如何将其无缝整合到你的工作流中。以下是我在一个典型功能开发任务中的实操步骤。

4.1 阶段一：任务启动与上下文准备

假设我需要开发一个“用户收藏夹”功能。

1. 打开AI工具并加载项目：在Claude Code或Cursor等工具中，打开项目根目录。确保工具已配置为能读取项目文件。

2. 提供高层级任务描述：我的初始提示词会非常简洁，因为大部分上下文已存在于文件中。

   “我们需要为用户添加一个收藏产品（products）的功能。请先阅读项目的CLAUDE.md和PRODUCT_SPEC.md文件，特别是关于数据模型和用户系统的部分，然后提出你的实现方案。”

3. AI消化上下文：AI会读取相关文件，理解技术栈（比如我们用Vue 3 + Pinia）、设计系统、以及现有的users和products表结构。它也会从产品文档中知道，这是一个增强用户粘性的功能，优先级高于社交分享但低于购物车。

4.2 阶段二：协作式设计与数据建模

1. AI提出初步方案：基于上下文，AI可能会回复：

   “根据CLAUDE.md，我们使用TypeScript严格模式和PostgreSQL。根据现有数据模型，我建议新增一张favorites表，与users和products建立多对多关系。前端需要在产品卡片上添加收藏按钮，并在用户中心增加收藏列表页。这是初步的ER图思路和API端点设计……”

2. 我进行细化与约束：我会审查这个方案，并用自然语言补充业务规则，这本质上是在迭代数据模型规约。

   “方案大体正确。但注意：1. 收藏关系应该是用户-产品的唯一组合，避免重复收藏。2. 需要记录收藏时间favorited_at。3. 产品被下架 (is_active = false) 后，仍应在收藏列表中显示，但标记为‘已失效’。请基于这些更新数据模型规约草案。”

3. 生成并确认最终规约：AI会生成一份更新的DATA_MODEL_FAVORITES.md草案。我确认后，将其核心部分合并到主数据模型文档或作为独立附件。这个过程确保了双方对“要建什么”达成精确共识。

4.3 阶段三：分步实施与上下文引用

1. 数据库迁移：

   “现在，请根据我们确认的favorites表规约，生成一个PostgreSQL迁移文件（使用Alembic/Knex/TypeORM格式，根据CLAUDE.md中的技术栈选择）。记得添加唯一约束和索引。”

2. 后端API与类型：

   “接下来，生成TypeScript类型定义Favorite.ts。然后，创建对应的RESTful API控制器，包含GET /api/users/me/favorites（分页列表），POST /api/products/:id/favorite，DELETE /api/favorites/:id。请遵循CLAUDE.md中关于错误处理和API URL结构的规则。”

3. 前端组件：

   “现在实现前端。首先，在Pinia中创建useFavoriteStore。然后，创建一个可复用的FavoriteButton.vue组件，它接收productId，根据当前收藏状态显示不同图标（使用CLAUDE.md中定义的图标库），点击时调用Store中的action。最后，创建一个UserFavoritesPage.vue页面，展示用户的收藏列表，产品失效时按规则显示。所有文本需使用i18n。”

在整个过程中，我几乎不需要重复解释技术栈、代码规范或设计细节。AI会主动引用CLAUDE.md中的规则，比如：“根据CLAUDE.md中的设计系统，我将使用红色#EF4444作为已收藏状态的颜色。”

4.4 阶段四：验收与技能封装

1. 代码审查与测试：AI生成代码后，我会要求它：

   “请运行pnpm lint检查生成的代码。然后，为FavoriteButton组件编写一个Vitest单元测试，模拟用户点击和Pinia状态变化。”

2. 封装工作流（如适用）：如果这个“添加收藏”功能是某个更大流程的一部分（比如“新品上线推广流程”），我会将“创建产品->添加到精选列表->通知收藏用户”这个多步骤工作流，封装成一个新的技能文件skills/promote-new-product.md。

5. 常见问题与避坑指南

在实践中，你会遇到各种问题。以下是我踩过坑后总结的经验。

5.1 问题：AI忽略了上下文文件中的某条规则

表现：生成的代码违反了CLAUDE.md中明确写明的规则，比如使用了行内样式或any类型。

排查与解决：

1. 检查文件位置与命名：确保CLAUDE.md位于项目根目录，且AI工具的文件读取范围包含它。有些工具需要手动“上传”或“添加”项目文件夹。
2. 在提示词中显式提醒：对于特别重要的规则，可以在任务提示词开头重申：“请务必严格遵守CLAUDE.md中关于TypeScript禁止使用any和样式必须使用Tailwind的规则。”
3. 规则表述清晰度：检查你的规则描述是否足够明确、无歧义。将“写好代码”改为“ESLint配置必须零错误；使用完整的TypeScript类型定义”。
4. 分步验证：不要等所有代码生成完再检查。可以分步进行：“先只生成TypeScript接口定义，我确认无误后，再继续生成组件逻辑。”

5.2 问题：上下文文件过于冗长，AI无法有效处理

表现：AI的回答开始偏离主题，或者似乎没有理解文件中的所有内容，尤其是当文件非常大时。

优化策略：

1. 模块化拆分：不要把所有东西塞进一个CLAUDE.md。可以拆分为：
   • CONTEXT_DESIGN.md：专用于设计系统、品牌规范。
   • CONTEXT_TECH.md：专用于技术栈、项目结构、开发命令。
   • CONTEXT_RULES.md：专用于强制性编码规则。 在CLAUDE.md中只保留索引和最关键信息，并指引AI去查阅特定文件。
2. 使用摘要：在每个长文件的顶部，添加一个“本章摘要”部分，用3-5个要点总结核心内容。AI在 token 受限时，可能会优先阅读摘要。
3. 保持更新与精简：定期回顾上下文文件，删除过时的、合并重复的。保持文档的简洁和时效性。

5.3 问题：不同AI工具或模型对上下文的理解不一致

表现：在Claude中工作良好的上下文，切换到GitHub Copilot Chat或ChatGPT时效果打折扣。

应对方案：

1. 采用最低公约数格式：坚持使用纯Markdown格式，避免使用某个工具特有的标记或语法。这是兼容性最强的格式。
2. 准备工具特定的引导提示词：创建一个ONBOARDING_PROMPT.txt文件，里面包含针对不同工具的“开场白”。例如，对于不擅长自动读取文件的工具，你的第一条提示词可以是：“我将为你提供本项目的关键上下文，请仔细阅读：”然后粘贴CLAUDE.md的精华部分。
3. 核心规则内联化：对于最重要的3-5条规则（如禁止any、使用i18n），即使在有上下文文件的情况下，也可以在复杂任务开始时，在提示词中简短重申，作为“双重保险”。

5.4 问题：团队协作时，上下文文件如何维护？

表现：你创建了完美的CLAUDE.md，但队友不更新，或者各自有不同的版本，导致AI产出混乱。

建立团队规范：

1. 版本控制：将CLAUDE.md、PRODUCT_SPEC.md等文件纳入Git版本控制。任何修改都需要通过Pull Request和代码审查。
2. 定义负责人：指定团队成员（如Tech Lead或产品负责人）作为这些上下文文件的维护者，负责审核和合并更新。
3. 在团队中推广：在团队内部分享使用上下文文件后效率提升的案例，将其作为新成员入职的必备阅读材料。让团队形成“修改代码前，先看上下文文件”的习惯。
4. 与现有文档融合：如果团队已有Wiki或Notion，可以将这些上下文文件视为其“AI优化版”的子集或导出物，保持信息同步。

5.5 问题：如何处理模糊或需要创意判断的任务？

表现：AI在面对“让这个页面看起来更现代”或“优化这个用户体验”等主观任务时，即使有上下文，也可能给出平庸或不合预期的方案。

引导策略：

1. 提供参考与范例：在提示词中链接到CLAUDE.md中提到的设计稿（Figma链接），或直接提供1-2个你欣赏的、符合产品调性的参考网站或截图。“请参考Figma中‘仪表盘v2’页面的视觉风格，特别是卡片阴影和间距层级。”
2. 设定明确的成功标准：将主观任务客观化。“优化注册表单的体验”可以改为：“目标是将注册转化率提升5%。请从以下角度提供修改方案：1. 减少必填字段数量；2. 优化手机号输入验证的即时反馈；3. 明确隐私政策链接。请给出具体的代码修改建议。”
3. 请求多方案选择：不要问“怎么做好？”，而是问“请基于我们的设计系统，提供A、B、C三种不同的按钮布局方案，并简要说明每种方案的视觉权重和适用场景。”

6. 进阶技巧：让上下文动态化与智能化

基础的文件系统建立后，你可以进一步优化，让上下文工程体系更强大。

6.1 利用“当前工作区”信息

许多先进的AI编码工具（如Claude Code、Cursor）不仅能读取文件，还能感知你“当前打开的文件”、“最近编辑的文件”以及“终端输出的错误”。在提示词中主动利用这一点：

“我正在编辑src/components/ProductCard.vue文件，需要为它添加收藏功能。这是该文件当前的内容。请根据我们之前讨论的favorites数据模型和useFavoriteStore，在此文件基础上进行修改，保持其现有样式和结构不变。”

这样AI提供的代码差异（diff）会非常精准，直接贴合你当前的代码上下文。

6.2 创建“上下文摘要”或“备忘单”

对于大型项目，可以创建一个CONTEXT_CHEATSHEET.md文件，这是一个极简的快速参考指南，只包含最常用、最容易忘记的规则：

# 上下文速查表 (5分钟上手) ## 绝对禁止 - ❌ `any` 类型 - ❌ 行内 `style` 或 `<style scoped>` 中的全局样式 - ❌ 硬编码文本（必须用 `$t()`） - ❌ 提交前不通过 `pnpm lint` ## 必须遵守 - ✅ 所有组件使用 `<script setup>` - ✅ 状态管理用 Pinia，逻辑复用用 Composables - ✅ 图标来自 `@/components/icons/`，颜色来自 `tailwind.config.js` - ✅ API调用必须用 `useApi()` 封装，错误必须处理 ## 常用命令 - 开发: `pnpm dev` - 构建: `pnpm build` - 代码检查: `pnpm lint` - 测试: `pnpm test`

这个文件可以在开启每一个新的AI会话时，作为第一条信息发送，进行“预热”。

6.3 将调试信息纳入上下文

当AI生成的代码运行时出现错误，不要仅仅把错误信息丢给它。将调试过程也结构化：

1. 复制终端错误日志。
2. 指出相关代码文件及行号。
3. 提供你已尝试的排查步骤。
4. 要求AI根据CLAUDE.md中的技术栈和常见问题部分进行分析。

例如：

“运行pnpm test时，FavoriteButton.spec.ts在第23行失败。错误是[Vue warn]: Failed to resolve component: IconHeart。我已经检查了components/icons/目录，IconHeart.vue文件存在。根据CLAUDE.md，图标组件是自动全局注册的。请分析可能的原因并提供修复方案。”

这种方式将AI从代码编写者，提升为问题诊断伙伴。

7. 心态转变：从“提示词工程师”到“上下文架构师”

最后，我想分享最重要的体会，这不是一个技巧，而是一种心态的转变。

过去一年，我看到“提示词工程”这个词被过度炒作，仿佛存在某种魔法咒语，只要找到它，AI就能吐出完美代码。这让人把精力放在了错误的地方——不断微调提问的措辞，却忽略了AI就像一个天赋极高但毫无经验的新人，它最需要的不是如何被提问，而是如何被赋能。

上下文工程的本质，就是为这位“新人”系统性地赋能。你不再是那个在每次对话中疲于解释基础的“导师”，而是成为了设计工作环境、制定操作手册、搭建质量体系的“架构师”。

你的核心工作前置了：从“每次交互时思考如何提问”，变成了“在项目开始时，如何设计一套能让AI持续高效、正确工作的知识体系”。CLAUDE.md是你的技术蓝图，PRODUCT_SPEC.md是你的产品指南，技能文件是你的标准作业程序，数据模型规约是你的领域契约。

这套体系的回报是非线性的。创建第一个文件的投入是实实在在的，但第二个、第三个项目你可以复用和调整它们。随着时间推移，你积累的不是一堆散落的提示词，而是一个可移植、可演进、不断丰富的“项目智慧库”。当你开始一个新项目，你能迅速为其装备一个强大的“AI就绪”环境。

最终，衡量成功的标准不再是“我这次问出了一个好问题”，而是“我的AI在无人值守的情况下，遵循项目规范完成工作的比例有多高”。当你发现，你只需要说“像上次处理用户个人资料那样，为这个新设置页面添加一个表单验证技能”，而AI就能准确无误地调用正确的上下文和流程时，那种流畅感，才是AI真正改变工作方式的时刻。

这不仅仅是关于Claude或某个特定工具。这是一个适用于任何能够处理文本和代码的AI辅助工具的通用的、根本性的方法。谁先理解并实践这一点，谁就将在人机协作的效率和代码质量上，获得实实在在的、长期的竞争优势。