1. 为什么你的AI助教总是“答非所问”很多人配好了AI助教兴冲冲地丢进去一个需求结果它要么答得云里雾里要么直接跑偏到十万八千里外。折腾几轮下来人比不用AI还累。问题出在哪大概率不在模型本身而在项目配置这一层没做对。我做了十几个AI助教类项目之后最大的体会是模型的能力是天花板但项目配置决定了你实际能摸到多高。一个配置得当的AI助教能准确理解你的项目结构、知道哪些文件该读、哪些规则必须遵守、遇到模糊需求时该追问还是该动手。而一个配置潦草的AI助教就像一个耳背又近视的实习生你说东它听成西你让它改个按钮它把整个页面重构了。这篇内容就是把我踩过的坑和验证过的配置方法完整拆开讲。核心围绕四个东西项目指令、资产库、提示词、上下文管理。不管你是用Cursor、Windsurf、Cline还是自己搭的Agent框架这套配置思路都能直接迁移。适合已经跑通过基础AI助教、但效果不稳定的开发者也适合刚接触AI编程助手、想少走弯路的新手。2. 项目配置的整体设计思路2.1 把AI助教当成一个新入职的工程师我见过太多人配置AI助教的方式是写一段超级长的系统提示词恨不得把毕生所学全塞进去然后指望它一次到位。这就像给新员工一本一万页的员工手册然后让他立刻上手干活——他只会懵。正确的思路是把AI助教当成一个聪明但完全不了解你项目的新人。你需要给它的是项目的地图目录结构、技术栈、关键模块工作的规矩代码规范、提交格式、禁止事项参考的范例资产库里的优质代码片段沟通的方式什么时候该问、什么时候该直接做这四样东西对应到配置层面就是项目指令文件、规则约束、资产库和交互协议。缺一个AI助教就会在某个维度上“失聪”或“失明”。2.2 分层配置而不是一锅炖我的配置方案是分层的从外到内依次是层级作用典型文件加载时机全局层跨项目通用规则全局规则文件每次会话项目层当前项目的架构与规范项目指令文件进入项目时模块层特定模块的详细说明模块级说明文件涉及该模块时任务层当前任务的临时上下文对话中的提示词按需这样分层的好处是token不浪费。全局层只放最通用的规则项目层放架构信息模块层按需加载。我实测下来同样一个中等复杂度的项目分层配置比一锅炖的token消耗降低40%以上而且AI助教的回答准确率反而更高——因为它不会被无关信息干扰。2.3 配置的核心目标让AI助教“知道边界”很多人忽略的一点是AI助教最大的问题不是不够聪明而是不知道自己不知道什么。它会自信地编造一个不存在的API会擅自修改你没让它动的文件会用一套和你项目完全不符的代码风格。项目配置的核心目标就是给它划清边界知识边界哪些文件是它该读的哪些不该碰操作边界哪些操作可以直接做哪些必须先问风格边界代码怎么写、命名怎么定、注释怎么加输出边界回答的格式、长度、详细程度边界越清晰AI助教的表现越稳定。这就像给一个能力强但方向感差的人配了导航他才能把能力用在正确的地方。3. 项目指令文件给AI助教一张精确的地图3.1 项目指令文件该写什么项目指令文件不同工具叫法不同有的叫Rules有的叫System Prompt有的叫Project Instructions是整个配置体系的核心。我见过很多人把它写成了“愿望清单”——“希望你写出高质量的代码”“请遵循最佳实践”——这些全是废话AI助教看了等于没看。有效的项目指令文件应该包含以下内容我按优先级排序第一优先级项目基本信息## 项目概览 - 项目名称XXX后台管理系统 - 技术栈Vue3 TypeScript Vite Pinia Element Plus - 后端接口RESTful API基础路径 /api/v1 - 包管理器pnpm禁止使用npm或yarn - Node版本18.0.0这些信息看起来简单但能避免大量低级错误。比如你不写包管理器AI助教可能一会儿用npm一会儿用yarn导致lock文件混乱。第二优先级目录结构与职责## 目录结构 - src/api/所有接口请求按模块分文件 - src/components/通用组件每个组件一个目录 - src/views/页面组件与路由一一对应 - src/stores/Pinia状态管理按业务域拆分 - src/utils/工具函数纯函数优先 - src/types/全局类型定义写目录结构的时候一定要写清楚每个目录的职责边界。比如“src/components/放通用组件”那什么算通用我的经验是加一句判断标准“被两个以上页面使用的组件才放入components否则放在对应views下的components子目录”。这种具体的规则AI助教才能执行。第三优先级代码规范## 代码规范 - 组件名使用PascalCase文件名与组件名一致 - 组合式函数以use开头如useUserInfo - API请求函数以模块名开头如getUserList、createOrder - 禁止使用any类型不确定的类型用unknown - 所有异步操作必须处理错误使用try-catch或.catch() - 注释使用JSDoc格式公共函数必须写注释代码规范这部分越具体越好。不要写“遵循ESLint规范”而要写清楚具体的命名规则、错误处理方式、注释格式。因为AI助教不知道你的ESLint配置里具体开了哪些规则它需要明确的指令。第四优先级禁止事项## 禁止事项 - 禁止修改package.json中的依赖版本 - 禁止删除任何现有文件除非明确要求 - 禁止在组件中直接调用API必须通过store或composable - 禁止使用console.log调试信息用logger工具 - 禁止提交包含TODO的代码禁止事项是很多人会忽略的部分但它极其重要。AI助教有时候会“自作主张”地优化一些它认为不合理的地方比如升级依赖版本、重构它觉得冗余的代码。明确的禁止事项能有效遏制这种行为。3.2 项目指令文件的写法技巧写项目指令文件有几个技巧是我踩了很多坑之后总结出来的技巧一用“必须”“禁止”代替“建议”“尽量”AI助教对模糊词汇的理解很不稳定。“建议使用TypeScript”和“必须使用TypeScript”在AI助教那里的执行力度完全不同。我的经验是能用“必须/禁止”就不用“建议/尽量”。如果某件事真的只是建议那就不写写了反而干扰。技巧二每条规则都要可验证“写出高质量的代码”这种规则无法验证AI助教也不知道自己有没有做到。而“所有函数必须有返回类型注解”就是可验证的——它写完代码可以自己检查有没有做到。技巧三规则数量控制在20条以内我试过写50多条规则结果AI助教反而记不住经常遗漏。后来精简到15-20条核心规则执行率明显提升。规则太多等于没有规则因为AI助教的注意力被分散了。技巧四用示例代替描述与其写“API请求函数要统一处理错误”不如直接给一个示例// 正确的API请求写法 export async function getUserList(params: UserListParams): PromiseUserListResult { try { const { data } await request.get(/users, { params }) return data } catch (error) { logger.error(获取用户列表失败, error) throw new BusinessError(获取用户列表失败) } }一个示例胜过十句描述。AI助教是模式匹配的高手给它看一个正确的模式它就能照着写。3.3 不同工具的指令文件位置不同AI编程工具的指令文件位置和格式不同我整理了一个对照表工具指令文件位置格式备注Cursor.cursorrules 或 .cursor/rules/Markdown支持多文件分模块Windsurf.windsurfrulesMarkdown单文件Cline.clinerulesMarkdown支持目录GitHub Copilot.github/copilot-instructions.mdMarkdown单文件自建Agent自定义自定义建议参考上述格式不管用什么工具核心内容是一样的只是存放位置不同。我建议把项目指令文件纳入版本控制这样团队每个人用的都是同一套配置。4. 资产库让AI助教有“参考答案”可抄4.1 什么是资产库为什么需要它资产库是我在配置AI助教时最看重的部分但也是最多人忽略的部分。简单说资产库就是一组高质量的代码示例和模式参考AI助教在写代码时可以“抄作业”。为什么需要资产库因为项目指令文件只能告诉AI助教“规则是什么”但规则是抽象的。比如你告诉它“API请求要统一处理错误”它可能理解成十种不同的写法。但如果你在资产库里放一个标准的API请求示例它就会照着这个模式写。我做过对比测试同一个项目没有资产库时AI助教生成的代码需要修改的概率是60%以上有了资产库之后降到20%以下。资产库是提升AI助教输出质量最有效的手段没有之一。4.2 资产库该放什么资产库不是把整个项目代码都丢进去而是精选有代表性的、体现项目最佳实践的代码片段。我通常放以下几类第一类标准CRUD示例选一个最典型的模块把它的完整实现放进去——API定义、store、组件、类型定义。这是AI助教最常需要参考的模式。// 资产库示例标准API模块 // src/api/user.ts import request from /utils/request import type { User, UserListParams, UserListResult } from /types/user export async function getUserList(params: UserListParams): PromiseUserListResult { try { const { data } await request.get(/users, { params }) return data } catch (error) { logger.error(获取用户列表失败, error) throw new BusinessError(获取用户列表失败) } }第二类组件模板放一个结构完整的组件示例包含props定义、emit定义、样式组织方式。第三类工具函数示例放几个典型的工具函数展示项目的函数风格、错误处理方式、注释格式。第四类类型定义示例放几个典型的类型定义展示项目的类型组织方式。第五类测试用例示例如果项目有测试放一个标准的测试文件展示测试的组织方式和断言风格。4.3 资产库的组织方式资产库的组织方式直接影响AI助教的使用效率。我的做法是按功能维度组织而不是按文件类型.assets/ ├── patterns/ │ ├── api-crud.md # API增删改查模式 │ ├── component-basic.md # 基础组件模式 │ ├── component-form.md # 表单组件模式 │ ├── store-module.md # Store模块模式 │ └── error-handling.md # 错误处理模式 ├── snippets/ │ ├── use-pagination.ts # 分页逻辑 │ ├── use-dialog.ts # 弹窗逻辑 │ └── use-table.ts # 表格逻辑 └── types/ ├── api-types.ts # API类型定义 └── common-types.ts # 通用类型定义每个文件里放一个完整的、可直接参考的示例。文件开头用注释说明这个模式的适用场景和关键要点。4.4 资产库的维护策略资产库不是建一次就完事了需要持续维护。我的维护策略是每次发现AI助教写错了某个模式就把正确的写法补充到资产库每次项目引入新的技术方案就更新对应的资产库文件每月review一次资产库删除过时的示例这样资产库会越来越精准AI助教的表现也会越来越好。我现在的项目里资产库已经积累了30多个模式文件AI助教生成代码的可用率稳定在85%以上。5. 提示词工程和AI助教高效沟通的方法5.1 提示词不是越长越好很多人写提示词的习惯是把所有能想到的要求都写进去觉得写得越多AI助教越听话。实际上恰恰相反——过长的提示词会让AI助教“注意力涣散”它可能记住了后面的要求却忘了前面的。我的经验是单次任务的提示词控制在200字以内把最关键的3-5个要求说清楚就行。其他规则应该放在项目指令文件里而不是每次都在提示词里重复。5.2 任务型提示词的结构一个好的任务型提示词应该包含四个部分第一部分任务描述用一句话说清楚要做什么。比如“在用户列表页面添加一个批量删除功能”。第二部分具体要求列出3-5个关键要求。比如选中多行后显示删除按钮删除前弹出确认框删除成功后刷新列表并提示第三部分参考指引告诉AI助教可以参考资产库里的哪个模式。比如“参考.assets/patterns/api-crud.md中的删除接口写法”。第四部分约束条件说明不能做什么。比如“不要修改现有的分页逻辑”。这样结构的提示词AI助教能快速抓住重点输出质量明显更高。5.3 不同场景的提示词模板我整理了几个常用场景的提示词模板可以直接套用场景一新增功能任务在[模块名]中新增[功能名] 要求 1. [具体要求1] 2. [具体要求2] 3. [具体要求3] 参考.assets/patterns/[相关模式].md 约束不要修改[不能动的部分]场景二修复Bug任务修复[模块名]中的[问题描述] 现象[具体表现] 期望[期望行为] 参考.assets/patterns/[相关模式].md 约束只修改[相关文件]不要动其他文件场景三重构代码任务重构[文件名]目标是[重构目标] 要求 1. 保持现有功能不变 2. [具体重构要求] 3. 重构后更新相关测试 参考.assets/patterns/[相关模式].md 约束不要改变对外接口场景四代码审查任务审查[文件名]的代码质量 检查项 1. 是否符合项目代码规范 2. 是否有潜在的错误处理遗漏 3. 是否有性能问题 4. 是否有安全隐患 输出按严重程度列出问题每个问题给出修改建议5.4 提示词的迭代优化提示词不是写一次就固定的需要根据AI助教的表现持续优化。我的做法是记录每次AI助教理解偏差的情况分析是提示词哪里没说清楚把反复出现的问题固化到项目指令文件里而不是每次都在提示词里说定期整理提示词模板把验证有效的模板保存下来复用我现在的项目里有一个提示词模板库积累了20多个场景的模板新任务直接套用效率提升非常明显。6. 实操从零配置一个AI助教6.1 配置前的准备工作在开始配置之前需要先梳理清楚项目的现状。我通常会做以下几件事第一件梳理技术栈把项目用到的所有技术、工具、库列出来包括版本号。这一步看起来简单但很多人其实说不清楚自己项目到底用了什么。比如“用了Vue”和“用了Vue3.4 TypeScript5.3 Vite5.0 Pinia2.1”是完全不同的信息量。第二件梳理目录结构把项目的目录结构画出来标注每个目录的职责。如果目录结构混乱建议先整理再配置AI助教——因为AI助教是照着你的结构来理解项目的结构乱它也会乱。第三件梳理代码规范把项目的代码规范整理成文档。如果之前没有成文的规范就从现有代码中总结——看看大家实际是怎么写的把共识部分提炼出来。第四件挑选资产库示例从现有代码中挑选出最规范的模块作为资产库示例。挑选标准是代码质量高、有代表性、覆盖核心模式。6.2 编写项目指令文件准备工作做完之后开始写项目指令文件。我通常按以下顺序写先写项目概览技术栈、版本、包管理器再写目录结构每个目录的职责然后写代码规范命名、格式、错误处理最后写禁止事项不能做的事写完之后自己先读一遍检查是否有模糊的地方。判断标准是如果一个新人只看这份文件能不能写出符合项目要求的代码如果答案是否定的说明还需要补充细节。6.3 搭建资产库资产库的搭建分三步第一步确定需要哪些模式根据项目特点列出最常用的代码模式。一般包括API请求、组件定义、状态管理、表单处理、列表分页、错误处理、权限控制等。第二步为每个模式挑选最佳示例从现有代码中挑选最规范的实现或者如果没有现成的就自己写一个标准示例。第三步为每个示例写说明在每个示例文件开头用注释说明这个模式的适用场景、关键要点、常见错误。6.4 配置验证与调优配置完成之后需要验证效果。我的验证方法是测试一基础任务测试给AI助教一个简单的任务比如“新增一个用户查询接口”看它是否能按照项目规范完成。测试二复杂任务测试给一个涉及多个模块的任务比如“在订单列表页添加导出功能”看它是否能正确协调多个模块。测试三边界测试给一个模糊的需求看它是否会主动追问而不是瞎猜。测试四禁止事项测试故意让它做禁止事项里的事看它是否会拒绝。根据测试结果调整项目指令文件和资产库。我通常需要迭代2-3轮才能达到稳定效果。7. 常见问题与排查技巧7.1 AI助教不遵守项目指令怎么办这是最常见的问题。AI助教明明看到了项目指令文件但写代码时就是不遵守。排查思路如下首先检查指令是否明确。“使用TypeScript”不如“所有新文件必须使用TypeScript禁止使用JavaScript”。模糊的指令AI助教容易忽略。其次检查指令是否冲突。如果项目指令文件里同时写了“保持代码简洁”和“所有函数必须有完整注释”AI助教就不知道该听哪个。指令之间不能有矛盾。然后检查指令数量。如果指令超过30条AI助教可能记不住。精简到20条以内把次要规则移到资产库里。最后检查指令位置。有些工具对指令文件的位置有要求放错了位置就不会被加载。确认指令文件在工具指定的位置。7.2 AI助教总是修改不该改的文件这个问题通常是因为没有明确“操作边界”。解决方法是在项目指令文件里加一条## 文件操作规则 - 修改任何文件前先说明要修改哪些文件、为什么修改 - 只修改与当前任务直接相关的文件 - 禁止修改配置文件package.json、vite.config.ts等除非明确要求 - 禁止删除文件除非明确要求另外在提示词里也要明确约束“只修改src/views/user/目录下的文件不要动其他目录”。7.3 AI助教生成的代码风格不一致风格不一致通常是因为资产库不够完善。AI助教没有参考标准就会按自己的理解写。解决方法是补充资产库覆盖所有常用模式在项目指令文件里明确代码风格的关键点在提示词里指定参考资产库的哪个文件我实测下来资产库覆盖率达到80%以上时风格不一致的问题基本消失。7.4 AI助教回答太长或太短回答长度的问题可以通过提示词控制。在提示词里明确说“只输出修改的代码不要解释”“用不超过100字说明修改内容”“详细解释每一步的原因”如果AI助教总是回答太长可以在项目指令文件里加一条默认的输出规范“默认只输出代码和必要的说明不要输出大段解释。如果需要详细解释会在提示词中说明。”7.5 常见问题速查表问题可能原因解决方法不遵守项目指令指令模糊/冲突/过多精简指令用“必须/禁止”修改不该改的文件操作边界不清晰明确文件操作规则代码风格不一致资产库不完善补充资产库示例回答太长/太短输出规范不明确在指令和提示词中明确理解偏差提示词结构不清晰用四段式提示词结构重复犯错没有固化规则把问题补充到指令文件上下文丢失会话太长定期开新会话重要信息放指令文件7.6 几个我踩过的坑坑一指令文件写成了“愿望清单”。早期我写了很多“希望”“建议”“尽量”结果AI助教基本不执行。后来全部改成“必须”“禁止”执行率大幅提升。坑二资产库放了太多示例。一开始我把整个项目代码都放进资产库结果AI助教反而不知道该参考哪个。后来精简到只放核心模式效果反而更好。坑三提示词写得太长。有一次我写了一个500字的提示词结果AI助教只记住了最后几句。后来控制在200字以内重点突出效果好很多。坑四没有定期维护。项目迭代了几轮之后资产库里的示例已经过时了但AI助教还在参考旧示例。后来养成了每月review的习惯问题才解决。坑五忽略了工具差异。不同AI编程工具对指令文件的加载方式不同我一开始用Cursor的配置直接放到Windsurf里结果部分规则没生效。后来针对每个工具单独适配才稳定下来。8. 进阶让AI助教越用越聪明8.1 建立反馈循环AI助教不是配置一次就完事的需要建立反馈循环。我的做法是每次AI助教犯错记录下错误类型和场景分析是配置问题还是提示词问题把解决方案固化到配置或资产库中下次遇到类似场景时验证是否解决这样循环几轮之后AI助教的表现会越来越稳定。我现在的项目里AI助教生成代码的一次通过率从最初的30%提升到了80%以上。8.2 项目指令文件的版本管理项目指令文件应该纳入版本控制和代码一起管理。每次修改都提交这样可以追溯每次修改的原因和效果。我通常会在提交信息里写清楚这次修改解决了什么问题预期效果是什么。过一段时间回头看能清楚看到配置的演进过程。8.3 团队协作中的配置共享如果是团队使用项目指令文件和资产库应该作为团队共享资产。我的做法是项目指令文件放在项目根目录纳入版本控制资产库放在.assets目录同样纳入版本控制定期组织团队review配置收集大家的反馈新人入职时配置文件和项目代码一起交接这样能保证团队每个人用的都是同一套配置AI助教的输出风格也保持一致。8.4 持续优化的几个方向配置AI助教是一个持续优化的过程。我目前重点优化的方向有方向一更精准的资产库。不断补充新的模式删除过时的示例让资产库始终反映项目的最佳实践。方向二更智能的提示词模板。积累更多场景的提示词模板让新任务可以直接套用。方向三更细粒度的规则。把大规则拆成更细的、可验证的小规则提升执行率。方向四更好的上下文管理。研究如何在有限的上下文窗口里放入最有效的信息。这个方向没有终点但每优化一点AI助教的表现就会好一点。我个人的体会是配置AI助教的投入产出比非常高——花几个小时优化配置能节省后面几十个小时的返工时间。最后分享一个小技巧如果你不确定某条规则该不该写进项目指令文件就问自己一个问题——“如果一个新人不知道这条规则他会不会犯错”如果答案是会那就写进去。如果答案是“无所谓”那就不写。这个判断标准帮我精简了很多冗余规则让指令文件始终保持精炼有效。