核心论点：AI 编码质量的瓶颈不在模型能力，而在模型对项目的认知。解决思路不是换更强的模型，而是搭建一个让模型越来越了解你项目的"认知漏斗"。
一个经典场景
你用 Claude Code 加一个新功能------在客服系统里给订单查询加个缓存。AI 噼里啪啦写了一堆代码，跑起来没问题，但你一看：
python
class OrderCache:
def __init__(self):
self._cache = {} # 内存 dict，重启即失
def get(self, key):
return self._cache.get(key)
def set(self, key, value, ttl=3600):
self._cache[key] = value你沉默了。项目里已经有 redis_cache_service.py，带连接池、三级降级、TTL 自动过期。AI 写出一个内存 dict 缓存，不是它不会写更好的------是它不知道你有一个更好的。
这不是一个孤例。翻翻你最近 AI 写的代码，大概率能找到这类问题的变体：
- 自己写了个 HTTP 重试逻辑，没用到项目里的
tenacity封装 - 手写了一套 JSON Schema，没用到 Pydantic 的
model_json_schema() - 在 router 里写了 30 行业务逻辑，没调用已有的 service 层
共性：AI 不知道你有什么，于是按"一般做法"重写了一遍。
问题的本质
把 AI 编码看成一个"输入→输出"系统：
输入：你的需求 + 少量上下文（当前文件）
↓
AI 模型
↓
输出：能跑的代码（但可能不兼容项目已有基础设施）输入端缺了什么？项目认知。AI 默认只看到你当前打开的文件和对话里的要求。它不知道：
| AI 不知道的 | 后果 |
|---|---|
| 项目里有哪些可复用的 Service/Util | 自己写一套 |
| 团队约定的编码规范（日志、异常处理、命名） | 风格不一致 |
| 哪些做法是被禁止的（硬编码、裸调 API） | 踩已知的坑 |
| 之前做过类似功能的实现 | 重复造轮子 |
模型本身再强也解决不了这个问题------GPT-5 来了也不知道你的 Settings 类在哪个文件里。
解法：三层认知漏斗
核心思路不是让模型变强，而是扩大输入端的项目认知。分三层递进：
┌─────────────────────────┐
│ 流程层：正确的协作模式 │ ← Agent 流水线、Plan 模式
│ （什么时候让 AI 做什么） │
├─────────────────────────┤
│ 交互层：精准输入 │ ← @ 引用文件、搜索后生成
│ （每次对话喂什么） │
├─────────────────────────┤
│ 上下文层：持久化规则 │ ← Rules、组件清单、禁止清单
│ （AI 自动知道什么） │
└─────────────────────────┘第一层：上下文层（Rules）------ AI 自动知道的
Rules 是 CodeBuddy 的规则系统。你在 .codebuddy/rules/ 下写的规则，AI 在编辑匹配的文件时自动加载。不需要每次对话提醒。
做什么：
- 编码规范："日志统一用 structlog，禁止 print()"
- 组件清单 ："缓存用
redis_cache_service，限流用rate_limiter" - 禁止清单："禁止在 router 里写内联业务逻辑，必须在 core/ 下写 service"
效果：AI 每次写代码前就已经知道你的基础设施有哪些、规范是什么。这是最省力的一层------写一次，永久生效。
第二层：交互层（@ 引用 + 搜索）------ 每次对话精准喂入
Rules 解决"AI 永远需要知道的事"，但有些信息是任务相关的------比如"这次要改的参数抽取逻辑，依赖 tool_registry.py 的哪些接口"。
做什么：
- @ 引用：对话里拖入相关文件，AI 会理解上下游调用链
- 搜索后生成：动手写代码前，先搜索项目中是否已有类似实现
效果：AI 不只是知道"项目有什么"，而是知道"这个任务和项目的哪些部分相关"。比 Rules 更精准，但需要每次对话手动操作。
第三层：流程层（模式 + Agent）------ 正确的协作节奏
输入对了，但流程不对，还是会返工。比如你用 Craft 模式让 AI 一口气改 5 个文件------它改到第 3 个就开始漂移。
做什么：
- Ask → Plan → Craft 模式选择：讨论用 Ask，设计用 Plan，实现用 Craft
- Agent 流水线：architecture-designer 出设计 → coder 实现 → test-generator 补测试 → code-reviewer 审查
效果：每步可验证，不会出现"改了一大片才发现方向错了"的情况。
三层之间的协作关系
三层不是孤立的，它们互相增强：
没有 Rules ──→ 每次对话都要手动 @ 所有依赖文件，容易遗漏
没有 @ 引用 ──→ Rules 只告诉 AI "有什么"，但不知道"这次用哪个"
没有搜索后生成 ──→ Rules 有延迟（刚加的组件还没入库），AI 仍可能重造
没有 Plan 模式 ──→ 即使用对了文件，也可能在错误的方向上越走越远真实的最佳实践是三层都用：
| 场景 | 哪层起作用 |
|---|---|
AI 想写 class OrderCache |
第一层：禁止清单 → "已有 redis_cache_service" |
| 改工具调用逻辑但不知道入口在哪 | 第二层：@ tool_registry.py → "dispatch() 是入口" |
| 参数抽取要从正则升级到 LLM | 第三层：Plan 模式先出方案 → "要改 3 个文件，顺序是..." |
| 刚加了一个新 service，AI 不知道 | 第二层：搜索后生成 → "找到了刚加的 service" |
一个完整的例子
回到开头的缓存场景。三层漏斗下，AI 的行为完全不同：
第一层（Rules 已注入）：
"禁止清单说：禁止新建 cache 类，用 redis_cache_service"
→ AI 不会写 class OrderCache
第二层（@ 引用当前 router）：
"@ src/modules/chat/core/redis_cache_service.py"
→ AI 看到了 set() / get() / delete() 的接口签名
第三层（Plan 模式）：
"计划：
1. 在 router 里注入 cache_service
2. 订单查询前加缓存读取
3. 查询后写缓存"
→ 你确认方案后 AI 再动手
结果：改 3 行代码，5 分钟搞定，零返工。对比之前：AI 写了 30 行内存 dict 代码，你手动改了 15 行，Review 发现还有边缘情况没处理，又改了两轮。
从 30 行返工到 3 行一次通过，差距不在模型------在认知输入。
核心要点
- AI 写出不兼容代码，根因不是模型不够强，是它不够了解你的项目。
- 三层漏斗是最小可落地的解法------从 Rules（自动知道）到 @ 引用（精准喂入）到 Plan 模式（正确流程），每一步都在扩大 AI 的项目认知。
- 三层要配合使用 ------只有 Rules 没有搜索，组件更新了 AI 不知道；只有 Plan 没有 Rules，AI 仍然可能自己写
class Cache。 - 投入产出比最高的起点：先写一个禁止清单 Rules（10 分钟），立刻生效。你项目中下周不会再出现裸调 openai、手写 cache 类的代码。