1. 为什么你的AI助教总是“答非所问”
很多人第一次给项目配AI助教，脑子里想的都是“我只要把问题丢给它，它就能像真人助教一样帮我答疑、查代码、补文档”。结果一上手就发现，它要么答得云里雾里，要么把项目里根本不存在的接口编得有模有样，要么你问东它答西，活像一个刚睡醒、耳朵还堵着的实习生。
问题出在哪？绝大多数情况下，不是模型不够聪明，而是你给它的“项目上下文”太贫瘠了。AI助教要“耳聪目明”，靠的不是一句“你是一个资深工程师”这种空泛的角色设定，而是项目配置层面的信息投喂——也就是把项目的结构、约定、资产、指令，用它能稳定理解的方式组织好，喂到它嘴边。
这一篇我就拿自己实际折腾过的一个中型后台管理系统项目当例子，把“如何配置项目，让AI助教耳聪目明”这件事从头到尾拆一遍。核心围绕四个东西：项目配置、项目指令、资产库、提示词。这四个词看着像四个独立概念，实际上是一条流水线上的四个工位，缺一个，AI助教就会在某个环节掉链子。
适合谁看？如果你正在用 Cursor、VS Code 插件、或者自建的对话式开发助手，想让它在你的项目里少说废话、多干实事，那这篇就是写给你的。哪怕你用的是最朴素的“把代码贴进对话框”的方式，里面的配置思路一样能直接用。
先说结论，省得你看到一半才反应过来：AI助教的表现上限，取决于你项目配置的信息密度和结构清晰度，而不是你提示词写得多花哨。提示词是最后一公里的导航，项目配置才是那张地图。地图是错的，导航再精准也到不了目的地。
2. 项目配置：给AI助教装上一双“看得见项目”的眼睛
2.1 项目配置到底在配什么
一提到“项目配置”，很多人第一反应是 IDE 里的 SDK 路径、Maven 依赖、Python 解释器这些。这些当然要配，但对 AI 助教来说，真正决定它“视力”好坏的，是另一层配置——项目知识的组织方式。
我把它拆成三层：
- 物理层配置：项目能不能跑起来。Python 解释器选对没有、依赖装全没有、环境变量有没有缺。这一层不解决，AI 助教给你的命令你执行了也是报错，它自己也没法通过运行结果来自我纠偏。
- 结构层配置：项目长什么样。目录树、模块划分、入口文件、配置文件位置。这一层决定 AI 助教能不能“定位”到相关代码，而不是每次都在整个仓库里瞎翻。
- 语义层配置：项目里有哪些约定。命名规范、分层规则、接口风格、错误码体系。这一层决定 AI 助教写出来的代码像不像“这个项目里的人写的”。
我见过太多人只做了物理层配置，然后抱怨 AI 助教“不懂我的项目”。你只告诉它 Python 解释器在哪，它当然只懂 Python 语法，不懂你的项目。
2.2 物理层配置：先让项目自己能跑
这一步是地基。以 Python 后台管理系统为例，我实际的做法是：
# 确认解释器版本，写进项目配置 python --version # 创建独立虚拟环境，避免污染全局 python -m venv .venv # 激活（Linux/macOS） source .venv/bin/activate # 安装依赖并锁定版本 pip install -r requirements.txt pip freeze > requirements.lock为什么要单独锁一份requirements.lock？因为 AI 助教在给你建议时，经常会说“你升级一下某个包就好了”。如果你没有锁定版本，它这个建议可能直接把项目搞崩。有了 lock 文件，你可以明确告诉它：这个项目的依赖版本是冻结的，不要建议我随意升级。
Java 项目同理。IDEA 里配置 JavaWeb 项目，SDK 版本、Tomcat 版本、Maven 的settings.xml路径，这些都要确认到位。我踩过的一个坑是：IDEA 里项目能跑，但 AI 助教给的 Maven 命令在命令行里跑不通，原因是 IDEA 用的是内置 Maven，命令行用的是系统 Maven，两者仓库路径不一致。后来我统一在项目根目录放了.mvn/maven.config，把仓库路径和配置固定下来，AI 助教给的命令才和 IDE 行为对齐。
注意：物理层配置的目标不是“能跑就行”，而是“在任何入口跑，结果都一致”。AI 助教可能通过命令行、可能通过 IDE 终端、可能通过它自己的执行环境来跑你的项目，行为不一致，它的判断就会飘。
2.3 结构层配置：让AI助教知道“东西在哪”
结构层配置的核心产物，是一份项目地图。我通常会在项目根目录放一个PROJECT_MAP.md，内容不写废话，就是目录结构加一句话说明：
project-root/ ├── src/ │ ├── api/ # 对外接口层，只做参数校验和转发 │ ├── service/ # 业务逻辑层，所有事务在这里 │ ├── dao/ # 数据访问层，只写SQL和ORM │ ├── model/ # 数据模型，与数据库表一一对应 │ └── common/ # 公共工具，禁止反向依赖上层 ├── config/ │ ├── application.yml # 主配置，环境相关项用占位符 │ └── logback.xml # 日志配置 ├── tests/ # 测试用例，按模块镜像src结构 └── docs/ # 项目文档，AI助教优先读这里这份地图看起来简单，但它解决了一个大问题：AI 助教在回答“这个功能应该写在哪”时，有了明确的依据。没有这份地图，它可能把业务逻辑写进 controller，把 SQL 写进 service，你还得手动搬。
我实测下来，加了PROJECT_MAP.md之后，AI 助教“放错文件”的概率大概从三成降到了一成以内。剩下那一成，基本是因为地图本身没更新，项目结构变了但地图没改。所以这份地图要当成代码一样维护，结构一变就改。
2.4 语义层配置：让AI助教说“项目里的话”
语义层是最容易被忽略、但收益最高的一层。它包含的东西很杂，我一般整理成一个CONVENTIONS.md：
- 命名规范：接口用
xxxApi，服务用xxxService，数据对象用xxxDO，传输对象用xxxDTO。 - 分层规则：controller 不写业务逻辑，service 不直接拼 SQL，dao 不抛业务异常。
- 接口风格：统一返回
{code, message, data}，错误码分段管理。 - 注释要求：公共方法必须有 docstring，说明参数、返回、异常。
- 禁止事项：禁止在循环里查数据库，禁止硬编码密钥，禁止吞异常。
这份文件的价值在于，它把“老员工脑子里的默契”变成了“AI 助教能读到的明文”。你不需要每次对话都重复“记得用 xxxService 命名”，它读一遍CONVENTIONS.md就记住了。
提示：
CONVENTIONS.md不要写太长，控制在 100 行以内。太长了 AI 助教抓不住重点，反而容易忽略关键几条。我的做法是只写“违反了一定会被 review 打回”的硬规则，软性的风格偏好放到提示词里按需强调。
3. 项目指令：把“临时交代”变成“永久规则”
3.1 项目指令和提示词的区别
这两个概念经常被混着用，但它们在配置体系里的位置完全不同。
提示词是你这一次对话说的话，比如“帮我写一个用户登录接口”。它是临时的、一次性的。
项目指令是你希望 AI 助教在整个项目周期里都遵守的规则，比如“所有接口必须做参数校验”。它是持久的、跨对话的。
打个比方：提示词是你对助教说的“帮我改一下这份卷子”，项目指令是你开学时就贴在墙上的“批改规范”。没有墙上的规范，你每次都得重新交代一遍，还容易漏。
在 Cursor 里，项目指令对应.cursorrules文件；在 VS Code 的 AI 插件里，可能是.github/copilot-instructions.md或者类似的约定文件；自建助手的话，就是系统提示词里那段固定的项目规则。名字不同，本质一样：把重复交代的东西固化下来。
3.2 项目指令该写什么、不该写什么
我见过两种极端。一种是项目指令写得像散文，洋洋洒洒几千字，AI 助教读完前面忘了后面。另一种是只写一句“你是一个资深工程师”，等于没写。
我的经验是，项目指令分四块写，每块控制在几句话：
# 项目指令 ## 角色 你是本项目的开发助手，熟悉 Python/FastAPI/PostgreSQL 技术栈。 ## 硬规则 - 所有接口必须校验入参，使用 pydantic 模型。 - 数据库操作必须通过 dao 层，禁止在 service 里直接写 SQL。 - 异常必须记录日志并转换为统一错误码，禁止裸抛。 ## 输出偏好 - 给代码时附上文件路径，说明放在哪一层。 - 修改现有代码时，先说明改了什么、为什么改。 - 不确定的地方明确说“不确定”，不要编造接口。 ## 禁止事项 - 不要建议升级依赖版本，本项目依赖已冻结。 - 不要生成测试数据里的真实个人信息。这四块里，“禁止事项”和“输出偏好”是最容易被忽略但最影响体验的。不写禁止事项，AI 助教就会热情地建议你升级这个、重构那个，全是噪音。不写输出偏好，它给你的代码片段就没有上下文，你还得自己猜放哪。
3.3 项目指令的维护节奏
项目指令不是写完就完事的。我的做法是：每次发现 AI 助教犯了一个“本可以避免”的错，就往项目指令里加一条。
比如有一次它把一个本该在 service 层的事务写到了 controller 里，我就在硬规则里加了一条“事务边界必须在 service 层”。又比如它老是给我用print调试，我就在输出偏好里加了“调试信息用 logging，不用 print”。
这样积累下来，项目指令会越来越贴合你的项目，AI 助教也会越来越“懂事”。这个过程有点像带新人，前两周你得反复交代，后面它上手了，你基本不用管。
注意：项目指令不要写“正确的废话”，比如“写高质量的代码”“注意性能”。这种话 AI 助教没法执行，等于占字数。要写就写可判定的规则，比如“单函数不超过 50 行”“接口响应时间目标 200ms 以内”。
4. 资产库：AI助教的“项目记忆”怎么建
4.1 什么是资产库，为什么需要它
资产库这个词听起来玄乎，说白了就是你希望 AI 助教随时能查到的项目资料集合。它可以是文档、代码片段、接口定义、数据库表结构、常见问题记录，任何你觉得“它应该知道”的东西。
为什么需要单独建一个资产库，而不是让它自己去读整个代码库？两个原因。
第一，代码库太大，它读不完也读不准。一个中型项目几万行代码，AI 助教的上下文窗口再大，也不可能每次都全量读一遍。它需要的是“按需检索”，而资产库就是那个被索引过的、结构化的知识源。
第二，很多知识不在代码里。比如“这个字段为什么这么设计”“这个接口为什么不能改”“上次这个 bug 是怎么修的”，这些都在人脑子里或者聊天记录里，代码里看不出来。资产库就是把这些隐性知识显性化。
4.2 资产库的四种核心资产
我实际维护的资产库，主要包含四类内容：
第一类：接口契约。每个对外接口的路径、方法、入参、出参、错误码，整理成结构化文档。AI 助教写调用代码或者写 mock 时，直接查这份契约，不会编造字段。
第二类：数据模型。数据库表结构、字段含义、索引、关联关系。我用一个schema.md维护，每次建表或改表就更新。AI 助教写 SQL 或 ORM 时，字段名和类型就不会错。
第三类：代码片段库。项目里反复出现的模式，比如“分页查询怎么写”“统一异常怎么抛”“日志怎么打”，整理成可复用的片段。AI 助教需要时直接引用，风格统一。
第四类：问题档案。踩过的坑、修过的 bug、排查思路，按时间或模块归档。这个最容易被忽略，但价值极高。AI 助教遇到类似问题时，能直接参考历史解法，不用从零推理。
4.3 资产库的组织方式
资产库的组织，我推荐按“检索场景”而不是“文件类型”来分。什么意思？就是不要建一个docs/文件夹把所有 md 都塞进去，而是按“AI 助教会在什么情况下查什么”来组织。
.ai-assets/ ├── api-contracts/ # 写接口调用时查 │ ├── user.md │ └── order.md ├──>[任务] 加一个按状态筛选用户的接口。 [上下文] 参考 api-contracts/user.md 的现有接口风格。 [约束] 分页用现有 pagination 模式，不要新造。 [验收] 给出文件路径和改动说明。这四段里，“上下文”和“约束”是项目配置在提示词里的投影。因为资产库和项目指令已经存在，提示词只需要“指路”，不需要“搬砖”。
对比一下没有项目配置时的提示词，你得写成这样：
你是一个资深 Python 工程师，请帮我写一个用户查询接口。 要求：用 FastAPI，入参用 pydantic 校验，返回格式是 {code, message, data}， 分页参数是 page 和 page_size，默认每页 20 条，按 status 筛选， status 取值 0/1/2，分别代表禁用/启用/待审核，SQL 用 SQLAlchemy， 事务放在 service 层，异常要记日志并转错误码，命名用 xxxService...看出区别了吗？后者把本该在项目配置里的东西，全塞进了提示词。每次都要重复，还容易漏。前者只需要说“做什么”，因为“怎么做”已经在配置里了。
5.3 提示词里的常见坑
坑一：把提示词当许愿池。写一大堆“要高质量”“要优雅”“要考虑边界”，这些词 AI 助教没法执行。要写就写具体的，比如“边界情况包括：status 为空、page 为 0、page_size 超过 100”。
坑二：一次提多个不相关的任务。“帮我加个接口，顺便把日志配置也改一下，再把那个 bug 修了。”这种提示词，AI 助教容易顾此失彼。一个提示词一个任务，做完再做下一个。
坑三：不给验收标准。只说“帮我写”，不说“写成什么样算对”。AI 助教只能猜，猜错了你还得返工。给个明确的验收点，比如“能通过现有测试”“符合 api-contracts 里的格式”，它就有了靶子。
坑四：上下文给太多。把整个文件贴进去，说“参考这个”。文件几百行，AI 助教抓不住重点。正确做法是贴关键片段，或者直接说“参考 api-contracts/user.md”，让它自己去读。
5.4 提示词的迭代思路
提示词不是一次写好的，是迭代出来的。我的做法是：同一个任务，如果 AI 助教第一次没做对，我不改代码，先改提示词，再做一次。如果改提示词能做对，说明是提示词的问题；如果改了几次还不行，说明是项目配置或资产库缺东西。
这个思路能帮你定位问题到底出在哪一层。很多人一遇到 AI 助教做错，就手动改代码，改完就过去了。下次遇到类似任务，还是错。因为你没定位到根因，也没把修复沉淀到配置里。
我自己的记录里，大概七成的问题通过改提示词解决，两成通过补资产库解决，一成通过改项目指令解决。这个比例说明，大部分“AI 助教不好用”的问题，其实是提示词没写对，而不是模型不行。
6. 实操：从零配置一个“耳聪目明”的AI助教
6.1 配置流程总览
把前面几块串起来，完整的配置流程是这样的：
- 物理层：确认项目能跑，依赖锁定，环境一致。
- 结构层：生成
PROJECT_MAP.md，写清目录职责。 - 语义层：生成
CONVENTIONS.md，写清命名、分层、接口风格。 - 项目指令：生成
.cursorrules或等价文件，写清角色、硬规则、输出偏好、禁止事项。 - 资产库：建
.ai-assets/，按检索场景组织接口契约、数据模型、代码模式、问题档案。 - 提示词：按“任务+上下文+约束+验收”四段式写，指路不搬砖。
- 迭代：每次出错，先定位是哪一层的问题，修对应层，不直接改代码。
这个流程走一遍，大概需要半天到一天。听起来不少，但这是一次性投入。后面每次开发，你都省下了反复交代、反复纠错的时间。
6.2 一个完整的配置示例
我拿一个真实的用户查询接口需求，走一遍完整流程。
需求：加一个按状态筛选用户的接口，支持分页。
第一步，查项目地图：确认接口放src/api/，业务放src/service/，数据访问放src/dao/。
第二步，查资产库：读api-contracts/user.md，确认现有接口风格是GET /api/v1/users，返回{code, message, data}，分页参数是page和page_size。读>[任务] 在现有用户接口基础上，加一个按 status 筛选的分页查询。 [上下文] 参考 api-contracts/user.md 的接口风格，参考 code-patterns/pagination.md 的分页模式。 [约束] status 可选，不传则查全部；分页参数沿用现有约定。 [验收] 给出 api、service、dao 三层的文件路径和改动说明。
第四步，AI 助教输出：它会给三层代码，命名符合规范，返回格式统一，分页模式一致。你 review 一遍，基本能用。
第五步，沉淀：如果这次有新的模式（比如 status 筛选的写法以前没有），把它加到code-patterns/里。下次类似需求，直接引用。
这个流程走下来，你会发现 AI 助教的表现和“随便问问”完全不是一个级别。它不再是那个答非所问的实习生，而是一个熟悉项目、遵守规范、能直接干活的助手。
6.3 配置效果的衡量
怎么判断你的配置到位了？我有个简单的标准：看提示词的长度。
配置到位时，提示词可以很短，因为大量信息在配置里。配置不到位时，提示词就得写得很长，还容易漏。
另一个标准是返工率。配置到位时，AI 助教给的代码，你 review 后直接用的比例高。配置不到位时，你得大改甚至重写。
我自己的项目里，配置到位后，AI 助教给的代码大概七成能直接用，两成小改，一成重写。配置不到位时，这个比例基本反过来。
注意：不要追求“十成直接用”。AI 助教是助手不是替身，你始终要做 review。配置的目标是让它“大部分时候靠谱”，而不是“永远不出错”。
7. 常见问题与排查技巧实录
7.1 AI助教答非所问，先查哪一层
答非所问是最常见的问题。排查顺序我一般是：
- 查提示词：任务说清楚了吗？上下文指对了吗？约束写了吗？
- 查资产库：它参考的资料是最新的吗？有没有过期内容？
- 查项目指令：硬规则有没有被违反？是不是指令里没写清楚？
- 查项目配置：项目地图和实际结构一致吗？约定文件更新了吗？
大部分情况下，问题在前两层。提示词写清楚、资产库更新及时，答非所问就少很多。
7.2 AI助教编造不存在的接口或字段
这是“幻觉”问题。根因通常是它没有可靠的资料可查，只能猜。
解法是补资产库。把接口契约和数据模型整理清楚，让它有据可查。同时，在项目指令里明确写“不确定的地方说不确定，不要编造”。两条一起用，幻觉会大幅减少。
我实测下来，补了接口契约后，编造字段的情况基本消失。因为以前它不知道字段叫什么，只能猜；现在它一查就知道，不用猜。
7.3 AI助教给的代码风格和项目不一致
这是语义层配置缺失的典型症状。解法是补CONVENTIONS.md，把命名、分层、接口风格写清楚。同时在项目指令里强调“遵循 CONVENTIONS.md”。
如果补了还不一致，检查一下CONVENTIONS.md是不是写得太抽象。比如“命名要规范”这种话没用，要写“接口用 xxxApi，服务用 xxxService”这种可执行的规则。
7.4 资产库更新不及时导致建议过时
这是维护问题。解法是把更新绑到流程上，前面 4.4 节讲过。另外，可以在项目指令里加一条“如果发现资产库和代码不一致，以代码为准，并提醒我更新资产库”。这样 AI 助教能帮你发现过期内容。
7.5 常见问题速查表
| 问题现象 | 最可能的原因 | 排查方向 | 解决动作 |
|---|---|---|---|
| 答非所问 | 提示词不清或资产库过期 | 先查提示词，再查资产库 | 补提示词上下文，更新资产库 |
| 编造接口/字段 | 缺少接口契约或数据模型 | 查资产库是否有对应文件 | 补 api-contracts 和> RELATED READING 延伸阅读更多一线实战笔记与深度复盘，助您持续精进 |
