1. 为什么“耳聪目明”是AI助教的第一道门槛做过AI助教类项目的人都有一个共同体会模型本身的能力其实不是瓶颈真正决定体验上限的是它能不能准确“看见”你的项目结构、理解你的业务上下文、记住你定过的规矩。我见过太多团队花大价钱调模型结果AI助教连项目里哪个目录放的是接口、哪个文件是配置文件都搞不清楚回答全靠猜——这不是模型不行是项目配置没做到位。所谓“耳聪”指的是AI能听到、读到项目里的关键信息目录结构、依赖清单、接口定义、数据库表结构、环境变量约定。所谓“目明”指的是AI能看清你的意图边界哪些事能做、哪些事不能碰、输出格式长什么样、遇到歧义时该问谁。这两件事合起来就是一套完整的项目配置体系核心抓手有三个项目指令、资产库、提示词工程。这套东西适合谁如果你正在用Cursor、通义灵码、CodeBuddy、扣子这类工具搭AI助教或者你在团队里负责“让AI真正融入研发流程”那这篇内容就是给你写的。它不聊虚的只讲怎么把项目配置成AI一进来就能干活的状态。下面我按“整体设计—核心细节—实操落地—问题排查”四块展开每一块都配上我实际踩过的坑和验证过的参数。2. 整体设计与思路拆解AI助教的“感官系统”怎么搭2.1 从“通用助手”到“项目专属助教”的认知转变大部分人配AI助教的第一步就错了直接开一个对话框把项目代码往里一贴然后问“帮我看看这段有什么问题”。这种做法在玩具项目里能跑通一旦项目超过50个文件AI就开始胡言乱语。原因很简单——大模型的上下文窗口是有限的你塞进去的东西越多它越抓不住重点最后变成“什么都看了一点什么都没看透”。正确的思路是把AI助教当成一个新入职的同事。新同事入职第一天你不会让他把公司所有代码读一遍而是给他一份《项目入门手册》——告诉他项目是干什么的、目录怎么分、代码规范是什么、遇到问题找谁。这份手册就是我们要配置的项目指令和资产库。我试过一个很直观的对比同一个模型不做任何配置直接问“这个项目的登录逻辑在哪”它给出的答案准确率大概30%配好项目指令和资产库之后同样的提问准确率能到85%以上。差距不在模型在配置。2.2 三层配置架构指令层、资产层、提示词层我把整套配置拆成三层每层解决不同的问题互不干扰又互相支撑。指令层解决“AI该遵守什么规矩”。它是一组常驻的系统级约束比如“回答必须用中文”“代码必须符合PEP8”“不确定时要主动提问而不是编造”。这一层的特点是稳定一旦定好整个项目周期内基本不动。资产层解决“AI该知道什么事实”。它包括项目结构说明、接口文档、数据库Schema、术语表、常见问题库。这一层是动态的项目迭代时资产库要跟着更新。资产库的质量直接决定AI回答的准确度。提示词层解决“AI该怎么完成具体任务”。它是针对单次交互的指令比如“帮我review这个函数”“根据这个需求生成测试用例”。提示词层最灵活但也最容易被忽视——很多人以为提示词就是随便写一句话实际上好的提示词需要包含角色、任务、约束、输出格式、示例五个要素。三层的关系可以这样理解指令层是宪法资产层是法律条文提示词层是具体案件的判决书。宪法不动法律条文定期修订判决书一案一写。2.3 为什么不用“一把梭”的大提示词有人会问为什么不把所有东西写进一个大提示词里一次发给AI我早期也这么干过结果是维护灾难。一个3000字的大提示词改一个标点都要重新测试全流程而且不同任务需要的上下文不一样大提示词里80%的内容对当前任务是噪音。拆成三层之后好处很明显指令层可以复用资产层可以按需检索提示词层可以针对任务定制。更重要的是当AI回答出错时你能快速定位是哪一层的问题——是指令没定清楚还是资产库缺了信息还是提示词写得有歧义。这种可调试性是“一把梭”方案给不了的。3. 核心细节解析与实操要点把配置落到文件里3.1 项目指令怎么写才不空泛项目指令最常见的毛病是写成了口号“请认真回答”“请保证代码质量”“请遵守规范”。这种指令对AI来说等于没说因为它不知道“认真”的标准是什么、“质量”指哪些维度。有效的项目指令必须满足三个条件可执行、可验证、有边界。我拿一个实际项目的指令片段举例# 项目指令 ## 角色定义 你是本项目的AI助教服务对象是3-5人的后端研发小组。 你的知识边界限于本仓库代码和资产库文档超出范围的问题必须明确说“这超出我的知识范围”。 ## 回答规范 1. 所有代码示例必须标注语言类型Python代码遵循PEP8Java代码遵循阿里巴巴规范。 2. 涉及数据库操作时必须显式写出事务边界。 3. 不确定的接口参数必须列出“需要确认”清单禁止编造参数名。 4. 回答长度控制在500字以内超过时先给结论再给细节。 ## 禁止事项 - 禁止建议使用项目依赖清单之外的第三方库。 - 禁止修改资产库中标记为“已冻结”的接口定义。 - 禁止在未确认环境的情况下给出部署命令。你看每一条都能被检验。“回答控制在500字以内”可以数“禁止建议清单外的库”可以查。这种指令AI执行起来才有抓手。提示项目指令不要超过800字。超过之后AI的注意力会被稀释反而记不住重点。如果确实有很多规矩把细节挪到资产库里指令层只留最核心的10条以内。3.2 资产库的四种必备文件资产库不是把项目文档一股脑塞进去而是要精选四类文件每类解决特定问题。第一类是项目地图。用一棵目录树加注释的方式告诉AI每个目录是干什么的。比如src/ api/ # 对外HTTP接口每个文件对应一个业务域 service/ # 业务逻辑层禁止直接操作数据库 dao/ # 数据访问层所有SQL写在这里 config/ # 环境配置敏感信息用占位符 utils/ # 通用工具新增工具前先查这里有没有现成的这棵树看起来简单但它能让AI在回答“登录逻辑在哪”时直接定位到api/auth.py和service/user_service.py而不是在几百个文件里瞎找。第二类是接口契约。把项目对外暴露的接口用结构化格式写清楚包括路径、方法、入参、出参、错误码。我习惯用YAML写因为AI读YAML比读散文准确得多- path: /api/v1/user/login method: POST params: username: string, 必填, 4-20位 password: string, 必填, 加密传输 response: code: 0成功 1001用户不存在 1002密码错误 data: {token: string, expire: int}第三类是术语表。每个项目都有自己的黑话比如“工单”指的是什么、“渠道”包含哪些、“冻结”是什么状态。术语表就是给AI的词典避免它用通用理解去套项目特定概念。第四类是常见问题库。把团队里反复被问的问题整理成问答对比如“本地启动报端口占用怎么办”“测试环境数据库连不上怎么排查”。这部分内容AI可以直接复用减少重复劳动。3.3 提示词工程的五个必备要素提示词层是最容易出效果也最容易翻车的地方。我总结了一个五要素模板缺一个都会导致输出质量下降。角色告诉AI以什么身份回答。“你是一名资深后端工程师”比“你是一个助手”效果好得多因为前者激活了模型里关于工程实践的知识。任务一句话说清楚要做什么。“帮我review这段代码”太模糊“检查这段代码的空指针风险、SQL注入风险和事务边界问题”就具体得多。约束明确不能做什么。“不要重构代码结构”“不要引入新依赖”“保持原有命名风格”。输出格式告诉AI结果长什么样。“用表格列出问题、位置、严重程度、修改建议”比“给我一些建议”可控得多。示例给一个输入输出的样例。这一条最容易被省略但效果最明显。一个示例能让AI的输出准确率提升一大截因为它有了模仿对象。把这五个要素串起来一个完整的提示词大概长这样角色你是一名有10年经验的后端工程师熟悉Python和MySQL。 任务检查下面这段用户查询代码的性能问题。 约束不要重写代码只指出问题不要建议更换ORM框架。 输出格式表格列为[问题类型, 代码行号, 问题描述, 优化建议]。 示例 | 问题类型 | 行号 | 问题描述 | 优化建议 | | 索引缺失 | 12 | user_id字段无索引 | 添加联合索引 | 代码 此处粘贴代码3.4 配置文件的组织方式三层配置最终要落到文件上。我的习惯是在项目根目录建一个.ai-assistant/目录里面放.ai-assistant/ instructions.md # 项目指令 assets/ project-map.md # 项目地图 api-contract.yaml # 接口契约 glossary.md # 术语表 faq.md # 常见问题 prompts/ code-review.md # 代码审查提示词 test-gen.md # 测试生成提示词 bug-triage.md # 问题排查提示词这样组织的好处是指令和资产分离资产和提示词分离每类文件职责单一。当AI助教工具支持读取本地文件时直接指向这个目录即可不支持时也可以手动把对应文件内容贴进对话。4. 实操过程与核心环节实现从零配一套能用的AI助教4.1 第一步梳理项目结构并生成项目地图不要手动写项目地图容易漏。我的做法是先用脚本生成目录树再人工加注释。# 生成三层目录树排除无关目录 find . -maxdepth 3 -type d \ -not -path ./.git* \ -not -path ./node_modules* \ -not -path ./venv* \ -not -path ./__pycache__* \ | sort拿到目录树后逐个目录问自己三个问题这个目录放什么、谁负责维护、AI需要知道它的什么信息。把答案写成注释项目地图就成型了。这里有个经验项目地图不要超过100行。超过之后AI读取效率下降而且维护成本高。如果项目确实很大按业务域拆成多份地图让AI按需读取。4.2 第二步从代码中提取接口契约手动整理接口契约是苦力活但可以半自动化。如果项目用了Swagger或OpenAPI直接导出YAML即可。如果没有可以用正则从代码里提取路由定义再人工补全参数说明。我写过一个简单的提取脚本思路是扫描app.route或RequestMapping这类注解把路径和方法抓出来import re def extract_routes(file_path): pattern r(?:app\.route|RequestMapping)\([\](.?)[\] routes [] with open(file_path, r, encodingutf-8) as f: for i, line in enumerate(f, 1): match re.search(pattern, line) if match: routes.append({path: match.group(1), line: i}) return routes抓出来的只是骨架参数和返回值还得人工补。但这一步能省掉大量翻代码的时间尤其是接口数量上百的项目。注意接口契约里的错误码一定要写全。AI在生成调用代码时如果不知道错误码含义会编造处理逻辑。把错误码写清楚AI生成的异常处理代码才能直接用。4.3 第三步编写项目指令并做A/B测试项目指令写完不能直接用要做对比测试。我的方法是准备10个典型问题分别在“无指令”和“有指令”两种情况下问AI对比回答质量。典型问题包括这个项目的登录流程是怎样的新增一个接口需要改哪些文件数据库连接配置在哪个文件这个报错可能是什么原因帮我写一个符合项目规范的Service方法测试时记录两个指标准确率回答是否正确和规范率回答是否符合项目约定。我实测下来配好指令后准确率从40%左右提升到80%规范率从几乎为零提升到90%以上。如果某个问题两种情况下都答不好说明资产库缺信息回去补资产库。如果答对了但格式不对说明指令里的输出规范没写清楚回去改指令。这个迭代过程通常要跑两三轮。4.4 第四步搭建提示词模板库提示词不要每次现写要沉淀成模板。我按任务类型建了几个模板每个模板固定五要素结构只留变量部分让使用者填。以代码审查模板为例角色你是一名{语言}资深工程师熟悉{框架}最佳实践。 任务审查下面的代码重点检查{检查重点}。 约束 - 不重构代码结构 - 不引入新依赖 - 保持现有命名风格 输出格式表格列为[问题类型, 行号, 严重程度, 问题描述, 修改建议] 严重程度定义高会导致线上故障中影响可维护性低风格问题 代码 {代码内容}使用时只需替换{语言}、{框架}、{检查重点}、{代码内容}四个变量。这样既保证了输出质量稳定又降低了使用门槛。4.5 第五步建立资产库更新机制资产库最大的问题是会过期。接口改了、目录调整了、术语变了资产库不更新AI就会给出过时答案。我的做法是设一个“资产库检查”环节挂在每次发版流程里。具体操作在项目的CI流程里加一个检查项对比接口契约文件和实际代码里的路由定义不一致就报警。术语表和FAQ则靠人工维护每两周review一次把新出现的黑话和重复问题补进去。这个机制听起来麻烦但比AI给出错误答案导致的返工要划算得多。我算过一笔账资产库维护每周花1小时但能减少大约5小时的AI纠错和人工复核时间投入产出比很划算。5. 常见问题与排查技巧实录5.1 AI回答“我不知道”时怎么排查AI说“我不知道”通常有三种原因排查顺序如下。第一检查资产库是否覆盖了这个问题。如果问的是“支付回调怎么处理”而资产库里只有接口契约没有业务流程说明AI自然答不上来。解决办法是补一份业务流程文档。第二检查项目指令是否限制了AI的知识范围。如果指令里写了“知识边界限于本仓库代码”而问题涉及外部系统交互AI会主动说不知道。这时候要么放宽边界要么把外部系统的信息补进资产库。第三检查提示词是否太模糊。把“支付回调怎么处理”改成“根据资产库中的支付接口契约说明回调接口的入参校验逻辑和幂等处理方式”AI就能找到对应内容。5.2 AI编造接口参数怎么防编造参数是AI助教最危险的行为因为开发者可能直接复制使用。防编造的核心是让AI在不确定时必须提问。在项目指令里加一条硬约束“当接口参数、字段名、错误码不在资产库中时必须列出‘需要确认’清单禁止自行推断。”同时在提示词里加一句“如果信息不足先输出需要确认的问题不要直接给代码。”我实测下来加了这两条之后编造参数的情况从经常出现降到偶尔出现。剩下的偶尔情况通常是资产库里有相似但不完全匹配的内容AI做了错误关联。解决办法是在资产库里给每个接口加唯一标识提示词里要求AI引用标识。5.3 上下文太长导致AI“失忆”怎么办项目大了之后资产库内容可能超过模型的上下文窗口。这时候AI会出现“前面说的后面忘”的情况。解决办法是分层检索不要一次性把所有资产塞进去。具体做法把资产库按业务域拆成多个文件提示词里指定本次任务需要读取哪些文件。比如问登录相关的问题只加载auth域的接口契约和术语不加载订单域的。如果工具支持向量检索把资产库做成向量库让AI按需检索相关片段。如果不支持就手动在提示词里写“本次任务参考以下文件xxx.yaml、yyy.md”。5.4 常见问题速查表现象可能原因排查动作解决方式AI答非所问提示词任务描述模糊检查提示词是否有明确任务按五要素重写提示词AI编造参数资产库缺接口定义对比资产库和实际代码补全接口契约并加确认约束AI回答过时资产库未更新检查资产库版本建立发版同步机制AI输出格式乱指令缺输出规范检查指令是否有格式要求在指令和提示词里都加格式约束AI忽略项目规范指令太笼统检查指令是否可验证把规范改成可检验的条目AI回答太长缺长度约束检查指令是否有长度限制加“500字以内”等硬约束AI不敢回答知识边界太窄检查指令的边界定义放宽边界或补充资产库5.5 几个我踩过的坑坑一指令写太多AI记不住。我一开始把项目所有规范都写进指令结果AI只记住了前几条。后来精简到10条以内效果反而更好。指令是宪法不是法典只写最核心的原则。坑二资产库用散文写AI读不懂。我早期用自然语言描述接口AI经常理解错参数类型。改成YAML结构化格式后准确率明显提升。AI对结构化数据的理解能力远强于散文。坑三提示词模板不写示例。我以为把要求写清楚就够了结果AI的输出格式每次都不一样。加了一个示例之后输出格式立刻稳定了。示例是提示词里性价比最高的部分。坑四资产库更新靠自觉。一开始靠开发者自觉更新结果三个月后资产库和代码完全对不上。后来把检查挂到CI流程里才解决了这个问题。机制比自觉可靠。坑五所有任务用同一个提示词。代码审查和测试生成用同一个提示词结果两边效果都不好。后来按任务类型拆分模板每个模板针对性地优化效果才上来。6. 让AI助教持续“耳聪目明”的维护心得配好一套AI助教不是终点而是起点。项目在变AI助教的配置也得跟着变。我现在的习惯是每两周做一次“配置体检”翻一遍最近AI回答错误的问题看是资产库过期了还是提示词有歧义然后针对性修复。还有一个很实用的技巧把AI回答错误的问题收集起来作为资产库的“负样本”。比如AI把“工单”理解成了“客服工单”那就在术语表里明确写“工单在本项目中特指研发任务单不是客服工单”。这种负样本比正样本更能提升AI的准确率因为它直接堵住了AI的错误联想路径。另外项目指令和提示词模板要版本化管理跟代码一起提交到仓库。这样每次配置变更都有记录出问题能回滚新人也能看到配置的演进过程。我见过太多团队把AI配置放在某个人电脑的本地文件里人一走配置就丢了非常可惜。最后分享一个判断配置是否到位的标准新入职的开发者拿着你的AI助教能不能在不问任何人的情况下完成一个简单需求。如果能说明配置到位了如果不能缺什么补什么。这个标准比任何指标都直观。
AI助教项目配置实战：项目指令、资产库与提示词工程
1. 为什么“耳聪目明”是AI助教的第一道门槛做过AI助教类项目的人都有一个共同体会模型本身的能力其实不是瓶颈真正决定体验上限的是它能不能准确“看见”你的项目结构、理解你的业务上下文、记住你定过的规矩。我见过太多团队花大价钱调模型结果AI助教连项目里哪个目录放的是接口、哪个文件是配置文件都搞不清楚回答全靠猜——这不是模型不行是项目配置没做到位。所谓“耳聪”指的是AI能听到、读到项目里的关键信息目录结构、依赖清单、接口定义、数据库表结构、环境变量约定。所谓“目明”指的是AI能看清你的意图边界哪些事能做、哪些事不能碰、输出格式长什么样、遇到歧义时该问谁。这两件事合起来就是一套完整的项目配置体系核心抓手有三个项目指令、资产库、提示词工程。这套东西适合谁如果你正在用Cursor、通义灵码、CodeBuddy、扣子这类工具搭AI助教或者你在团队里负责“让AI真正融入研发流程”那这篇内容就是给你写的。它不聊虚的只讲怎么把项目配置成AI一进来就能干活的状态。下面我按“整体设计—核心细节—实操落地—问题排查”四块展开每一块都配上我实际踩过的坑和验证过的参数。2. 整体设计与思路拆解AI助教的“感官系统”怎么搭2.1 从“通用助手”到“项目专属助教”的认知转变大部分人配AI助教的第一步就错了直接开一个对话框把项目代码往里一贴然后问“帮我看看这段有什么问题”。这种做法在玩具项目里能跑通一旦项目超过50个文件AI就开始胡言乱语。原因很简单——大模型的上下文窗口是有限的你塞进去的东西越多它越抓不住重点最后变成“什么都看了一点什么都没看透”。正确的思路是把AI助教当成一个新入职的同事。新同事入职第一天你不会让他把公司所有代码读一遍而是给他一份《项目入门手册》——告诉他项目是干什么的、目录怎么分、代码规范是什么、遇到问题找谁。这份手册就是我们要配置的项目指令和资产库。我试过一个很直观的对比同一个模型不做任何配置直接问“这个项目的登录逻辑在哪”它给出的答案准确率大概30%配好项目指令和资产库之后同样的提问准确率能到85%以上。差距不在模型在配置。2.2 三层配置架构指令层、资产层、提示词层我把整套配置拆成三层每层解决不同的问题互不干扰又互相支撑。指令层解决“AI该遵守什么规矩”。它是一组常驻的系统级约束比如“回答必须用中文”“代码必须符合PEP8”“不确定时要主动提问而不是编造”。这一层的特点是稳定一旦定好整个项目周期内基本不动。资产层解决“AI该知道什么事实”。它包括项目结构说明、接口文档、数据库Schema、术语表、常见问题库。这一层是动态的项目迭代时资产库要跟着更新。资产库的质量直接决定AI回答的准确度。提示词层解决“AI该怎么完成具体任务”。它是针对单次交互的指令比如“帮我review这个函数”“根据这个需求生成测试用例”。提示词层最灵活但也最容易被忽视——很多人以为提示词就是随便写一句话实际上好的提示词需要包含角色、任务、约束、输出格式、示例五个要素。三层的关系可以这样理解指令层是宪法资产层是法律条文提示词层是具体案件的判决书。宪法不动法律条文定期修订判决书一案一写。2.3 为什么不用“一把梭”的大提示词有人会问为什么不把所有东西写进一个大提示词里一次发给AI我早期也这么干过结果是维护灾难。一个3000字的大提示词改一个标点都要重新测试全流程而且不同任务需要的上下文不一样大提示词里80%的内容对当前任务是噪音。拆成三层之后好处很明显指令层可以复用资产层可以按需检索提示词层可以针对任务定制。更重要的是当AI回答出错时你能快速定位是哪一层的问题——是指令没定清楚还是资产库缺了信息还是提示词写得有歧义。这种可调试性是“一把梭”方案给不了的。3. 核心细节解析与实操要点把配置落到文件里3.1 项目指令怎么写才不空泛项目指令最常见的毛病是写成了口号“请认真回答”“请保证代码质量”“请遵守规范”。这种指令对AI来说等于没说因为它不知道“认真”的标准是什么、“质量”指哪些维度。有效的项目指令必须满足三个条件可执行、可验证、有边界。我拿一个实际项目的指令片段举例# 项目指令 ## 角色定义 你是本项目的AI助教服务对象是3-5人的后端研发小组。 你的知识边界限于本仓库代码和资产库文档超出范围的问题必须明确说“这超出我的知识范围”。 ## 回答规范 1. 所有代码示例必须标注语言类型Python代码遵循PEP8Java代码遵循阿里巴巴规范。 2. 涉及数据库操作时必须显式写出事务边界。 3. 不确定的接口参数必须列出“需要确认”清单禁止编造参数名。 4. 回答长度控制在500字以内超过时先给结论再给细节。 ## 禁止事项 - 禁止建议使用项目依赖清单之外的第三方库。 - 禁止修改资产库中标记为“已冻结”的接口定义。 - 禁止在未确认环境的情况下给出部署命令。你看每一条都能被检验。“回答控制在500字以内”可以数“禁止建议清单外的库”可以查。这种指令AI执行起来才有抓手。提示项目指令不要超过800字。超过之后AI的注意力会被稀释反而记不住重点。如果确实有很多规矩把细节挪到资产库里指令层只留最核心的10条以内。3.2 资产库的四种必备文件资产库不是把项目文档一股脑塞进去而是要精选四类文件每类解决特定问题。第一类是项目地图。用一棵目录树加注释的方式告诉AI每个目录是干什么的。比如src/ api/ # 对外HTTP接口每个文件对应一个业务域 service/ # 业务逻辑层禁止直接操作数据库 dao/ # 数据访问层所有SQL写在这里 config/ # 环境配置敏感信息用占位符 utils/ # 通用工具新增工具前先查这里有没有现成的这棵树看起来简单但它能让AI在回答“登录逻辑在哪”时直接定位到api/auth.py和service/user_service.py而不是在几百个文件里瞎找。第二类是接口契约。把项目对外暴露的接口用结构化格式写清楚包括路径、方法、入参、出参、错误码。我习惯用YAML写因为AI读YAML比读散文准确得多- path: /api/v1/user/login method: POST params: username: string, 必填, 4-20位 password: string, 必填, 加密传输 response: code: 0成功 1001用户不存在 1002密码错误 data: {token: string, expire: int}第三类是术语表。每个项目都有自己的黑话比如“工单”指的是什么、“渠道”包含哪些、“冻结”是什么状态。术语表就是给AI的词典避免它用通用理解去套项目特定概念。第四类是常见问题库。把团队里反复被问的问题整理成问答对比如“本地启动报端口占用怎么办”“测试环境数据库连不上怎么排查”。这部分内容AI可以直接复用减少重复劳动。3.3 提示词工程的五个必备要素提示词层是最容易出效果也最容易翻车的地方。我总结了一个五要素模板缺一个都会导致输出质量下降。角色告诉AI以什么身份回答。“你是一名资深后端工程师”比“你是一个助手”效果好得多因为前者激活了模型里关于工程实践的知识。任务一句话说清楚要做什么。“帮我review这段代码”太模糊“检查这段代码的空指针风险、SQL注入风险和事务边界问题”就具体得多。约束明确不能做什么。“不要重构代码结构”“不要引入新依赖”“保持原有命名风格”。输出格式告诉AI结果长什么样。“用表格列出问题、位置、严重程度、修改建议”比“给我一些建议”可控得多。示例给一个输入输出的样例。这一条最容易被省略但效果最明显。一个示例能让AI的输出准确率提升一大截因为它有了模仿对象。把这五个要素串起来一个完整的提示词大概长这样角色你是一名有10年经验的后端工程师熟悉Python和MySQL。 任务检查下面这段用户查询代码的性能问题。 约束不要重写代码只指出问题不要建议更换ORM框架。 输出格式表格列为[问题类型, 代码行号, 问题描述, 优化建议]。 示例 | 问题类型 | 行号 | 问题描述 | 优化建议 | | 索引缺失 | 12 | user_id字段无索引 | 添加联合索引 | 代码 此处粘贴代码3.4 配置文件的组织方式三层配置最终要落到文件上。我的习惯是在项目根目录建一个.ai-assistant/目录里面放.ai-assistant/ instructions.md # 项目指令 assets/ project-map.md # 项目地图 api-contract.yaml # 接口契约 glossary.md # 术语表 faq.md # 常见问题 prompts/ code-review.md # 代码审查提示词 test-gen.md # 测试生成提示词 bug-triage.md # 问题排查提示词这样组织的好处是指令和资产分离资产和提示词分离每类文件职责单一。当AI助教工具支持读取本地文件时直接指向这个目录即可不支持时也可以手动把对应文件内容贴进对话。4. 实操过程与核心环节实现从零配一套能用的AI助教4.1 第一步梳理项目结构并生成项目地图不要手动写项目地图容易漏。我的做法是先用脚本生成目录树再人工加注释。# 生成三层目录树排除无关目录 find . -maxdepth 3 -type d \ -not -path ./.git* \ -not -path ./node_modules* \ -not -path ./venv* \ -not -path ./__pycache__* \ | sort拿到目录树后逐个目录问自己三个问题这个目录放什么、谁负责维护、AI需要知道它的什么信息。把答案写成注释项目地图就成型了。这里有个经验项目地图不要超过100行。超过之后AI读取效率下降而且维护成本高。如果项目确实很大按业务域拆成多份地图让AI按需读取。4.2 第二步从代码中提取接口契约手动整理接口契约是苦力活但可以半自动化。如果项目用了Swagger或OpenAPI直接导出YAML即可。如果没有可以用正则从代码里提取路由定义再人工补全参数说明。我写过一个简单的提取脚本思路是扫描app.route或RequestMapping这类注解把路径和方法抓出来import re def extract_routes(file_path): pattern r(?:app\.route|RequestMapping)\([\](.?)[\] routes [] with open(file_path, r, encodingutf-8) as f: for i, line in enumerate(f, 1): match re.search(pattern, line) if match: routes.append({path: match.group(1), line: i}) return routes抓出来的只是骨架参数和返回值还得人工补。但这一步能省掉大量翻代码的时间尤其是接口数量上百的项目。注意接口契约里的错误码一定要写全。AI在生成调用代码时如果不知道错误码含义会编造处理逻辑。把错误码写清楚AI生成的异常处理代码才能直接用。4.3 第三步编写项目指令并做A/B测试项目指令写完不能直接用要做对比测试。我的方法是准备10个典型问题分别在“无指令”和“有指令”两种情况下问AI对比回答质量。典型问题包括这个项目的登录流程是怎样的新增一个接口需要改哪些文件数据库连接配置在哪个文件这个报错可能是什么原因帮我写一个符合项目规范的Service方法测试时记录两个指标准确率回答是否正确和规范率回答是否符合项目约定。我实测下来配好指令后准确率从40%左右提升到80%规范率从几乎为零提升到90%以上。如果某个问题两种情况下都答不好说明资产库缺信息回去补资产库。如果答对了但格式不对说明指令里的输出规范没写清楚回去改指令。这个迭代过程通常要跑两三轮。4.4 第四步搭建提示词模板库提示词不要每次现写要沉淀成模板。我按任务类型建了几个模板每个模板固定五要素结构只留变量部分让使用者填。以代码审查模板为例角色你是一名{语言}资深工程师熟悉{框架}最佳实践。 任务审查下面的代码重点检查{检查重点}。 约束 - 不重构代码结构 - 不引入新依赖 - 保持现有命名风格 输出格式表格列为[问题类型, 行号, 严重程度, 问题描述, 修改建议] 严重程度定义高会导致线上故障中影响可维护性低风格问题 代码 {代码内容}使用时只需替换{语言}、{框架}、{检查重点}、{代码内容}四个变量。这样既保证了输出质量稳定又降低了使用门槛。4.5 第五步建立资产库更新机制资产库最大的问题是会过期。接口改了、目录调整了、术语变了资产库不更新AI就会给出过时答案。我的做法是设一个“资产库检查”环节挂在每次发版流程里。具体操作在项目的CI流程里加一个检查项对比接口契约文件和实际代码里的路由定义不一致就报警。术语表和FAQ则靠人工维护每两周review一次把新出现的黑话和重复问题补进去。这个机制听起来麻烦但比AI给出错误答案导致的返工要划算得多。我算过一笔账资产库维护每周花1小时但能减少大约5小时的AI纠错和人工复核时间投入产出比很划算。5. 常见问题与排查技巧实录5.1 AI回答“我不知道”时怎么排查AI说“我不知道”通常有三种原因排查顺序如下。第一检查资产库是否覆盖了这个问题。如果问的是“支付回调怎么处理”而资产库里只有接口契约没有业务流程说明AI自然答不上来。解决办法是补一份业务流程文档。第二检查项目指令是否限制了AI的知识范围。如果指令里写了“知识边界限于本仓库代码”而问题涉及外部系统交互AI会主动说不知道。这时候要么放宽边界要么把外部系统的信息补进资产库。第三检查提示词是否太模糊。把“支付回调怎么处理”改成“根据资产库中的支付接口契约说明回调接口的入参校验逻辑和幂等处理方式”AI就能找到对应内容。5.2 AI编造接口参数怎么防编造参数是AI助教最危险的行为因为开发者可能直接复制使用。防编造的核心是让AI在不确定时必须提问。在项目指令里加一条硬约束“当接口参数、字段名、错误码不在资产库中时必须列出‘需要确认’清单禁止自行推断。”同时在提示词里加一句“如果信息不足先输出需要确认的问题不要直接给代码。”我实测下来加了这两条之后编造参数的情况从经常出现降到偶尔出现。剩下的偶尔情况通常是资产库里有相似但不完全匹配的内容AI做了错误关联。解决办法是在资产库里给每个接口加唯一标识提示词里要求AI引用标识。5.3 上下文太长导致AI“失忆”怎么办项目大了之后资产库内容可能超过模型的上下文窗口。这时候AI会出现“前面说的后面忘”的情况。解决办法是分层检索不要一次性把所有资产塞进去。具体做法把资产库按业务域拆成多个文件提示词里指定本次任务需要读取哪些文件。比如问登录相关的问题只加载auth域的接口契约和术语不加载订单域的。如果工具支持向量检索把资产库做成向量库让AI按需检索相关片段。如果不支持就手动在提示词里写“本次任务参考以下文件xxx.yaml、yyy.md”。5.4 常见问题速查表现象可能原因排查动作解决方式AI答非所问提示词任务描述模糊检查提示词是否有明确任务按五要素重写提示词AI编造参数资产库缺接口定义对比资产库和实际代码补全接口契约并加确认约束AI回答过时资产库未更新检查资产库版本建立发版同步机制AI输出格式乱指令缺输出规范检查指令是否有格式要求在指令和提示词里都加格式约束AI忽略项目规范指令太笼统检查指令是否可验证把规范改成可检验的条目AI回答太长缺长度约束检查指令是否有长度限制加“500字以内”等硬约束AI不敢回答知识边界太窄检查指令的边界定义放宽边界或补充资产库5.5 几个我踩过的坑坑一指令写太多AI记不住。我一开始把项目所有规范都写进指令结果AI只记住了前几条。后来精简到10条以内效果反而更好。指令是宪法不是法典只写最核心的原则。坑二资产库用散文写AI读不懂。我早期用自然语言描述接口AI经常理解错参数类型。改成YAML结构化格式后准确率明显提升。AI对结构化数据的理解能力远强于散文。坑三提示词模板不写示例。我以为把要求写清楚就够了结果AI的输出格式每次都不一样。加了一个示例之后输出格式立刻稳定了。示例是提示词里性价比最高的部分。坑四资产库更新靠自觉。一开始靠开发者自觉更新结果三个月后资产库和代码完全对不上。后来把检查挂到CI流程里才解决了这个问题。机制比自觉可靠。坑五所有任务用同一个提示词。代码审查和测试生成用同一个提示词结果两边效果都不好。后来按任务类型拆分模板每个模板针对性地优化效果才上来。6. 让AI助教持续“耳聪目明”的维护心得配好一套AI助教不是终点而是起点。项目在变AI助教的配置也得跟着变。我现在的习惯是每两周做一次“配置体检”翻一遍最近AI回答错误的问题看是资产库过期了还是提示词有歧义然后针对性修复。还有一个很实用的技巧把AI回答错误的问题收集起来作为资产库的“负样本”。比如AI把“工单”理解成了“客服工单”那就在术语表里明确写“工单在本项目中特指研发任务单不是客服工单”。这种负样本比正样本更能提升AI的准确率因为它直接堵住了AI的错误联想路径。另外项目指令和提示词模板要版本化管理跟代码一起提交到仓库。这样每次配置变更都有记录出问题能回滚新人也能看到配置的演进过程。我见过太多团队把AI配置放在某个人电脑的本地文件里人一走配置就丢了非常可惜。最后分享一个判断配置是否到位的标准新入职的开发者拿着你的AI助教能不能在不问任何人的情况下完成一个简单需求。如果能说明配置到位了如果不能缺什么补什么。这个标准比任何指标都直观。