如果你是一名开发者最近可能已经感受到了某种“不对劲”AI 工具越来越多代码生成越来越快但项目交付的瓶颈似乎并没有因此消失。我们不再为“写代码”本身发愁却陷入了更深的泥潭——如何让 AI 理解我们真正的意图如何把零散的 AI 输出整合成一个逻辑自洽的系统如何管理这些由 AI 生成的、充满不确定性的“代码资产”这正是 Geoffrey Litt 在《理解成为新的瓶颈》一文中提出的核心观点。这篇文章并非来自科技媒体而是一位资深工程师在 Notion 上分享的深度思考它精准地戳中了当前“AI 工程师”热潮下的一个关键痛点当 AI 大幅降低了“生成”的成本后“理解”与“协调”的成本反而急剧上升成为了制约生产效率的新瓶颈。本文不会复述那篇文章的每一句话而是会结合我们日常的开发实践深入拆解这个“理解瓶颈”到底是什么它具体体现在哪些开发环节以及作为开发者我们该如何利用现有的工具如 Notion和思维模型来应对。你会发现解决这个瓶颈远比学会使用一个新的 AI 代码助手更重要。1. 这篇文章真正要解决的问题为什么 AI 越强我越累过去一个功能的开发流程相对线性理解需求 - 设计架构 - 编写代码 - 测试调试。瓶颈通常出现在“编写代码”阶段需要深厚的语法和算法功底。现在有了 Copilot、ChatGPT 等工具“编写代码”环节被极大加速。你描述一个功能AI 能瞬间生成大段代码。但问题也随之而来生成代码的“黑盒”特性AI 生成的代码能跑但为什么这么写边界条件处理全了吗性能如何你需要花时间去“理解”这段本应由你创造的代码。碎片化的输出AI 擅长完成具体的、局部的任务如写一个函数、一个 API 接口但如何将这些碎片组装成一个完整、可维护的系统这个“系统级理解”和“组装工作”完全落在了开发者肩上。意图传递的损耗用自然语言描述复杂逻辑本身就是高损耗的。你的描述稍有偏差AI 的输出就可能南辕北辙。反复沟通和修正的成本有时甚至高于自己动手写。知识资产的混乱大量 AI 生成的代码片段、配置、提示词散落在聊天记录、临时文件和各种 AI 工具中难以检索、复用和迭代形成了新的“技术债”。Geoffrey Litt 指出瓶颈已经从“生成能力”转移到了“理解能力”——包括让 AI 理解我们以及我们去理解 AI 的产出。对于每一位正在使用或考虑使用 AI 进行开发的工程师来说建立一套超越“提示词技巧”的、系统化的“理解管理”工作流是当前提升效率最关键的破局点。2. 核心概念什么是“AI Engineer”与“理解瓶颈”在深入解决方案前我们需要明确两个核心概念。2.1 AI Engineer不止是会用 ChatGPT 写代码“AI Engineer”是当前一个热门但定义模糊的职位。它不仅仅是“会使用 AI 工具的软件工程师”。一个真正的 AI Engineer 应该具备以下分层能力基础层提示工程与工具链。熟练使用各类 AI 编程助手Copilot, Cursor、大模型 APIOpenAI, Claude和 AI 驱动开发环境。这是入门门槛。核心层系统思维与抽象能力。能够将复杂问题分解为 AI 擅长处理的子任务设计清晰的数据流和接口并将 AI 的产出整合进现有工程体系。这是应对“理解瓶颈”的关键。进阶层评估与优化。能建立评估 AI 生成代码质量、性能和安全性的标准与流程并能通过迭代提示词、微调模型或设计验证程序来持续优化 AI 的产出。本文讨论的“理解瓶颈”主要挑战的是核心层的能力。它要求我们从“代码编写者”部分转变为“系统设计者”和“AI 输出管理者”。2.2 “理解瓶颈”的具体表现“理解”在这里是双向的具体表现为四个维度维度传统开发瓶颈AI 时代的新瓶颈理解瓶颈需求理解与产品经理沟通将模糊需求转化为清晰的技术方案。将技术方案转化为 AI 能精确执行的、无歧义的提示词或指令集。代码理解阅读和理解他人或自己过去的复杂代码。快速审计、验证和消化 AI 生成的大量“陌生”代码理解其意图和潜在缺陷。系统理解设计模块化架构管理模块间的依赖和通信。设计能让 AI 协作的“接口”和“协议”将 AI 生成的碎片组装成可靠系统。知识管理管理文档、代码库和设计图。管理提示词、AI 会话上下文、生成的代码片段及其元数据如生成原因、版本、评估结果。3. 应对策略以 Notion 为例构建你的“理解增强”工作流工具不是万能的但好的工具能固化思维模型。Notion 作为一个高度灵活的知识管理工具非常适合用来构建应对“理解瓶颈”的个人或团队工作流。下面我们将一个功能开发的全生命周期为例展示如何实践。3.1 环境与思想准备核心思想将 Notion 作为 AI 辅助开发的“中央控制台”和“第二大脑”而不是零散的记事本。这里记录的不是最终代码而是决策过程、上下文和知识链接。基本设置创建一个名为AI-Dev-Workspace的 Notion 页面作为总入口。在内部建立几个核心数据库Database项目看板管理开发任务。提示词库积累和优化针对不同场景的提示词。代码片段库保存和分类 AI 生成的有价值的代码并附上上下文。决策日志记录为什么选择某种实现方案AI 提供了哪些选项最终依据是什么。3.2 核心流程拆解从需求到可维护代码我们以开发一个“用户上传图片并压缩”的 API 为例。步骤一需求澄清与任务分解在 Notion 中完成不要在聊天框里直接开始。先在 Notion 的项目看板中创建一个任务卡标题为“实现图片上传压缩 API”。在卡片内部使用/code块或分点描述清晰地定义输入HTTP POST 请求multipart/form-data字段image。输出JSON包含压缩后图片的 URL 和元数据大小、格式。非功能性需求支持常见格式JPG, PNG最大尺寸限制压缩比可配置异步处理。AI 辅助子任务生成 Flask/FastAPI 的图片上传端点代码。生成使用 Pillow 库进行图片压缩的代码。生成将压缩图片保存到云存储如 S3的代码。生成相关的配置说明如环境变量。这一步的价值你强迫自己进行了系统思考为 AI 提供了结构化的、无歧义的上下文。这本身就是对“需求理解瓶颈”的突破。步骤二结构化提示与生成链接 Notion 与 AI 工具现在不要将整个任务卡扔给 AI。而是针对子任务 1从你的提示词库中找到一个“生成 RESTful API 端点”的优质提示词模板并填入当前项目的具体参数。在 Notion 中创建一个临时页面标题为“【任务1】上传端点生成记录”然后开始与 AI如 ChatGPT对话你的提示词从 Notion 复制过去你是一个经验丰富的 Python 后端工程师。请为以下需求生成 FastAPI 代码。 项目上下文我们正在构建一个图片处理服务。 具体任务创建一个图片上传端点。 详细要求 1. 路径为 /upload方法 POST。 2. 接收 multipart/form-data 格式的 image 文件字段。 3. 进行基础验证文件大小不超过 10MB类型仅限 [image/jpeg, image/png]。 4. 暂时将文件保存到服务器的临时目录路径可配置。 5. 返回一个 JSON格式为 {status: success, message: 文件已接收, filename: xxx}。 6. 请包含必要的异常处理如文件过大、类型错误并返回合适的 HTTP 状态码。 7. 在代码中添加清晰的注释。 请只输出最终的代码块。AI 生成代码后将其复制回Notion 的这个临时页面中粘贴为代码块。并在代码块下方记录使用的 AI 模型和提示词版本。生成时间。你的初步审查笔记例如“异常处理逻辑完整但临时目录路径最好从环境变量读取已标记 TODO”。步骤三审查、集成与知识沉淀回到 Notion这是克服“代码理解瓶颈”的关键。不要在 IDE 里直接使用生成的代码。静态审查在 Notion 页面中仔细阅读生成的代码。用评论功能或高亮标记出你理解有疑问、觉得需要优化或存在潜在风险的地方。创建代码片段库条目如果这个上传代码的模式具有通用性例如验证逻辑将其保存到代码片段库中。属性可以包括语言Python、框架FastAPI、功能分类文件上传、依赖Pillow、以及关键的提示词上下文。这样下次类似需求你可以直接从这个库关联的提示词开始。更新决策日志在项目主页面记录为什么选择 FastAPI 而不是 Flask为什么这样设计验证逻辑。如果 AI 提供了其他方案比如用streaming处理大文件也记录下来并说明否决原因。步骤四组装与系统测试跳出 Notion但保持链接将审查和修正后的代码从 Notion 复制到你的 IDE 项目中。然后重复步骤二和步骤三完成子任务 2图片压缩和 3云存储。当所有模块代码就绪在本地运行测试。如果测试失败或发现集成问题将错误信息和你的调试过程记录回 Notion 的对应任务页面。例如“发现压缩模块与上传模块的临时文件路径不一致已修复。根本原因提示词中未明确要求路径变量名统一。”这个记录极其宝贵它帮助你迭代提示词并沉淀了“AI 协同开发时常见的集成陷阱”这类隐性知识。3.3 完整示例一个 Notion 任务页面的样子# 任务[API-002] 实现图片上传压缩端点 **状态**进行中 **关联项目**图片处理微服务 **创建日期**2023-10-27 ## 1. 需求定义 - 输入POST /upload, multipart/form-data (image) - 输出JSON {“url”: “”, “size”: 1024, “format”: “jpg”} - 约束≤10MB, JPG/PNG, 压缩至宽度≤1200px ## 2. AI 生成与审查记录 ### 2.1 子任务FastAPI 上传端点 **提示词ID**PROMPT#FASTAPI_FILE_UPLOAD_V2 **生成模型**GPT-4 **生成时间**2023-10-27 14:30 python # 文件app/api/upload.py from fastapi import FastAPI, File, UploadFile, HTTPException import os from pathlib import Path import shutil app FastAPI() # TODO: 从环境变量读取 TEMP_DIR Path(./tmp) TEMP_DIR.mkdir(exist_okTrue) ALLOWED_TYPES [image/jpeg, image/png] MAX_SIZE 10 * 1024 * 1024 # 10MB app.post(/upload) async def upload_image(image: UploadFile File(...)): # 1. 验证文件类型 if image.content_type not in ALLOWED_TYPES: raise HTTPException(status_code400, detailUnsupported file type.) # 2. 验证文件大小注意这里需要读取内容对于大文件需优化 contents await image.read() if len(contents) MAX_SIZE: raise HTTPException(status_code400, detailFile too large.) # 3. 保存临时文件 file_location TEMP_DIR / image.filename with open(file_location, wb) as f: f.write(contents) # 4. 返回响应后续将触发压缩任务 return { status: success, message: File uploaded successfully., filename: image.filename, path: str(file_location) }审查笔记✅ 基础验证和异常处理完整。⚠️await image.read()会读取整个文件到内存不符合MAX_SIZE验证的初衷。对于大文件应使用spooled特性或流式检查。已标记为待优化。 已将TEMP_DIR标记为 TODO需改为从配置读取。决策当前版本可用于开发测试性能优化放入下一个迭代。2.2 子任务Pillow 图片压缩类似结构包含提示词、代码和审查笔记3. 集成与测试记录2023-10-27 16:00将上传和压缩模块集成。发现压缩模块需要文件路径但上传模块返回的是Path对象。已修复统一使用str(path)传递。2023-10-27 16:30测试通过。上传 JPG 文件成功返回压缩后的 URL。4. 关联知识链接到提示词库[PROMPT#FASTAPI_FILE_UPLOAD_V2]链接到代码片段库[通用文件验证逻辑]链接到决策日志[关于异步处理 vs 同步处理的选择]## 4. 常见问题与排查思路 在实践上述工作流时你可能会遇到以下典型问题 | 问题现象 | 可能原因 | 排查方式 | 解决方案 | | :--- | :--- | :--- | :--- | | AI 生成的代码跑不通但看起来没问题。 | 1. 缺少关键依赖导入。br2. 使用了过时或错误的 API。br3. 上下文理解偏差如 Python 版本。 | 1. 检查代码块顶部的 import 语句。br2. 将错误信息反馈给 AI要求其检查。br3. 在提示词中明确指定技术栈和版本。 | **永远先在隔离环境测试**。将提示词细化例如“请为 **Python 3.9** 和 **FastAPI 0.104** 生成代码。” | | 不同 AI 会话生成的代码风格不一致难以整合。 | 提示词缺乏对代码风格和项目规范的约束。 | 对比不同会话的提示词差异。 | 在提示词库中建立**项目专用提示词模板**开头固定包含“请遵循本项目规范使用 Black 格式化类型注解错误处理用自定义异常类等。” | | 忘记了某个功能当初为什么这么实现。 | 决策过程没有记录只有最终代码。 | 回溯 Git 提交历史但信息有限。 | 强制要求任何由 AI 辅助实现的功能其 Notion 任务页面必须包含“决策日志”部分记录备选方案和选择理由。 | | 找不到之前用过的一个很好的提示词或代码片段。 | 知识资产散落在各处。 | 在各个聊天历史、文件中盲目搜索。 | 建立并严格执行 Notion 提示词库和代码片段库的积累和分类习惯。每次生成有价值内容后花 2 分钟进行保存和关联。 | ## 5. 最佳实践与工程建议 1. **提示词工程化**不要每次重写提示词。将你的提示词库当成代码库来维护进行版本化、分类如“代码生成”、“代码审查”、“文档生成”、“调试”并持续迭代优化。 2. **上下文管理**在与 AI 对话时主动提供结构化上下文。可以将 Notion 页面的大纲、接口定义、错误日志直接作为提示词的一部分。这能显著降低“意图传递损耗”。 3. **代码所有权****AI 是副驾驶你才是机长**。你必须对最终进入代码库的每一行负责。这意味着严格的审查、测试和重构。AI 生成代码的初始版本应被视为“初稿”。 4. **聚焦 AI 的优势与劣势**让 AI 去做它擅长的事生成样板代码、编写单元测试、解释复杂代码、提供多种实现方案。把系统设计、架构决策、业务逻辑整合和最终的质量把关留给自己。 5. **工具链集成**探索将 Notion 与开发流程更深集成。例如使用 Notion API 将任务状态同步到 GitHub Issues或将 CI/CD 失败日志自动回写到对应的 Notion 任务页面。 6. **团队协同**在团队中共享 Notion 工作区。统一的提示词库和决策日志能极大降低团队认知负荷让新成员快速理解项目为何如此构建避免重复踩坑。 ## 6. 总结 Geoffrey Litt 所说的“理解成为新的瓶颈”是一个深刻的行业洞察。它告诉我们在 AI 时代开发者的核心价值正在从“编码实现”向“精准定义问题、管理复杂性和保障系统可靠性”迁移。 应对这一挑战单纯学习更炫酷的提示词技巧是远远不够的。你需要构建一个外化的、系统化的“理解增强”工作流。本文以 Notion 为例展示了一种将思考过程、决策逻辑和 AI 交互记录进行结构化管理的方法。这套方法的本质是 * **将隐性的“理解”过程显性化**通过需求澄清、决策日志。 * **将碎片化的 AI 输出资产化**通过提示词库、代码片段库。 * **将线性的开发流程迭代化**通过生成-审查-记录-优化的闭环。 开始行动吧。不必追求一步到位打造完美体系可以从下一个功能开发任务开始尝试在 Notion 中创建一个任务页面并遵循“澄清 - 生成 - 审查 - 记录”的流程。当你积累了几十个这样的页面后你会发现自己对项目的“理解”达到了一个新的高度而 AI 也将真正从一个时灵时不灵的“魔术盒”变成一个稳定可靠的“动力倍增器”。 AI时代开发新瓶颈：理解成本飙升与Notion工作流应对策略
如果你是一名开发者最近可能已经感受到了某种“不对劲”AI 工具越来越多代码生成越来越快但项目交付的瓶颈似乎并没有因此消失。我们不再为“写代码”本身发愁却陷入了更深的泥潭——如何让 AI 理解我们真正的意图如何把零散的 AI 输出整合成一个逻辑自洽的系统如何管理这些由 AI 生成的、充满不确定性的“代码资产”这正是 Geoffrey Litt 在《理解成为新的瓶颈》一文中提出的核心观点。这篇文章并非来自科技媒体而是一位资深工程师在 Notion 上分享的深度思考它精准地戳中了当前“AI 工程师”热潮下的一个关键痛点当 AI 大幅降低了“生成”的成本后“理解”与“协调”的成本反而急剧上升成为了制约生产效率的新瓶颈。本文不会复述那篇文章的每一句话而是会结合我们日常的开发实践深入拆解这个“理解瓶颈”到底是什么它具体体现在哪些开发环节以及作为开发者我们该如何利用现有的工具如 Notion和思维模型来应对。你会发现解决这个瓶颈远比学会使用一个新的 AI 代码助手更重要。1. 这篇文章真正要解决的问题为什么 AI 越强我越累过去一个功能的开发流程相对线性理解需求 - 设计架构 - 编写代码 - 测试调试。瓶颈通常出现在“编写代码”阶段需要深厚的语法和算法功底。现在有了 Copilot、ChatGPT 等工具“编写代码”环节被极大加速。你描述一个功能AI 能瞬间生成大段代码。但问题也随之而来生成代码的“黑盒”特性AI 生成的代码能跑但为什么这么写边界条件处理全了吗性能如何你需要花时间去“理解”这段本应由你创造的代码。碎片化的输出AI 擅长完成具体的、局部的任务如写一个函数、一个 API 接口但如何将这些碎片组装成一个完整、可维护的系统这个“系统级理解”和“组装工作”完全落在了开发者肩上。意图传递的损耗用自然语言描述复杂逻辑本身就是高损耗的。你的描述稍有偏差AI 的输出就可能南辕北辙。反复沟通和修正的成本有时甚至高于自己动手写。知识资产的混乱大量 AI 生成的代码片段、配置、提示词散落在聊天记录、临时文件和各种 AI 工具中难以检索、复用和迭代形成了新的“技术债”。Geoffrey Litt 指出瓶颈已经从“生成能力”转移到了“理解能力”——包括让 AI 理解我们以及我们去理解 AI 的产出。对于每一位正在使用或考虑使用 AI 进行开发的工程师来说建立一套超越“提示词技巧”的、系统化的“理解管理”工作流是当前提升效率最关键的破局点。2. 核心概念什么是“AI Engineer”与“理解瓶颈”在深入解决方案前我们需要明确两个核心概念。2.1 AI Engineer不止是会用 ChatGPT 写代码“AI Engineer”是当前一个热门但定义模糊的职位。它不仅仅是“会使用 AI 工具的软件工程师”。一个真正的 AI Engineer 应该具备以下分层能力基础层提示工程与工具链。熟练使用各类 AI 编程助手Copilot, Cursor、大模型 APIOpenAI, Claude和 AI 驱动开发环境。这是入门门槛。核心层系统思维与抽象能力。能够将复杂问题分解为 AI 擅长处理的子任务设计清晰的数据流和接口并将 AI 的产出整合进现有工程体系。这是应对“理解瓶颈”的关键。进阶层评估与优化。能建立评估 AI 生成代码质量、性能和安全性的标准与流程并能通过迭代提示词、微调模型或设计验证程序来持续优化 AI 的产出。本文讨论的“理解瓶颈”主要挑战的是核心层的能力。它要求我们从“代码编写者”部分转变为“系统设计者”和“AI 输出管理者”。2.2 “理解瓶颈”的具体表现“理解”在这里是双向的具体表现为四个维度维度传统开发瓶颈AI 时代的新瓶颈理解瓶颈需求理解与产品经理沟通将模糊需求转化为清晰的技术方案。将技术方案转化为 AI 能精确执行的、无歧义的提示词或指令集。代码理解阅读和理解他人或自己过去的复杂代码。快速审计、验证和消化 AI 生成的大量“陌生”代码理解其意图和潜在缺陷。系统理解设计模块化架构管理模块间的依赖和通信。设计能让 AI 协作的“接口”和“协议”将 AI 生成的碎片组装成可靠系统。知识管理管理文档、代码库和设计图。管理提示词、AI 会话上下文、生成的代码片段及其元数据如生成原因、版本、评估结果。3. 应对策略以 Notion 为例构建你的“理解增强”工作流工具不是万能的但好的工具能固化思维模型。Notion 作为一个高度灵活的知识管理工具非常适合用来构建应对“理解瓶颈”的个人或团队工作流。下面我们将一个功能开发的全生命周期为例展示如何实践。3.1 环境与思想准备核心思想将 Notion 作为 AI 辅助开发的“中央控制台”和“第二大脑”而不是零散的记事本。这里记录的不是最终代码而是决策过程、上下文和知识链接。基本设置创建一个名为AI-Dev-Workspace的 Notion 页面作为总入口。在内部建立几个核心数据库Database项目看板管理开发任务。提示词库积累和优化针对不同场景的提示词。代码片段库保存和分类 AI 生成的有价值的代码并附上上下文。决策日志记录为什么选择某种实现方案AI 提供了哪些选项最终依据是什么。3.2 核心流程拆解从需求到可维护代码我们以开发一个“用户上传图片并压缩”的 API 为例。步骤一需求澄清与任务分解在 Notion 中完成不要在聊天框里直接开始。先在 Notion 的项目看板中创建一个任务卡标题为“实现图片上传压缩 API”。在卡片内部使用/code块或分点描述清晰地定义输入HTTP POST 请求multipart/form-data字段image。输出JSON包含压缩后图片的 URL 和元数据大小、格式。非功能性需求支持常见格式JPG, PNG最大尺寸限制压缩比可配置异步处理。AI 辅助子任务生成 Flask/FastAPI 的图片上传端点代码。生成使用 Pillow 库进行图片压缩的代码。生成将压缩图片保存到云存储如 S3的代码。生成相关的配置说明如环境变量。这一步的价值你强迫自己进行了系统思考为 AI 提供了结构化的、无歧义的上下文。这本身就是对“需求理解瓶颈”的突破。步骤二结构化提示与生成链接 Notion 与 AI 工具现在不要将整个任务卡扔给 AI。而是针对子任务 1从你的提示词库中找到一个“生成 RESTful API 端点”的优质提示词模板并填入当前项目的具体参数。在 Notion 中创建一个临时页面标题为“【任务1】上传端点生成记录”然后开始与 AI如 ChatGPT对话你的提示词从 Notion 复制过去你是一个经验丰富的 Python 后端工程师。请为以下需求生成 FastAPI 代码。 项目上下文我们正在构建一个图片处理服务。 具体任务创建一个图片上传端点。 详细要求 1. 路径为 /upload方法 POST。 2. 接收 multipart/form-data 格式的 image 文件字段。 3. 进行基础验证文件大小不超过 10MB类型仅限 [image/jpeg, image/png]。 4. 暂时将文件保存到服务器的临时目录路径可配置。 5. 返回一个 JSON格式为 {status: success, message: 文件已接收, filename: xxx}。 6. 请包含必要的异常处理如文件过大、类型错误并返回合适的 HTTP 状态码。 7. 在代码中添加清晰的注释。 请只输出最终的代码块。AI 生成代码后将其复制回Notion 的这个临时页面中粘贴为代码块。并在代码块下方记录使用的 AI 模型和提示词版本。生成时间。你的初步审查笔记例如“异常处理逻辑完整但临时目录路径最好从环境变量读取已标记 TODO”。步骤三审查、集成与知识沉淀回到 Notion这是克服“代码理解瓶颈”的关键。不要在 IDE 里直接使用生成的代码。静态审查在 Notion 页面中仔细阅读生成的代码。用评论功能或高亮标记出你理解有疑问、觉得需要优化或存在潜在风险的地方。创建代码片段库条目如果这个上传代码的模式具有通用性例如验证逻辑将其保存到代码片段库中。属性可以包括语言Python、框架FastAPI、功能分类文件上传、依赖Pillow、以及关键的提示词上下文。这样下次类似需求你可以直接从这个库关联的提示词开始。更新决策日志在项目主页面记录为什么选择 FastAPI 而不是 Flask为什么这样设计验证逻辑。如果 AI 提供了其他方案比如用streaming处理大文件也记录下来并说明否决原因。步骤四组装与系统测试跳出 Notion但保持链接将审查和修正后的代码从 Notion 复制到你的 IDE 项目中。然后重复步骤二和步骤三完成子任务 2图片压缩和 3云存储。当所有模块代码就绪在本地运行测试。如果测试失败或发现集成问题将错误信息和你的调试过程记录回 Notion 的对应任务页面。例如“发现压缩模块与上传模块的临时文件路径不一致已修复。根本原因提示词中未明确要求路径变量名统一。”这个记录极其宝贵它帮助你迭代提示词并沉淀了“AI 协同开发时常见的集成陷阱”这类隐性知识。3.3 完整示例一个 Notion 任务页面的样子# 任务[API-002] 实现图片上传压缩端点 **状态**进行中 **关联项目**图片处理微服务 **创建日期**2023-10-27 ## 1. 需求定义 - 输入POST /upload, multipart/form-data (image) - 输出JSON {“url”: “”, “size”: 1024, “format”: “jpg”} - 约束≤10MB, JPG/PNG, 压缩至宽度≤1200px ## 2. AI 生成与审查记录 ### 2.1 子任务FastAPI 上传端点 **提示词ID**PROMPT#FASTAPI_FILE_UPLOAD_V2 **生成模型**GPT-4 **生成时间**2023-10-27 14:30 python # 文件app/api/upload.py from fastapi import FastAPI, File, UploadFile, HTTPException import os from pathlib import Path import shutil app FastAPI() # TODO: 从环境变量读取 TEMP_DIR Path(./tmp) TEMP_DIR.mkdir(exist_okTrue) ALLOWED_TYPES [image/jpeg, image/png] MAX_SIZE 10 * 1024 * 1024 # 10MB app.post(/upload) async def upload_image(image: UploadFile File(...)): # 1. 验证文件类型 if image.content_type not in ALLOWED_TYPES: raise HTTPException(status_code400, detailUnsupported file type.) # 2. 验证文件大小注意这里需要读取内容对于大文件需优化 contents await image.read() if len(contents) MAX_SIZE: raise HTTPException(status_code400, detailFile too large.) # 3. 保存临时文件 file_location TEMP_DIR / image.filename with open(file_location, wb) as f: f.write(contents) # 4. 返回响应后续将触发压缩任务 return { status: success, message: File uploaded successfully., filename: image.filename, path: str(file_location) }审查笔记✅ 基础验证和异常处理完整。⚠️await image.read()会读取整个文件到内存不符合MAX_SIZE验证的初衷。对于大文件应使用spooled特性或流式检查。已标记为待优化。 已将TEMP_DIR标记为 TODO需改为从配置读取。决策当前版本可用于开发测试性能优化放入下一个迭代。2.2 子任务Pillow 图片压缩类似结构包含提示词、代码和审查笔记3. 集成与测试记录2023-10-27 16:00将上传和压缩模块集成。发现压缩模块需要文件路径但上传模块返回的是Path对象。已修复统一使用str(path)传递。2023-10-27 16:30测试通过。上传 JPG 文件成功返回压缩后的 URL。4. 关联知识链接到提示词库[PROMPT#FASTAPI_FILE_UPLOAD_V2]链接到代码片段库[通用文件验证逻辑]链接到决策日志[关于异步处理 vs 同步处理的选择]## 4. 常见问题与排查思路 在实践上述工作流时你可能会遇到以下典型问题 | 问题现象 | 可能原因 | 排查方式 | 解决方案 | | :--- | :--- | :--- | :--- | | AI 生成的代码跑不通但看起来没问题。 | 1. 缺少关键依赖导入。br2. 使用了过时或错误的 API。br3. 上下文理解偏差如 Python 版本。 | 1. 检查代码块顶部的 import 语句。br2. 将错误信息反馈给 AI要求其检查。br3. 在提示词中明确指定技术栈和版本。 | **永远先在隔离环境测试**。将提示词细化例如“请为 **Python 3.9** 和 **FastAPI 0.104** 生成代码。” | | 不同 AI 会话生成的代码风格不一致难以整合。 | 提示词缺乏对代码风格和项目规范的约束。 | 对比不同会话的提示词差异。 | 在提示词库中建立**项目专用提示词模板**开头固定包含“请遵循本项目规范使用 Black 格式化类型注解错误处理用自定义异常类等。” | | 忘记了某个功能当初为什么这么实现。 | 决策过程没有记录只有最终代码。 | 回溯 Git 提交历史但信息有限。 | 强制要求任何由 AI 辅助实现的功能其 Notion 任务页面必须包含“决策日志”部分记录备选方案和选择理由。 | | 找不到之前用过的一个很好的提示词或代码片段。 | 知识资产散落在各处。 | 在各个聊天历史、文件中盲目搜索。 | 建立并严格执行 Notion 提示词库和代码片段库的积累和分类习惯。每次生成有价值内容后花 2 分钟进行保存和关联。 | ## 5. 最佳实践与工程建议 1. **提示词工程化**不要每次重写提示词。将你的提示词库当成代码库来维护进行版本化、分类如“代码生成”、“代码审查”、“文档生成”、“调试”并持续迭代优化。 2. **上下文管理**在与 AI 对话时主动提供结构化上下文。可以将 Notion 页面的大纲、接口定义、错误日志直接作为提示词的一部分。这能显著降低“意图传递损耗”。 3. **代码所有权****AI 是副驾驶你才是机长**。你必须对最终进入代码库的每一行负责。这意味着严格的审查、测试和重构。AI 生成代码的初始版本应被视为“初稿”。 4. **聚焦 AI 的优势与劣势**让 AI 去做它擅长的事生成样板代码、编写单元测试、解释复杂代码、提供多种实现方案。把系统设计、架构决策、业务逻辑整合和最终的质量把关留给自己。 5. **工具链集成**探索将 Notion 与开发流程更深集成。例如使用 Notion API 将任务状态同步到 GitHub Issues或将 CI/CD 失败日志自动回写到对应的 Notion 任务页面。 6. **团队协同**在团队中共享 Notion 工作区。统一的提示词库和决策日志能极大降低团队认知负荷让新成员快速理解项目为何如此构建避免重复踩坑。 ## 6. 总结 Geoffrey Litt 所说的“理解成为新的瓶颈”是一个深刻的行业洞察。它告诉我们在 AI 时代开发者的核心价值正在从“编码实现”向“精准定义问题、管理复杂性和保障系统可靠性”迁移。 应对这一挑战单纯学习更炫酷的提示词技巧是远远不够的。你需要构建一个外化的、系统化的“理解增强”工作流。本文以 Notion 为例展示了一种将思考过程、决策逻辑和 AI 交互记录进行结构化管理的方法。这套方法的本质是 * **将隐性的“理解”过程显性化**通过需求澄清、决策日志。 * **将碎片化的 AI 输出资产化**通过提示词库、代码片段库。 * **将线性的开发流程迭代化**通过生成-审查-记录-优化的闭环。 开始行动吧。不必追求一步到位打造完美体系可以从下一个功能开发任务开始尝试在 Notion 中创建一个任务页面并遵循“澄清 - 生成 - 审查 - 记录”的流程。当你积累了几十个这样的页面后你会发现自己对项目的“理解”达到了一个新的高度而 AI 也将真正从一个时灵时不灵的“魔术盒”变成一个稳定可靠的“动力倍增器”。