【WorkBuddy专栏20】项目指令的深度解析——如何让AI真正理解你的意图

你有没有遇到过这样的情况：明明给AI下了很详细的指令，它却理解偏差，做出来的东西完全不是你要的？问题往往不在AI不够聪明，而在于你的「项目指令」写得不够精准。项目指令是WorkBuddy的「导航系统」，决定了AI的行为模式和工作方向。本文将深度解析项目指令的设计原理和实战技巧。

一、项目指令的本质------AI的「工作手册」

1.1 什么是项目指令？

项目指令（Project Instructions）是WorkBuddy的核心配置，它定义了AI在特定项目中的行为规则、工作流程和输出标准。简单来说：

• 没有项目指令：AI使用默认行为，泛泛而谈
• 有项目指令：AI理解项目上下文，精准执行

类比来说，项目指令就像给新员工发的「员工手册」+「项目文档」。没有这些，新员工只能凭感觉做事；有了这些，他们能快速融入团队，按规则工作。

1.2 项目指令 vs 技能 vs 提示词

这三个概念容易混淆，让我们用一张表厘清：

维度	项目指令	技能	提示词
作用范围	整个项目周期	特定任务场景	单次对话
持久性	项目期间持续有效	持久化，可复用	对话结束即消失
内容类型	规则、标准、流程	工具、知识、逻辑	任务描述、示例
修改频率	较低（项目周期内稳定）	中等（技能迭代）	很高（每次对话可能不同）
示例	「所有代码必须用TypeScript」	「GitHub管理技能」	「帮我写一个登录函数」

核心关系：

• 项目指令是「宪法」（根本大法）
• 技能是「部门规章」（专门领域的规则）
• 提示词是「具体任务单」（临时工作指令）

1.3 项目指令的层级结构

WorkBuddy的项目指令采用「层级式」设计，从宏观到微观：

全局指令（~/.workbuddy/global.md）
    ↓ 影响所有项目
工作区指令（.workbuddy/global.md）
    ↓ 影响当前工作区所有项目
项目指令（.workbuddy/project.md）
    ↓ 只影响当前项目
会话指令（对话开始时指定）
    ↓ 只影响当前对话

优先级：会话指令 > 项目指令 > 工作区指令 > 全局指令

设计原理：越具体的指令，优先级越高。这遵循了「特殊优于一般」的原则。

二、项目指令架构深度拆解

2.1 项目指令文件结构

一个完整的项目指令文件（.workbuddy/project.md）包含以下部分：

# 项目指令

## 项目概述
（项目背景、目标、技术栈）

## 行为规则
（AI必须遵守的规则）

## 工作流程
（处理任务的步骤和规范）

## 输出标准
（代码、文档、回复的格式要求）

## 禁忌清单
（明确禁止的行为）

## 参考资料
（相关文档、API手册的链接）

2.2 核心模块详解

模块1：项目概述

目的：让AI快速理解项目上下文

必备要素：

1. 项目类型：Web应用、CLI工具、机器学习项目...
2. 技术栈：前端框架、后端语言、数据库...
3. 目标用户：开发者、终端用户、内部工具...
4. 当前阶段：MVP、迭代中、维护期...

示例：

## 项目概述

项目名称：WorkBuddy技能市场
项目类型：Web应用（全栈）
技术栈：
- 前端：React + TypeScript + Tailwind CSS
- 后端：Node.js + Express + MongoDB
- 部署：Docker + Kubernetes

目标用户：AI开发者和普通用户
当前阶段：MVP开发（已完成核心功能，正在完善UI）

项目目标：打造一个类似「插件市场」的平台，让用户可以发布、分享、安装WorkBuddy技能

模块2：行为规则

目的：定义AI的「职业操守」

分类：

1. 代码规范：命名、格式、注释要求
2. 安全规则：敏感信息处理、权限控制
3. 性能要求：响应时间、资源占用限制
4. 沟通风格：回复的语气、详细程度

示例：

## 行为规则

