1. 为什么AI写的代码总像“半路出家”用AI写代码这件事现在几乎成了日常。不管是补全一个函数、生成一段CRUD还是让它帮忙重构一个模块速度确实快。但用得多了你会发现一个很普遍的问题AI生成的代码单看某一段没毛病放进项目里就各种水土不服。变量命名风格对不上、调用的工具函数不存在、业务逻辑跟现有流程冲突、边界条件完全没考虑——这些问题归根结底就一句话AI没有真正理解你项目的上下文。我最早用AI辅助编码的时候踩的最多的坑就是“它写得挺对但就是不能用”。比如让它写一个订单状态流转的方法它给我生成了一个状态机逻辑很漂亮但我们项目里订单状态是用枚举加数据库字段控制的根本没有状态机这套东西。它不知道因为它只看到了我贴给它的那几十行代码看不到整个项目的架构约定、命名习惯、工具类库和业务规则。这就是AI生成代码缺乏上下文理解的核心痛点。模型本身的能力在快速进步但“上下文窗口”始终是瓶颈。你不可能每次提问都把整个代码仓库塞进去一是塞不下二是塞进去了模型也抓不住重点。于是就有了Code2AI这类方案核心思路是通过长上下文模型配合结构化的上下文描述文件比如CLAUDE.md这种约定文件让AI在生成代码之前先“读懂”你的项目。这篇文章我想从一个一线开发者的角度把这个问题拆开讲清楚上下文理解到底难在哪、Code2AI的长上下文方案是怎么设计的、CLAUDE.md这类文件该怎么写、实际落地时有哪些坑。如果你也在团队里推AI辅助编码或者自己用AI写代码总觉得“差口气”这篇内容应该能帮你省不少时间。2. 上下文理解到底难在哪里2.1 模型看到的和你以为它看到的不是一回事很多人用AI写代码的方式是这样的打开对话框把当前文件的一段代码贴进去然后说“帮我加一个XXX功能”。这个操作里隐含了一个假设——AI能从我贴的这段代码里推断出整个项目的约定。但实际情况是AI只能基于你给的那点信息做概率性的补全。举个具体的例子。假设你贴了这么一段def get_user_order(user_id): conn get_db_connection() cursor conn.cursor() cursor.execute(SELECT * FROM orders WHERE user_id %s, (user_id,)) return cursor.fetchall()然后你说“帮我加一个按状态筛选的功能”。AI可能会给你生成一个带status参数的版本但它不知道你们项目的数据库连接是不是应该用连接池返回结果是不是应该转成ORM对象状态字段在数据库里是字符串还是整数有没有统一的异常处理规范日志该怎么打这些信息不在你贴的代码里AI只能猜。猜对了是运气猜错了你还得手动改。这就是上下文缺失的代价——AI生成的代码越多你需要修正的地方就越多效率提升被大幅抵消。2.2 上下文窗口的物理限制与信息密度问题有人会说那就多贴点代码进去不就行了现在不是有长上下文模型吗几十万token的窗口把整个项目塞进去不就完了理论上可以但实际操作中有两个问题。第一个是成本问题。长上下文意味着每次请求都要处理大量token推理成本和延迟都会显著上升。你不可能每次让AI补全一个函数都把整个仓库几万行代码传一遍。第二个是信息密度问题。就算你把整个项目塞进去了模型也不一定能找到关键信息。这就像你把一本百科全书扔给一个人然后问他“第三章第二节提到的那个公式怎么推导”他得先翻目录、再定位、再理解。上下文越长模型对中间部分的注意力就越容易衰减这是目前长上下文模型的通病。所以真正有效的方案不是“把所有东西都塞进去”而是把最关键的上下文提炼出来用结构化的方式喂给模型。这就是Code2AI方案的核心思路也是CLAUDE.md这类文件存在的意义。2.3 项目上下文包含哪些层次要把上下文这件事说清楚得先明确一个项目的“上下文”到底包含什么。我把它分成四个层次层次内容举例项目级技术栈、目录结构、构建方式用FastAPI还是Django前端用React还是Vue模块级模块职责、依赖关系、接口约定订单模块依赖用户模块通过内部RPC调用文件级文件内的类、函数、变量命名规范工具类统一放在utils目录命名用下划线风格任务级当前要做的具体改动给订单查询加一个状态筛选参数AI生成代码时如果只拿到任务级信息那它写出来的东西就是“孤岛代码”。只有把上面四个层次都覆盖到它才能写出真正能用的代码。而长上下文模型的价值就是能同时容纳多个层次的信息并在生成时综合考量。3. Code2AI的长上下文方案是怎么设计的3.1 核心思路用结构化文件替代“全量投喂”Code2AI这个方案我理解下来核心不是单纯把上下文窗口做大而是建立一套上下文描述规范让开发者用结构化的方式把项目关键信息写下来然后在每次请求时按需注入。这个思路跟CLAUDE.md的定位是一致的。CLAUDE.md本质上是一个放在项目根目录的Markdown文件里面写清楚这个项目是干什么的、用什么技术栈、有哪些约定、常见任务怎么做。当AI工具读取到这个文件时就相当于拿到了一份“项目说明书”。为什么用Markdown而不是JSON或者YAML因为Markdown对人和模型都友好。人写起来自然模型读起来也符合它预训练时的文本分布。你不需要学一套新的schema直接用自然语言把关键信息写清楚就行。3.2 长上下文模型在其中的角色长上下文模型在这里承担的是“综合推理”的角色。它需要同时处理三类信息项目上下文文件CLAUDE.md提供项目级的约定和背景相关代码片段提供当前任务涉及的具体实现用户指令说明这次要做什么传统做法是把这三类信息拼成一个prompt但拼接顺序和格式会严重影响效果。Code2AI方案里通常会做几件事第一上下文分层注入。项目级信息放在最前面作为“系统提示”的一部分相关代码片段放在中间用户指令放在最后。这样模型在生成时最近的注意力落在指令上同时前面的背景信息也能被检索到。第二关键信息重复强调。对于特别重要的约定比如“所有数据库操作必须用连接池”“异常必须用自定义的AppError抛出”会在上下文文件里用加粗或者单独章节的方式强调增加模型注意到的概率。第三动态裁剪。不是每次都要把整个CLAUDE.md注入进去。根据任务类型只注入相关章节。比如改前端组件时后端数据库约定那部分就可以省略。3.3 为什么这种方式比“微调”更实用有人可能会问为什么不直接拿项目代码微调一个模型那样模型不就“天生”懂你的项目了吗微调的问题在于成本高、周期长、不灵活。项目代码每天都在变微调一次要重新训练而且微调后的模型可能在其他任务上表现下降。相比之下用上下文文件的方式是“即写即用”的——你今天加了一条约定明天AI生成代码时就能遵守不需要任何训练过程。而且上下文文件是可版本控制的。你可以把它提交到Git仓库团队成员共享新人入职时读一遍CLAUDE.md就能快速了解项目约定。这比微调模型的黑盒方式透明得多。4. CLAUDE.md这类上下文文件该怎么写4.1 最小可用版本先写清楚这五件事如果你之前没写过这类文件不用一上来就追求大而全。先写清楚五件事就能覆盖80%的场景项目是做什么的一句话说明业务领域和核心功能技术栈语言、框架、数据库、关键依赖目录结构主要目录的职责编码约定命名规范、异常处理、日志、测试要求常见任务示例比如“新增一个API接口的步骤”我见过很多团队写的上下文文件要么太简略就写了个技术栈要么太啰嗦把整个架构文档搬进去。好的上下文文件应该像一份“给新人的快速上手指南”——信息密度高但不过度展开。4.2 一个真实的CLAUDE.md结构示例下面是我在一个实际项目中用的结构你可以参考# 项目上下文 ## 项目概述 电商后台订单管理系统处理订单创建、状态流转、退款。 ## 技术栈 - 语言Python 3.11 - 框架FastAPI - 数据库PostgreSQL SQLAlchemy ORM - 缓存Redis - 测试pytest ## 目录结构 - app/api/路由层只做参数校验和响应封装 - app/services/业务逻辑层 - app/models/SQLAlchemy模型 - app/utils/工具函数 ## 编码约定 - 所有数据库操作通过get_db()依赖注入禁止手动创建连接 - 异常统一用AppError抛出由全局异常处理器捕获 - 日志用logger logging.getLogger(__name__) - 新增接口必须写pytest测试 ## 常见任务 ### 新增一个API接口 1. 在app/api/下新建路由文件 2. 在app/services/下实现业务逻辑 3. 在app/models/下定义或复用模型 4. 写测试这个文件大概一百多行但包含了AI生成代码时最需要的信息。关键是每一条约定都是可执行的不是空泛的“代码要规范”而是“数据库操作通过get_db()依赖注入”。4.3 写上下文文件的几个实操心得第一用“禁止”和“必须”代替“建议”。模型对强约束的遵守程度明显高于软建议。写“建议用连接池”不如写“必须用get_db()禁止手动创建连接”。第二给出正例和反例。对于容易出错的约定直接给代码示例。比如# 正确 app.get(/orders) def list_orders(db: Session Depends(get_db)): ... # 错误禁止这样写 app.get(/orders) def list_orders(): conn create_connection() ...第三定期更新。项目约定变了上下文文件要同步改。我一般会在代码review时顺便检查CLAUDE.md是否需要更新。第四不要写敏感信息。上下文文件会随代码提交不要在里面写数据库密码、API密钥这类东西。5. 实操把长上下文方案落地到日常开发5.1 环境准备与工具链搭建要把这套方案用起来你需要准备几样东西一个支持长上下文的AI编码工具现在主流的AI编码助手基本都支持读取项目文件作为上下文项目根目录的上下文文件按上一节的结构写好一个约定团队所有人用AI生成代码时都确保工具读取了这个文件具体操作上不同工具的方式不一样。有的工具会自动读取项目根目录的CLAUDE.md有的需要你在配置里指定。我建议在项目README里也提一句告诉团队成员这个文件的存在和作用。5.2 一次完整的AI辅助编码流程我拿一个真实任务来演示给订单查询接口加一个按状态筛选的功能。第一步确认上下文文件已就位。检查CLAUDE.md里有没有关于API接口写法的约定。有里面写了路由层只做参数校验业务逻辑放services层。第二步给AI提供任务描述和相关代码。我会这样组织prompt参考项目上下文文件CLAUDE.md给订单查询接口加一个status筛选参数。 当前接口代码 [贴上app/api/orders.py里的查询接口] 相关service代码 [贴上app/services/order_service.py里的查询方法] 要求 - status参数可选不传时返回全部 - 遵循项目现有的参数校验方式 - 更新对应的测试第三步检查AI生成的代码。重点看几个地方有没有用get_db()、异常有没有用AppError、命名风格是否一致、测试有没有覆盖新参数。第四步运行测试。这一步不能省。AI生成的代码即使看起来对也可能有边界条件没处理。比如status传了非法值时是返回空列表还是报错这取决于你的业务约定AI不一定猜得对。5.3 参数选择上下文注入多少才合适这是一个需要权衡的问题。注入太少AI理解不够注入太多成本和延迟上升还可能引入噪声。我的经验值是项目级上下文控制在500-1500 token任务相关代码控制在1000-3000 token。这个量级下模型既能获得足够的背景信息又不会因为上下文过长而丢失重点。如果任务特别复杂比如重构一个模块可以适当增加相关代码的注入量但建议不要超过8000 token。超过这个量模型对中间部分的注意力会明显下降。另外上下文的顺序很重要。我一般按这个顺序组织项目上下文文件精简版只保留相关章节相关代码片段按依赖关系排列被依赖的放前面任务指令放最后让模型最近距离地看到5.4 验证AI生成代码是否真正理解了上下文生成完代码后怎么判断它是真的理解了上下文还是碰巧写对了我一般用三个检查点检查点一命名一致性。AI生成的变量名、函数名是否符合项目规范如果项目用snake_case它生成了camelCase说明它没读到命名约定。检查点二依赖使用。它有没有用项目里已有的工具函数还是自己重新造了一个如果重新造了说明它不知道项目里已经有现成的。检查点三异常处理。它抛的异常类型是否符合项目约定如果项目统一用AppError它抛了ValueError说明上下文没生效。这三个检查点过不了就说明上下文注入有问题需要回头检查CLAUDE.md的写法或者注入方式。6. 常见问题与排查技巧实录6.1 AI还是不用我定义的函数怎么办这是最常见的问题。你在CLAUDE.md里写了“数据库操作必须用get_db()”但AI生成的代码还是手动创建连接。排查思路确认CLAUDE.md确实被工具读取了。有的工具需要显式配置不是自动读取的。检查约定写法是否足够强。把“必须用get_db()”改成“必须用get_db()禁止手动创建连接禁止使用create_engine”。在prompt里再次强调。有时候模型对上下文文件的注意力不够需要在指令里重复关键约束。我实测下来在prompt里重复一遍关键约束遵守率能提升不少。虽然看起来有点冗余但有效。6.2 上下文文件太长导致AI忽略重点CLAUDE.md写得太长模型反而抓不住重点。这个问题很普遍。解决办法是分层组织。把最重要的约定放在文件最前面用二级标题分隔不同主题。如果某个主题特别长考虑拆成单独的文件按需注入。另一个技巧是用表格和列表代替大段文字。模型对结构化信息的提取能力比纯文本强。比如编码约定用表格列出来比写成段落效果好。6.3 不同任务需要不同上下文怎么管理一个项目里前端任务和后端任务需要的上下文不一样。如果每次都注入全部上下文既浪费又引入噪声。我的做法是按任务类型拆分上下文文件。根目录放一个CLAUDE.md作为总入口里面写项目概述和通用约定。然后在子目录放更具体的上下文文件比如app/api/CLAUDE.md写API层的约定app/services/CLAUDE.md写业务层的约定。AI工具一般支持读取多个上下文文件按需组合。这样既保证了信息的针对性又不会让单个文件过长。6.4 常见问题速查表问题现象可能原因解决办法AI不用项目已有函数上下文未注入或约定太弱检查工具配置强化约定写法生成代码风格不一致命名约定未写清楚在上下文文件里明确命名规范忽略异常处理约定约定位置太靠后把关键约定移到文件前面上下文太长导致遗漏信息密度低拆分文件用表格代替段落测试代码不符合规范测试约定未单独说明增加测试相关的上下文章节6.5 几个我踩过的坑坑一上下文文件写了但没人维护。项目初期写得好好的后来架构改了文件没更新AI生成的代码就开始跑偏。解决办法是把上下文文件的更新纳入代码review流程。坑二过度依赖AI不写测试。AI生成的代码看起来对但边界条件经常有问题。我现在养成的习惯是AI生成完代码先跑测试测试不过就自己改不纠结。坑三把所有信息都塞进一个文件。一开始我觉得一个文件方便后来发现文件太长模型反而记不住。拆成多个文件后效果明显好转。坑四忽略了prompt里的指令。上下文文件是背景prompt里的指令是当前任务。两者要配合。我现在的做法是prompt里会明确说“参考CLAUDE.md中的XXX约定”引导模型去查。7. 长上下文方案的边界与后续优化方向7.1 这套方案解决不了什么得说清楚长上下文方案不是万能的。它解决的是“AI不知道项目约定”的问题但解决不了“AI不懂业务逻辑”的问题。比如你的订单状态流转有一套复杂的业务规则涉及多个条件的组合判断。这些规则如果没写在上下文文件里AI还是写不对。而如果全写进去文件又会太长。这种情况下更好的做法是把业务规则封装成服务层的函数让AI调用而不是让AI重新实现。另外长上下文方案对架构级重构的帮助有限。重构需要理解模块间的依赖关系、数据流向、性能瓶颈这些信息很难用一份Markdown文件完整表达。重构场景下还是需要人工主导AI辅助。7.2 后续可以怎么优化方向一上下文文件的自动化生成。现在写CLAUDE.md还是靠人工未来可以从代码里自动提取关键信息比如从类型注解提取接口签名从测试文件提取行为约定。方向二动态上下文选择。根据当前任务自动从上下文文件里选取相关章节注入而不是全量注入。这需要工具层面的支持。方向三上下文效果评估。建立一套指标衡量AI生成代码的“上下文遵守率”比如命名一致性、依赖使用率、异常规范率。有了指标才能持续优化上下文文件的写法。方向四团队协作规范。把上下文文件作为团队资产来管理新人入职先读代码review时检查是否需要更新。这比技术方案本身更重要。7.3 一个实用的小技巧最后分享一个我最近在用的技巧在上下文文件里加一个“常见错误”章节记录AI经常犯的错误。比如“AI经常忘记给新接口加测试”“AI经常用错日志级别”。每次发现AI犯同样的错误就加一条进去。时间长了这个章节就成了一个“避坑清单”效果很好。这个技巧的核心逻辑是上下文文件不是一次写完就完事的它是一个持续迭代的资产。你投入的时间越多AI生成代码的质量就越高。反过来如果你只是随便写写那AI也只能随便写写。我在实际使用中发现一个维护良好的上下文文件能让AI生成代码的可用率从大概五成提升到八成以上。剩下的两成靠测试和人工review兜底。这个投入产出比对于任何用AI辅助编码的团队来说都是划算的。 AI写代码总像半路出家？长上下文方案与CLAUDE.md实战指南
1. 为什么AI写的代码总像“半路出家”用AI写代码这件事现在几乎成了日常。不管是补全一个函数、生成一段CRUD还是让它帮忙重构一个模块速度确实快。但用得多了你会发现一个很普遍的问题AI生成的代码单看某一段没毛病放进项目里就各种水土不服。变量命名风格对不上、调用的工具函数不存在、业务逻辑跟现有流程冲突、边界条件完全没考虑——这些问题归根结底就一句话AI没有真正理解你项目的上下文。我最早用AI辅助编码的时候踩的最多的坑就是“它写得挺对但就是不能用”。比如让它写一个订单状态流转的方法它给我生成了一个状态机逻辑很漂亮但我们项目里订单状态是用枚举加数据库字段控制的根本没有状态机这套东西。它不知道因为它只看到了我贴给它的那几十行代码看不到整个项目的架构约定、命名习惯、工具类库和业务规则。这就是AI生成代码缺乏上下文理解的核心痛点。模型本身的能力在快速进步但“上下文窗口”始终是瓶颈。你不可能每次提问都把整个代码仓库塞进去一是塞不下二是塞进去了模型也抓不住重点。于是就有了Code2AI这类方案核心思路是通过长上下文模型配合结构化的上下文描述文件比如CLAUDE.md这种约定文件让AI在生成代码之前先“读懂”你的项目。这篇文章我想从一个一线开发者的角度把这个问题拆开讲清楚上下文理解到底难在哪、Code2AI的长上下文方案是怎么设计的、CLAUDE.md这类文件该怎么写、实际落地时有哪些坑。如果你也在团队里推AI辅助编码或者自己用AI写代码总觉得“差口气”这篇内容应该能帮你省不少时间。2. 上下文理解到底难在哪里2.1 模型看到的和你以为它看到的不是一回事很多人用AI写代码的方式是这样的打开对话框把当前文件的一段代码贴进去然后说“帮我加一个XXX功能”。这个操作里隐含了一个假设——AI能从我贴的这段代码里推断出整个项目的约定。但实际情况是AI只能基于你给的那点信息做概率性的补全。举个具体的例子。假设你贴了这么一段def get_user_order(user_id): conn get_db_connection() cursor conn.cursor() cursor.execute(SELECT * FROM orders WHERE user_id %s, (user_id,)) return cursor.fetchall()然后你说“帮我加一个按状态筛选的功能”。AI可能会给你生成一个带status参数的版本但它不知道你们项目的数据库连接是不是应该用连接池返回结果是不是应该转成ORM对象状态字段在数据库里是字符串还是整数有没有统一的异常处理规范日志该怎么打这些信息不在你贴的代码里AI只能猜。猜对了是运气猜错了你还得手动改。这就是上下文缺失的代价——AI生成的代码越多你需要修正的地方就越多效率提升被大幅抵消。2.2 上下文窗口的物理限制与信息密度问题有人会说那就多贴点代码进去不就行了现在不是有长上下文模型吗几十万token的窗口把整个项目塞进去不就完了理论上可以但实际操作中有两个问题。第一个是成本问题。长上下文意味着每次请求都要处理大量token推理成本和延迟都会显著上升。你不可能每次让AI补全一个函数都把整个仓库几万行代码传一遍。第二个是信息密度问题。就算你把整个项目塞进去了模型也不一定能找到关键信息。这就像你把一本百科全书扔给一个人然后问他“第三章第二节提到的那个公式怎么推导”他得先翻目录、再定位、再理解。上下文越长模型对中间部分的注意力就越容易衰减这是目前长上下文模型的通病。所以真正有效的方案不是“把所有东西都塞进去”而是把最关键的上下文提炼出来用结构化的方式喂给模型。这就是Code2AI方案的核心思路也是CLAUDE.md这类文件存在的意义。2.3 项目上下文包含哪些层次要把上下文这件事说清楚得先明确一个项目的“上下文”到底包含什么。我把它分成四个层次层次内容举例项目级技术栈、目录结构、构建方式用FastAPI还是Django前端用React还是Vue模块级模块职责、依赖关系、接口约定订单模块依赖用户模块通过内部RPC调用文件级文件内的类、函数、变量命名规范工具类统一放在utils目录命名用下划线风格任务级当前要做的具体改动给订单查询加一个状态筛选参数AI生成代码时如果只拿到任务级信息那它写出来的东西就是“孤岛代码”。只有把上面四个层次都覆盖到它才能写出真正能用的代码。而长上下文模型的价值就是能同时容纳多个层次的信息并在生成时综合考量。3. Code2AI的长上下文方案是怎么设计的3.1 核心思路用结构化文件替代“全量投喂”Code2AI这个方案我理解下来核心不是单纯把上下文窗口做大而是建立一套上下文描述规范让开发者用结构化的方式把项目关键信息写下来然后在每次请求时按需注入。这个思路跟CLAUDE.md的定位是一致的。CLAUDE.md本质上是一个放在项目根目录的Markdown文件里面写清楚这个项目是干什么的、用什么技术栈、有哪些约定、常见任务怎么做。当AI工具读取到这个文件时就相当于拿到了一份“项目说明书”。为什么用Markdown而不是JSON或者YAML因为Markdown对人和模型都友好。人写起来自然模型读起来也符合它预训练时的文本分布。你不需要学一套新的schema直接用自然语言把关键信息写清楚就行。3.2 长上下文模型在其中的角色长上下文模型在这里承担的是“综合推理”的角色。它需要同时处理三类信息项目上下文文件CLAUDE.md提供项目级的约定和背景相关代码片段提供当前任务涉及的具体实现用户指令说明这次要做什么传统做法是把这三类信息拼成一个prompt但拼接顺序和格式会严重影响效果。Code2AI方案里通常会做几件事第一上下文分层注入。项目级信息放在最前面作为“系统提示”的一部分相关代码片段放在中间用户指令放在最后。这样模型在生成时最近的注意力落在指令上同时前面的背景信息也能被检索到。第二关键信息重复强调。对于特别重要的约定比如“所有数据库操作必须用连接池”“异常必须用自定义的AppError抛出”会在上下文文件里用加粗或者单独章节的方式强调增加模型注意到的概率。第三动态裁剪。不是每次都要把整个CLAUDE.md注入进去。根据任务类型只注入相关章节。比如改前端组件时后端数据库约定那部分就可以省略。3.3 为什么这种方式比“微调”更实用有人可能会问为什么不直接拿项目代码微调一个模型那样模型不就“天生”懂你的项目了吗微调的问题在于成本高、周期长、不灵活。项目代码每天都在变微调一次要重新训练而且微调后的模型可能在其他任务上表现下降。相比之下用上下文文件的方式是“即写即用”的——你今天加了一条约定明天AI生成代码时就能遵守不需要任何训练过程。而且上下文文件是可版本控制的。你可以把它提交到Git仓库团队成员共享新人入职时读一遍CLAUDE.md就能快速了解项目约定。这比微调模型的黑盒方式透明得多。4. CLAUDE.md这类上下文文件该怎么写4.1 最小可用版本先写清楚这五件事如果你之前没写过这类文件不用一上来就追求大而全。先写清楚五件事就能覆盖80%的场景项目是做什么的一句话说明业务领域和核心功能技术栈语言、框架、数据库、关键依赖目录结构主要目录的职责编码约定命名规范、异常处理、日志、测试要求常见任务示例比如“新增一个API接口的步骤”我见过很多团队写的上下文文件要么太简略就写了个技术栈要么太啰嗦把整个架构文档搬进去。好的上下文文件应该像一份“给新人的快速上手指南”——信息密度高但不过度展开。4.2 一个真实的CLAUDE.md结构示例下面是我在一个实际项目中用的结构你可以参考# 项目上下文 ## 项目概述 电商后台订单管理系统处理订单创建、状态流转、退款。 ## 技术栈 - 语言Python 3.11 - 框架FastAPI - 数据库PostgreSQL SQLAlchemy ORM - 缓存Redis - 测试pytest ## 目录结构 - app/api/路由层只做参数校验和响应封装 - app/services/业务逻辑层 - app/models/SQLAlchemy模型 - app/utils/工具函数 ## 编码约定 - 所有数据库操作通过get_db()依赖注入禁止手动创建连接 - 异常统一用AppError抛出由全局异常处理器捕获 - 日志用logger logging.getLogger(__name__) - 新增接口必须写pytest测试 ## 常见任务 ### 新增一个API接口 1. 在app/api/下新建路由文件 2. 在app/services/下实现业务逻辑 3. 在app/models/下定义或复用模型 4. 写测试这个文件大概一百多行但包含了AI生成代码时最需要的信息。关键是每一条约定都是可执行的不是空泛的“代码要规范”而是“数据库操作通过get_db()依赖注入”。4.3 写上下文文件的几个实操心得第一用“禁止”和“必须”代替“建议”。模型对强约束的遵守程度明显高于软建议。写“建议用连接池”不如写“必须用get_db()禁止手动创建连接”。第二给出正例和反例。对于容易出错的约定直接给代码示例。比如# 正确 app.get(/orders) def list_orders(db: Session Depends(get_db)): ... # 错误禁止这样写 app.get(/orders) def list_orders(): conn create_connection() ...第三定期更新。项目约定变了上下文文件要同步改。我一般会在代码review时顺便检查CLAUDE.md是否需要更新。第四不要写敏感信息。上下文文件会随代码提交不要在里面写数据库密码、API密钥这类东西。5. 实操把长上下文方案落地到日常开发5.1 环境准备与工具链搭建要把这套方案用起来你需要准备几样东西一个支持长上下文的AI编码工具现在主流的AI编码助手基本都支持读取项目文件作为上下文项目根目录的上下文文件按上一节的结构写好一个约定团队所有人用AI生成代码时都确保工具读取了这个文件具体操作上不同工具的方式不一样。有的工具会自动读取项目根目录的CLAUDE.md有的需要你在配置里指定。我建议在项目README里也提一句告诉团队成员这个文件的存在和作用。5.2 一次完整的AI辅助编码流程我拿一个真实任务来演示给订单查询接口加一个按状态筛选的功能。第一步确认上下文文件已就位。检查CLAUDE.md里有没有关于API接口写法的约定。有里面写了路由层只做参数校验业务逻辑放services层。第二步给AI提供任务描述和相关代码。我会这样组织prompt参考项目上下文文件CLAUDE.md给订单查询接口加一个status筛选参数。 当前接口代码 [贴上app/api/orders.py里的查询接口] 相关service代码 [贴上app/services/order_service.py里的查询方法] 要求 - status参数可选不传时返回全部 - 遵循项目现有的参数校验方式 - 更新对应的测试第三步检查AI生成的代码。重点看几个地方有没有用get_db()、异常有没有用AppError、命名风格是否一致、测试有没有覆盖新参数。第四步运行测试。这一步不能省。AI生成的代码即使看起来对也可能有边界条件没处理。比如status传了非法值时是返回空列表还是报错这取决于你的业务约定AI不一定猜得对。5.3 参数选择上下文注入多少才合适这是一个需要权衡的问题。注入太少AI理解不够注入太多成本和延迟上升还可能引入噪声。我的经验值是项目级上下文控制在500-1500 token任务相关代码控制在1000-3000 token。这个量级下模型既能获得足够的背景信息又不会因为上下文过长而丢失重点。如果任务特别复杂比如重构一个模块可以适当增加相关代码的注入量但建议不要超过8000 token。超过这个量模型对中间部分的注意力会明显下降。另外上下文的顺序很重要。我一般按这个顺序组织项目上下文文件精简版只保留相关章节相关代码片段按依赖关系排列被依赖的放前面任务指令放最后让模型最近距离地看到5.4 验证AI生成代码是否真正理解了上下文生成完代码后怎么判断它是真的理解了上下文还是碰巧写对了我一般用三个检查点检查点一命名一致性。AI生成的变量名、函数名是否符合项目规范如果项目用snake_case它生成了camelCase说明它没读到命名约定。检查点二依赖使用。它有没有用项目里已有的工具函数还是自己重新造了一个如果重新造了说明它不知道项目里已经有现成的。检查点三异常处理。它抛的异常类型是否符合项目约定如果项目统一用AppError它抛了ValueError说明上下文没生效。这三个检查点过不了就说明上下文注入有问题需要回头检查CLAUDE.md的写法或者注入方式。6. 常见问题与排查技巧实录6.1 AI还是不用我定义的函数怎么办这是最常见的问题。你在CLAUDE.md里写了“数据库操作必须用get_db()”但AI生成的代码还是手动创建连接。排查思路确认CLAUDE.md确实被工具读取了。有的工具需要显式配置不是自动读取的。检查约定写法是否足够强。把“必须用get_db()”改成“必须用get_db()禁止手动创建连接禁止使用create_engine”。在prompt里再次强调。有时候模型对上下文文件的注意力不够需要在指令里重复关键约束。我实测下来在prompt里重复一遍关键约束遵守率能提升不少。虽然看起来有点冗余但有效。6.2 上下文文件太长导致AI忽略重点CLAUDE.md写得太长模型反而抓不住重点。这个问题很普遍。解决办法是分层组织。把最重要的约定放在文件最前面用二级标题分隔不同主题。如果某个主题特别长考虑拆成单独的文件按需注入。另一个技巧是用表格和列表代替大段文字。模型对结构化信息的提取能力比纯文本强。比如编码约定用表格列出来比写成段落效果好。6.3 不同任务需要不同上下文怎么管理一个项目里前端任务和后端任务需要的上下文不一样。如果每次都注入全部上下文既浪费又引入噪声。我的做法是按任务类型拆分上下文文件。根目录放一个CLAUDE.md作为总入口里面写项目概述和通用约定。然后在子目录放更具体的上下文文件比如app/api/CLAUDE.md写API层的约定app/services/CLAUDE.md写业务层的约定。AI工具一般支持读取多个上下文文件按需组合。这样既保证了信息的针对性又不会让单个文件过长。6.4 常见问题速查表问题现象可能原因解决办法AI不用项目已有函数上下文未注入或约定太弱检查工具配置强化约定写法生成代码风格不一致命名约定未写清楚在上下文文件里明确命名规范忽略异常处理约定约定位置太靠后把关键约定移到文件前面上下文太长导致遗漏信息密度低拆分文件用表格代替段落测试代码不符合规范测试约定未单独说明增加测试相关的上下文章节6.5 几个我踩过的坑坑一上下文文件写了但没人维护。项目初期写得好好的后来架构改了文件没更新AI生成的代码就开始跑偏。解决办法是把上下文文件的更新纳入代码review流程。坑二过度依赖AI不写测试。AI生成的代码看起来对但边界条件经常有问题。我现在养成的习惯是AI生成完代码先跑测试测试不过就自己改不纠结。坑三把所有信息都塞进一个文件。一开始我觉得一个文件方便后来发现文件太长模型反而记不住。拆成多个文件后效果明显好转。坑四忽略了prompt里的指令。上下文文件是背景prompt里的指令是当前任务。两者要配合。我现在的做法是prompt里会明确说“参考CLAUDE.md中的XXX约定”引导模型去查。7. 长上下文方案的边界与后续优化方向7.1 这套方案解决不了什么得说清楚长上下文方案不是万能的。它解决的是“AI不知道项目约定”的问题但解决不了“AI不懂业务逻辑”的问题。比如你的订单状态流转有一套复杂的业务规则涉及多个条件的组合判断。这些规则如果没写在上下文文件里AI还是写不对。而如果全写进去文件又会太长。这种情况下更好的做法是把业务规则封装成服务层的函数让AI调用而不是让AI重新实现。另外长上下文方案对架构级重构的帮助有限。重构需要理解模块间的依赖关系、数据流向、性能瓶颈这些信息很难用一份Markdown文件完整表达。重构场景下还是需要人工主导AI辅助。7.2 后续可以怎么优化方向一上下文文件的自动化生成。现在写CLAUDE.md还是靠人工未来可以从代码里自动提取关键信息比如从类型注解提取接口签名从测试文件提取行为约定。方向二动态上下文选择。根据当前任务自动从上下文文件里选取相关章节注入而不是全量注入。这需要工具层面的支持。方向三上下文效果评估。建立一套指标衡量AI生成代码的“上下文遵守率”比如命名一致性、依赖使用率、异常规范率。有了指标才能持续优化上下文文件的写法。方向四团队协作规范。把上下文文件作为团队资产来管理新人入职先读代码review时检查是否需要更新。这比技术方案本身更重要。7.3 一个实用的小技巧最后分享一个我最近在用的技巧在上下文文件里加一个“常见错误”章节记录AI经常犯的错误。比如“AI经常忘记给新接口加测试”“AI经常用错日志级别”。每次发现AI犯同样的错误就加一条进去。时间长了这个章节就成了一个“避坑清单”效果很好。这个技巧的核心逻辑是上下文文件不是一次写完就完事的它是一个持续迭代的资产。你投入的时间越多AI生成代码的质量就越高。反过来如果你只是随便写写那AI也只能随便写写。我在实际使用中发现一个维护良好的上下文文件能让AI生成代码的可用率从大概五成提升到八成以上。剩下的两成靠测试和人工review兜底。这个投入产出比对于任何用AI辅助编码的团队来说都是划算的。