### 代码规范
- 所有代码必须用TypeScript编写，不允许使用any类型
- 函数必须有JSDoc注释，说明参数和返回值
- 变量命名使用camelCase，常量使用UPPER_SNAKE_CASE
- 代码格式遵循Prettier配置（.prettierrc）

### 安全规则
- 绝对不允许将API密钥、密码硬编码在代码中
- 所有用户输入必须做合法性验证
- 敏感操作（如删除数据）必须请求用户确认

### 性能要求
- API响应时间必须小于200ms（P95）
- 数据库查询必须建立合适索引
- 前端包大小不超过500KB（gzip后）

### 沟通风格
- 回复简洁明了，避免冗长的解释
- 代码示例优先于文字描述
- 遇到不确定问题时，主动询问而非猜测

模块3：工作流程

目的：规范AI处理任务的标准流程

典型流程：

1. 需求理解：如何解析用户意图
2. 方案设计：如何选择技术方案
3. 代码实现：编码规范和步骤
4. 测试验证：测试方法和标准
5. 部署发布：部署流程和检查点

示例：

## 工作流程

### 需求理解阶段
1. 如果用户需求不明确，主动询问3个关键问题：
   - 具体要实现什么功能？
   - 有没有参考示例？
   - 有什么约束条件（性能、兼容性等）？
2. 确认理解后，用一句话复述需求，等待用户确认

### 方案设计阶段
1. 列出2-3个可行方案，说明优缺点
2. 推荐一个方案，并解释理由
3. 如果方案涉及新技术，提供学习资料链接

### 代码实现阶段
1. 先写伪代码或流程图，确认逻辑正确
2. 按照「测试驱动开发（TDD）」原则，先写测试再写实现
3. 每完成一个功能模块，立即运行测试

### 测试验证阶段
1. 单元测试覆盖率必须达到80%以上
2. 手动测试关键流程（happy path + edge cases）
3. 性能测试（如果涉及性能敏感功能）

### 部署发布阶段
1. 检查环境变量配置
2. 运行数据库迁移脚本（如果有）
3. 灰度发布（先发布到10%用户）

模块4：输出标准

目的：确保输出质量一致

输出类型：

1. 代码输出：格式、注释、错误处理
2. 文档输出：结构、术语、示例
3. 回复输出：语气、详细程度、格式

示例：

## 输出标准

### 代码输出
- 每个文件头部必须有文件说明注释
- 复杂逻辑必须有行内注释
- 错误处理必须使用try-catch，并返回友好错误信息
- 代码示例必须可运行（包含所有import和示例数据）

### 文档输出
- 使用Markdown格式，遵循GitHub Flavored Markdown规范
- 标题层级不超过3级（#、##、###）
- 技术术语首次出现时，用加粗并给出解释
- 每个章节必须有实际内容，不允许空章节

### 回复输出
- 回答问题时，先给结论，再给解释
- 提供多个方案时，用表格对比
- 代码示例使用语法高亮，并注明语言类型

模块5：禁忌清单

目的：明确「红线」，防止AI犯错

典型禁忌：

1. 安全禁忌：不泄露敏感信息
2. 质量禁忌：不提交未测试的代码
3. 沟通禁忌：不承诺无法实现的功能

示例：

## 禁忌清单

### 绝对禁止
- ❌ 不要修改.gitignore中指定的文件
- ❌ 不要删除数据库中的数据（除非用户明确指示）
- ❌ 不要在生产环境中直接测试
- ❌ 不要忽略错误信息，必须处理或上报

### 尽量避免
- ⚠️ 避免一次性重写大量代码（容易引入bug）
- ⚠️ 避免使用过于复杂的正则表达式（难以维护）
- ⚠️ 避免深度嵌套的回调函数（改用async/await）

### 需要确认
- ❓ 涉及第三方服务的集成，先确认API配额和费用
- ❓ 涉及数据库schema变更，先确认兼容性
- ❓ 涉及用户体验的重大变更，先做A/B测试

三、实战案例------3种典型场景

3.1 案例1：前端项目指令

项目背景：一个React + TypeScript的前端项目

项目指令要点：

## 项目概述
这是一个面向开发者的技术博客平台，使用React 18 + TypeScript + Vite构建。

## 技术约束
- 必须使用函数组件 + Hooks，禁止使用Class组件
- 状态管理使用Zustand，不使用Redux
- 样式使用Tailwind CSS，不使用CSS Modules
- 图标使用Heroicons库

## 代码规范
- 组件文件名使用PascalCase（如`UserProfile.tsx`）
- Hook文件名使用camelCase，以`use`开头（如`useAuth.ts`）
- 每个组件不超过200行代码，超过则拆分
- 所有props必须定义interface，不允许使用object类型

## 工作流程
1. 创建组件时，先写Storybook故事
2. 实现组件逻辑
3. 编写单元测试（使用Vitest）
4. 在Storybook中手动测试不同状态
5. 提交代码前运行`npm run lint`和`npm run test`

效果：AI生成的代码完全符合团队规范，无需手动调整。

3.2 案例2：后端项目指令

项目背景：一个Node.js + Express的API服务项目

项目指令要点：

## 项目概述
这是一个RESTful API服务，为移动端App提供后端支持。使用Node.js 18 + TypeScript + Express。

## 架构规则
- 严格按照Controller-Service-Repository分层
- Controller只处理HTTP请求，不写业务逻辑
- Service处理业务逻辑，不直接操作数据库
- Repository封装数据库操作，不写业务逻辑

## 错误处理
- 所有错误必须抛出自定义AppError（不允许直接throw Error）
- 错误必须有错误码和错误消息
- 在Controller层统一捕获错误，返回标准JSON格式

## API规范
- 响应格式：{ "code": 0, "data": {}, "message": "success" }
- 错误响应：{ "code": 1001, "data": null, "message": "参数错误" }
- 分页参数：page（页码）、pageSize（每页数量）
- 分页响应：{ "code": 0, "data": { "list": [], "total": 100, "page": 1, "pageSize": 20 } }

## 安全规则
- 所有用户输入使用Joi验证
- 敏感接口（如修改密码）需要rate limiting
- SQL查询使用参数化查询，防止SQL注入

效果：AI生成的API代码结构清晰，错误处理完善，安全性高。

3.3 案例3：全栈项目指令

项目背景：一个需要前后端协作的全栈项目

项目指令要点：

## 项目概述
这是一个全栈项目，前端使用Next.js，后端使用NestJS，共享类型定义。

## 前后端协作规范
- 类型定义放在`shared/types/`目录，前后端共同引用
- API接口定义放在`shared/api/`目录，使用OpenAPI规范
- 前端使用Swagger生成的客户端，不直接写fetch代码
- 后端必须提供API文档（使用Swagger UI）

## 开发流程
1. 后端先定义API接口（包括请求/响应类型）
2. 更新`shared/`目录下的类型定义
3. 前端根据类型定义开发UI
4. 后端实现API逻辑
5. 前后端联调

## 测试策略
- 后端：单元测试（Jest）+ 集成测试（Supertest）
- 前端：单元测试（Jest）+ E2E测试（Cypress）
- 共享：类型检查（TypeScript compiler）

## 部署流程
- 前端部署到Vercel，后端部署到Railway
- 使用GitHub Actions自动部署
- 环境变量使用.env文件管理，不允许硬编码

效果：前后端开发高效协作，类型安全，减少沟通成本。

四、项目指令设计心法

从多个项目的实践中，我总结了以下设计原则：

4.1 具体优于抽象

原则：指令要具体、可操作，避免模糊的表述

❌ 抽象指令：

代码要写得清晰易懂。

✅ 具体指令：

代码清晰标准：
1. 变量名必须是自解释的（如`userList`而非`list`）
2. 函数长度不超过30行，超过则拆分
3. 复杂逻辑必须写注释，说明「为什么」而非「是什么」
4. 每个函数只做一件事（单一职责原则）

4.2 示例优于描述

原则：给出具体示例，让AI有参照物

❌ 纯文字描述：

组件props要有默认值。

✅ 带示例的说明：

组件props要有默认值。

示例：
// ❌ 错误写法
interface ButtonProps {
  text: string;
}

// ✅ 正确写法
interface ButtonProps {
  text: string;
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
}

const Button = ({ 
  text, 
  size = 'medium',  // 默认值
  disabled = false  // 默认值
}: ButtonProps) => {
  // ...
};

4.3 约束优于自由

原则：明确禁止事项，减少AI的「自由发挥」

❌ 只说能做什么：

你可以使用React Router进行路由管理。

✅ 同时说能和不能：

路由管理使用React Router v6。

允许：
- 使用嵌套路由
- 使用lazy loading
- 使用路由守卫

禁止：
- 不要使用React Router v5的语法
- 不要在一个文件中定义所有路由（要拆分到模块）
- 不要使用hash路由（使用history路由）

4.4 迭代优于完美

原则：项目指令不需要一次写完美，可以逐步迭代

推荐流程：

1. 初版：写下最核心的3-5条规则
2. 使用：在实际使用中发现问题
3. 补充：针对问题补充指令
4. 重构：定期整理，删除过时指令

示例：

// 第1版（核心规则）
- 代码用TypeScript
- 提交前必须跑测试

// 第2版（补充细节）
- 代码用TypeScript（不允许any类型）
- 提交前必须跑测试（覆盖率≥80%）
- 新增：组件必须写Storybook故事

// 第3版（重构优化）
## 代码规范
- 必须使用TypeScript，不允许any类型
- 单元测试覆盖率≥80%

## 组件规范
- 必须使用函数组件 + Hooks
- 必须编写Storybook故事

4.5 分层优于扁平

原则：指令要有结构，方便查找和维护

❌ 扁平结构：

要用TypeScript。
要写测试。
要加注释。
代码不超过200行。
变量名要清晰。
...（几十条规则混在一起）

✅ 分层结构：

## 代码规范
### 语言要求
- 必须使用TypeScript
- 不允许使用any类型

### 质量要求和详细程度
- 单元测试覆盖率≥80%
- 所有public函数必须有JSDoc注释

## 架构规范
### 文件组织
- 单个文件不超过200行
- 组件和样式文件放在同一目录

### 命名规范
- 变量名必须自解释
- 组件名使用PascalCase

五、避坑指南

5.1 坑1：指令过于冗长

现象：项目指令写了5000字，AI反而「理解混乱」

原因：信息过载，AI抓不住重点

解决：

1. 遵循「3-5-3原则」：3个核心规则、5个重要规则、3个补充规则
2. 使用「渐进式指令」：基础指令写在project.md，高级指令写在单独的.md文件，按需加载
3. 定期重构：删除过时、重复的指令

5.2 坑2：指令相互矛盾

现象：指令A说「要写详细注释」，指令B说「代码要简洁」

原因：不同时间写的指令，没有整体审查

解决：

1. 指令分类：强制规则（必须遵守）、推荐规则（尽量遵守）、可选规则（参考）
2. 冲突解决：强制规则 > 推荐规则 > 可选规则
3. 定期审查：每周检查一次指令，发现矛盾立即修正

5.3 坑3：指令过于严格

现象：AI变得「束手束脚」，连简单任务都要反复确认

原因：指令中「禁止」太多，「允许」太少

解决：

1. 平衡「约束」和「自由」：核心规则严格，非核心规则宽松
2. 使用「灰度指令」：如「尽量避免」而非「绝对禁止」
3. 设置「紧急通道」：当用户说「跳过检查」时，允许AI灵活处理

5.4 坑4：忽略负面指令

现象：只告诉AI「要做什么」，没告诉「不要做什么」

原因：人们倾向于正向思考

解决：

1. 每个正向指令，都思考对应的负向指令
2. 例如：「代码要清晰」→「不要写嵌套超过3层的回调函数」
3. 建立「禁忌清单」模板，每次写指令时对照检查

5.5 坑5：没有版本管理

现象：项目指令改来改去，不知道哪个版本是对的

原因：没有把项目指令当作「代码」来管理

解决：

1. 项目指令文件加入Git版本控制
2. 每次修改都写commit message
3. 重大修改创建新分支，测试后再合并

六、总结

本文深度解析了WorkBuddy项目指令的设计原理和实战技巧：

1. 项目指令的本质是AI的「员工手册」，让它理解项目上下文和工作规范
2. 项目指令架构包含项目概述、行为规则、工作流程、输出标准、禁忌清单5个核心模块
3. 实战案例展示了前端、后端、全栈3种典型项目的指令设计
4. 设计心法遵循具体优于抽象、示例优于描述等5个原则
5. 避坑指南帮助我们避免指令冗长、矛盾、过于严格等常见错误

下一步行动：

• 检查你当前项目的指令文件，用本文的原则优化它
• 建立一个「指令模板库」，方便新项目快速启动
• 关注后续专栏，我们将深入解析「如何让AI自动优化项目指令」

项目指令是WorkBuddy的「灵魂」。写好项目指令，就像给AI装上了「导航系统」，让它能精准、高效地完成任务。投入时间写好项目指令，是最值得的技术投资之一。

专栏导航

本文是「腾讯小龙虾 WorkBuddy 专栏」第 20 篇。

篇目	标题	状态
01	【WorkBuddy专栏01】WorkBuddy 入门：从零开始认识你的 AI 编程搭档	已发布
02	【WorkBuddy专栏02】WorkBuddy 技能系统：让 AI 学会你的工作方式	已发布
03	【WorkBuddy专栏03】WorkBuddy 自动化：让 AI 定时帮你干活	已发布
04	【WorkBuddy专栏04】一文搞懂WorkBuddy的「专家」和「专家团」------AI界的复仇者联盟	已发布
05	【WorkBuddy专栏05】深度解析WorkBuddy连接器(Connector)------MCP协议如何让AI打通你的所有工具	已发布
06	【WorkBuddy专栏06】让AI住进你的微信------WorkBuddy微信生态接入完全指南	已发布
07	【WorkBuddy专栏07】把AI训练成你的专属员工------WorkBuddy Skill系统深度解析	已发布
08	【WorkBuddy专栏08】从「定时任务」到「数字员工」------WorkBuddy自动化系统深度拆解	已发布
09	【WorkBuddy专栏09】AI不止会聊天------WorkBuddy多模态能力深度揭秘	已发布
10	【WorkBuddy专栏10】你的AI终于学会「分项目干活」了------WorkBuddy项目功能完全指南	已发布
11	【WorkBuddy专栏11】WB项目不是TAPD------一张图说清项目管理的「大脑」和「双手」	已发布
12	【WorkBuddy专栏12】技能到底存在哪？------WorkBuddy两级技能存储架构深度解析	已发布
13	【WorkBuddy专栏13】WB的「记忆系统」是怎么搭建的------配置文件架构与月度整理方法论	已发布
14	【WorkBuddy专栏14】专家不是「换皮」------角色切换、训练机制与自我进化深度拆解	已发布
15	【WorkBuddy专栏15】灵感被折叠到「更多」里，真的不重要了吗？	已发布
16	【WorkBuddy专栏16】三层记忆系统深度拆解------让AI真正「记住」你	已发布
17	【WorkBuddy专栏17】一个 AI 不够用？WorkBuddy SubAgent 多智能体协作系统深度拆解	已发布
18	【WorkBuddy专栏18】WorkBuddy API深度解析------打造开发者友好的AI生态	已发布
19	【WorkBuddy专栏19】技能的创造与迁移------从零开始打造你的AI工作流	已发布
20	【WorkBuddy专栏20】项目指令的深度解析------如何让AI真正理解你的意图	本文