1. 项目概述从“AI编程助手”到“AI编程伙伴”的进化如果你和我一样深度使用过Cursor、Claude Code、GitHub Copilot这类AI编程工具一定经历过这样的场景你向AI描述了一个复杂功能它“唰唰唰”地生成了一大段看似完美的代码。你满心欢喜地运行结果要么是编译报错要么是逻辑跑偏要么是缺失了某个关键的业务模块。你不得不回头像挤牙膏一样一遍遍地追问“这里需要处理异常吗”“那个API的返回值结构是什么”“这个函数应该放在哪个模块”整个过程与其说是“编程”不如说是一场充满挫败感的“猜谜游戏”。问题的核心就在于“未知项”。在传统编程中需求、接口、边界条件这些信息要么在文档里要么在开发者的脑子里。但在AI编程的对话流中这些信息是零散、模糊且动态的。AI没有“上下文”除非你明确告诉它。这个“告诉”的过程如果全靠临场发挥、即兴提问效率极低且容易遗漏。“未知项管理”就是为解决这个问题而生。它不是某个具体的AI工具功能而是一套将人类开发者的领域知识、设计意图和验证逻辑结构化地注入AI协作流程的方法论。我花了大量时间将这套方法论从零散的实践打磨成了一个名为“可复用Skill”的体系。你可以把它理解为一套标准化的“提问模板”或“协作协议”但它远比模板更强大。它封装了针对特定编程任务如“需求澄清”、“编写测试驱动开发用例”、“进行代码审查”、“设计UI组件”的最佳提问策略、验证步骤和上下文构建方法。一旦创建就可以像调用函数一样在任何AI编程会话中一键复用将随机的、低效的对话转变为可预测、高质量、可追溯的工程化协作。简单说这个Skill让你从“向AI提问的人”升级为“为AI设定清晰目标的指挥官”。接下来我将彻底拆解这个Skill的构建思路、核心模块、实操方法以及我踩过的所有坑让你不仅能理解更能直接复制这套体系打造你自己的AI编程增效武器库。2. 核心理念为什么“管理未知”比“生成代码”更重要在深入细节之前我们必须统一思想AI编程的瓶颈从来不是AI的代码生成能力而是我们与AI之间信息传递的保真度。Codex、Claude 3、GPT-4等大模型在语法、算法甚至设计模式上已经表现出色但它们本质上是“概率预测机”而非“理解执行机”。它们会根据你提供的上下文预测最可能的下一个token代码段。如果你的上下文模糊、矛盾或残缺那么生成的代码自然也是“垃圾进垃圾出”。2.1 传统提示Prompt的局限性我们常用的提示方式比如“帮我写一个用户登录的REST API”存在几个致命缺陷信息单点爆发试图在一个问题里塞进所有要求鉴权方式、数据库模型、错误处理、响应格式导致AI要么忽略部分要求要么生成臃肿且难以维护的代码块。缺乏验证闭环生成代码后没有内置的检查点。你只能人工阅读代码凭经验判断对错效率低下且容易看走眼。上下文易丢失在多轮对话中重要的前期决策如“我们决定使用JWT而非Session”可能被后续对话淹没AI在回答新问题时可能“忘记”之前的约定。无法积累经验每次遇到类似任务如“分页查询”都需要重新组织语言描述无法沉淀为可复用的资产。2.2 “未知项管理Skill”的范式转换我的Skill体系正是为了突破这些局限。它的核心不是“如何问得更好”而是“如何系统地识别并填充所有未知信息”。其运作范式基于一个简单的认知任何编程任务都可以分解为“已知条件”和“未知项”。我们的工作就是设计一个流程引导AI和开发者自己协同探索将这些“未知项”逐一转化为“已知条件”。这个流程通常包含四个阶段需求结构化澄清将模糊的自然语言需求转化为结构化的技术规格说明书。这不仅仅是翻译更是通过一系列预设问题挖掘出隐藏的边界条件和业务规则。测试驱动设计在写一行实现代码之前先与AI共同定义验收标准测试用例。这相当于为AI的代码生成提供了“目标函数”极大提高了生成代码的准确性和可靠性。分步实现与审查将大任务拆解为小步骤每完成一步都进行一次轻量级的“AI自审查”或“交叉审查”确保代码符合之前约定的所有规格。上下文封装与复用将整个任务解决过程中形成的有效提示、决策记录和验证方法打包成一个命名的Skill。下次遇到同类任务直接调用所有上下文自动载入。这个范式将AI编程从“一次性的艺术创作”变成了“可重复的工程过程”。下面我们进入实战环节看看如何具体构建这样一个Skill。3. Skill的核心架构与模块设计一个完整的、可复用的“未知项管理Skill”不是一个魔法咒语而是一个由多个组件构成的微型工作流。我将其设计为以下四个核心模块它们像流水线一样协同工作。3.1 模块一需求澄清引擎这是Skill的起点也是最容易出错的环节。它的目标是将用户的一句话需求扩展成一份机器AI和人都能无歧义理解的“任务工单”。实操要点输入模板化不要直接让用户描述。提供一个结构化输入框。例如对于“创建一个CRUD API”的Skill输入模板可能是【实体名称】: [例如Product] 【核心字段】: [例如id (整数主键), name (字符串非空), price (浮点数大于0), category (字符串枚举)] 【特殊业务规则】: [例如删除操作仅为软删除更新价格时需记录审计日志] 【已有技术栈】: [例如Spring Boot 3, JPA, MySQL]自动追问链根据用户输入Skill自动生成一组澄清问题。例如如果用户提到了“价格”Skill会追问“价格的精度要求是多少小数点后几位是否有货币单位是否允许为负值或零” 这些问题是我预先在Skill中埋设的“问题触发器”。输出规格说明书将收集到的所有信息整理成一份格式固定的Markdown文档作为后续所有步骤的“唯一真相源”。这份文档会包括实体定义、API端点列表方法、路径、请求/响应体示例、数据库约束、业务规则摘要。注意这个模块的成功关键在于你对特定领域如Web后端、前端组件、数据管道的“常见未知项”有深刻理解。你需要预先穷举这个领域里新手和老手都容易忽略的细节。我建议从你最熟悉的领域开始构建第一个Skill。3.2 模块二测试驱动开发引导器在获得清晰的规格后最反直觉但最有效的一步是不直接写实现先写测试。这个模块引导AI根据规格说明书生成一套完整的、可执行的测试用例。实操要点测试框架约定在Skill中硬编码你团队使用的测试框架如JUnit 5、 pytest、Jest。这确保了生成代码的即用性。场景化用例生成引导AI为每个API端点或函数生成“成功路径”、“失败路径”如无效输入、资源不存在、权限不足和“边界条件”的测试用例。例如对于“创建产品”API除了测试成功创建还必须测试“名称为空”、“价格为负”、“重复产品名”等情况。测试数据工厂为了避免测试数据过于随意Skill会引导AI创建一个简单的测试数据工厂或Fixture确保测试数据的一致性和可维护性。输出一整套包含描述性测试名称和清晰断言语句的测试代码文件。这些测试最初当然是“红色”失败状态因为它们对应的实现还不存在。我的心得很多开发者觉得让AI先写测试多此一举。但实测下来这步有奇效。第一它迫使AI和你自己在思考“如何实现”之前先彻底想清楚“什么是正确”。第二这些测试用例成为了后续代码生成的“黄金标准”AI在编写实现代码时会潜意识地向通过这些测试的方向靠拢。第三当AI生成实现后直接运行测试能立刻得到客观的通过/失败反馈比人眼审查代码快得多、准得多。3.3 模块三分步实现与即时审查流水线现在我们有了清晰的规格模块一和验收标准模块二。这个模块负责以“小步快跑”的方式生成实现代码并在每一步植入质量检查点。实操步骤任务分解Skill将大的开发任务如“实现Product的CRUD API”分解为原子性子任务并排序。例如子任务1创建Product实体类JPA Entity。子任务2创建ProductRepository接口。子任务3创建ProductService接口及实现类。子任务4创建ProductController实现GET /api/products端点。子任务5实现POST /api/products端点。...以此类推。循环执行对每个子任务执行一个“生成-审查”循环生成Skill将当前子任务、规格说明书、已生成的相关代码如实体类作为上下文发送给AI要求生成代码。审查代码生成后Skill自动触发一个内置的“代码审查子Skill”。这个子审查Skill会检查代码风格是否一致如命名规范、是否使用了项目约定的库、是否有明显的安全漏洞如SQL注入风险、是否遵循了规格中的业务规则。反馈与修正如果审查发现问题Skill会将问题列表和修正要求反馈给AI要求其重新生成或修正代码。这个过程可以迭代1-2次。集成测试当一个逻辑模块如整个Controller的所有子任务完成后Skill会引导AI运行该模块对应的单元测试来自模块二确保所有测试通过。这个流水线的精髓在于“即时反馈”。它把传统开发中后期才进行的代码审查和测试环节提前并自动化地嵌入到生成过程中确保了每一段新生代码的质量基线。3.4 模块四Skill封装与上下文管理器这是实现“可复用”的关键。一个任务完成后所有有价值的“过程资产”需要被妥善保存。封装内容核心提示模板模块一中使用的需求澄清模板。领域特定问题集针对该领域如“API开发”、“React组件”的自动追问问题列表。任务分解策略模块三中使用的任务分解逻辑。审查规则集内置代码审查子Skill所依据的规则如“必须使用Transactional注解”、“React组件必须使用TypeScript”。示例输入与输出一次成功的任务执行记录作为未来参考的范例。调用方式在AI编程助手的对话中你只需要输入类似!skill create-crud-api --entity Product的指令整个Skill包包括所有预设的上下文、提示、流程就会被激活。AI会立刻进入“需求澄清引擎”模式开始向你提问。你无需再回忆上次是怎么一步步问出来的。技术实现参考在Cursor中你可以利用其“自定义指令”和“上下文文件”功能来模拟。更高级的做法是利用其API或类似Windscope这类AI工作流平台将上述流程图形化、自动化。核心是建立一个“Skill库”目录每个Skill是一个文件夹里面包含prompt.md主提示、questions.md追问集、workflow.yaml任务流定义等文件。4. 实战演练构建一个“Spring Boot CRUD API生成”Skill光说不练假把式。让我们以最常见的后端任务为例手把手构建一个Skill。假设我们团队主要使用Spring Boot和JPA。4.1 第一步定义Skill的元信息与输入模板创建一个名为skill_springboot_crud.md的文件开头定义Skill的基本信息。# Skill: Spring Boot CRUD API Generator **描述**: 自动化生成符合团队规范的Spring Boot JPA CRUD REST API代码包含实体、仓库、服务、控制器、DTO及完整单元测试。 **触发指令**: !crud **版本**: 1.0 ## 输入模板 请提供以下信息以生成API 【实体名英文单数】: e.g., Product 【实体名中文】: e.g., 产品 【核心字段列表】: 每行一个格式字段名: 类型 [约束] // 注释 示例 id: Long // 主键自增 name: String NotBlank // 产品名称不可为空 price: BigDecimal DecimalMin(\0.0\) // 价格大于等于0 category: String // 分类 inStock: Boolean // 是否有库存 【特殊业务规则】: 1. 删除是否为逻辑删除软删除[是/否] 2. 创建/更新时是否需要审计日志记录操作人、时间[是/否] 3. 是否有唯一性约束字段[字段名] 【技术栈】: Spring Boot 3.x, Spring Data JPA, H2/MySQL, MapStruct, Lombok, JUnit 54.2 第二步编写需求澄清引擎的追问逻辑在同一个文件中或者一个单独的clarification_questions.md中定义基于用户输入的自动追问逻辑。这部分需要一些简单的“模式匹配”思维。## 自动追问逻辑 根据用户输入的【核心字段列表】和【特殊业务规则】自动生成以下追问 1. 对于每个 String 类型字段 * 追问字段【{字段名}】的最大长度限制是多少默认值是多少 2. 对于每个 BigDecimal 或数值类型字段 * 追问字段【{字段名}】的精度和小数位数分别是多少例如总位数10小数位2 3. 如果【特殊业务规则】中“逻辑删除”为“是” * 追问软删除的字段名用什么建议使用‘deleted’Boolean类型或‘deletedAt’LocalDateTime类型。 4. 如果【特殊业务规则】中“审计日志”为“是” * 追问审计日志需要记录哪些字段通常包括‘createdBy’, ‘createdDate’, ‘lastModifiedBy’, ‘lastModifiedDate’。请确认。 5. 对于【实体名】 * 追问该实体的REST API路径前缀是什么建议使用‘/api/v1/{实体名复数小写}’例如‘/api/v1/products’。在实际操作中当用户触发!crud并填写初始模板后我会手动或通过一个简单脚本根据这些规则将追问列表呈现给用户并收集答案。最终所有这些信息会汇总成一份最终的规格说明书。4.3 第三步编写TDD引导器与实现流水线提示这是Skill最核心的部分是一个给AI看的“操作规程”。我把它放在core_prompt.md中。这个提示非常长且详细因为它直接指导AI的行为。# 核心执行提示 你是一个专业的Spring Boot开发专家。请严格按照以下步骤和规范为用户生成CRUD API代码。 ## 上下文信息 【规格说明书已就绪包含实体、字段、规则、API路径等信息】 ## 你的任务流程 ### 阶段A生成单元测试测试驱动开发 **目标**为每个API端点GET /{id}, GET /, POST, PUT, DELETE生成JUnit 5单元测试。 **要求** 1. 使用SpringBootTest进行集成测试或使用WebMvcTest专注Controller层根据复杂度选择。 2. 为每个端点编写至少3个测试方法一个成功测试两个边界/失败测试如无效ID、无效请求体、重复唯一键冲突。 3. 使用MockMvc进行HTTP请求模拟。 4. 测试数据使用BeforeEach方法统一设置确保一致性。 5. 测试方法命名遵循shouldReturnXXX_whenYYY格式。 **现在请先生成针对【实体名】的完整单元测试代码。在生成后我会提供‘继续’指令。** ### 阶段B分步生成实现代码 收到“继续”指令后请按顺序执行以下子任务。每个子任务完成后我会要求你进行“自审查”。 **子任务1生成JPA实体类** - 使用Entity注解。 - 根据规格正确设置字段类型、约束NotBlank, Column等。 - 如果启用逻辑删除添加Where注解或相应字段。 - 如果启用审计使用EntityListeners(AuditingEntityListener.class)。 - 生成完整的Getter/Setter或使用Lombok Data。 - 生成equals()和hashCode()方法重点包含业务唯一键字段。 生成后我将触发审查点检查注解完整性、字段类型匹配、Lombok使用是否正确 **子任务2生成Repository接口** - 扩展JpaRepositoryEntity, Long。 - 如有唯一字段查询声明findByXxx方法。 - 如为软删除考虑使用Query覆盖默认删除方法。 ...后续子任务Service接口及实现、DTO、Controller、全局异常处理等结构类似 ### 阶段C代码自审查规则在每个子任务后执行 当我发出“审查”指令时请根据以下规则检查刚生成的代码 1. **风格一致性**缩进为4个空格类名大驼峰变量小驼峰常量全大写。 2. **框架规范**Controller使用RestController和RequestMappingService使用Service事务管理使用Transactional。 3. **安全与健壮性**Controller方法必须有Valid注解验证输入Service方法需进行必要的空值检查Repository查询考虑分页Pageable。 4. **业务规则符合性**核对生成的代码是否完全实现了【规格说明书】中定义的所有业务规则如唯一性约束、软删除逻辑。 5. **测试覆盖**确保生成的实现代码能够通过阶段A中编写的单元测试逻辑上可行。 如果审查发现问题请直接输出修正后的代码片段。4.4 第四步使用与迭代在实际的Cursor对话中我的操作流程如下输入!crud然后粘贴填写好的输入模板。根据Skill的追问逻辑逐一回答AI或我手动模拟的追问提出的问题。将最终确认的规格说明书发送给AI并附上核心执行提示的开头部分然后发出指令“请开始执行阶段A生成单元测试。”AI生成测试代码。我检查无误后回复“继续开始子任务1”。AI生成实体类代码。我回复“审查”。AI根据审查规则进行自我检查并输出结果。重复“继续” - “审查”的循环直到所有代码生成完毕。最后运行生成的单元测试进行最终验证。踩坑实录坑1AI的“创造性”偏离有时AI会“自作主张”添加一些规格中没有的字段或逻辑。解决方案在审查规则中强调“严格遵循规格说明书”并在每个子任务开始时都重新附上关键的规格摘要。坑2上下文超长多轮对话后上下文会非常长导致AI忘记最早的要求。解决方案Skill设计为“分阶段、小上下文”模式。每个阶段只提供该阶段必需的信息并在关键节点如审查时重新注入核心规则。坑3技术栈版本差异AI可能生成基于旧版本Spring Boot的代码。解决方案在核心提示的“技术栈”部分明确指定版本号如Spring Boot 3.2.0并给出关键注解的示例。5. 高级技巧让Skill更智能、更强大基础Skill能解决80%的重复性问题。但要追求极致效率还需要一些进阶玩法。5.1 实现“动态上下文感知”一个死板的Skill在遇到复杂项目时可能不够用。我们可以让它具备简单的感知能力。项目结构嗅探在Skill开始时让AI先“看看”项目里已有的代码。你可以提示它“请分析当前项目pom.xml或build.gradle确认依赖版本查看已有的Entity或Controller了解团队的编码风格如是否使用LombokDTO命名习惯等。”然后让Skill根据嗅探到的信息动态调整其生成规则。决策树集成对于“特殊业务规则”中的问题可以设计成决策树。例如用户选择“需要权限控制”Skill可以进一步追问“权限控制粒度是方法级(PreAuthorize)还是API级使用的权限框架是Spring Security还是Shiro”5.2 构建“Skill组合”与“流水线”复杂的开发任务往往由多个简单任务组成。Skill组合你可以创建“数据库迁移Skill”、“API文档生成Skill”、“Dockerfile生成Skill”。然后在一个“新微服务初始化”的Master Skill中按顺序调用这些子Skill一键完成从数据库到部署配置的全套工作。条件化流水线在核心提示中可以加入条件判断。例如“如果【实体字段】超过15个则自动建议并生成分页查询API如果涉及金额字段则建议并生成财务精度计算工具类。”5.3 建立团队共享Skill库与版本管理Skill的真正价值在于团队复用。共享库在团队内部建立Git仓库来管理Skill。每个Skill一个目录包含提示文件、示例和文档。新成员入职先学习团队Skill库能快速统一代码风格和质量标准。版本迭代Skill不是一成不变的。当团队引入新技术如从Spring Boot 2升级到3或总结出新的最佳实践时需要更新Skill。像管理代码一样为Skill添加版本号、更新日志并进行同行评审。6. 常见问题与排查技巧实录在推广和使用这套Skill体系的过程中我和团队遇到了不少问题。这里列出一个速查表希望能帮你绕过这些坑。问题现象可能原因排查与解决思路AI生成的代码完全跑偏不符合预期1. 需求澄清阶段信息遗漏或歧义。2. 核心提示中的技术栈描述与AI模型训练数据有偏差。3. 上下文过长AI丢失了早期关键指令。1.回查规格书逐项核对AI输出与规格说明书是否一致。强化澄清阶段的追问。2.细化技术栈在提示中提供更精确的依赖版本和代码片段示例。3.重置对话开启新对话只携带最精简、最必要的上下文重新执行Skill。Skill流程执行到一半卡住AI不理解下一步1. 核心提示中的流程指令过于复杂或模糊。2. AI在某个子任务上“钻牛角尖”陷入循环。1.简化指令将“阶段A、B、C”拆分成更独立的对话回合。使用更明确的指令如“现在请生成Entity类代码”。2.人工干预当AI陷入循环时直接给出正确代码或明确命令它跳过当前步骤。事后反思并优化提示避免该模糊点。生成的代码质量参差不齐有时好有时坏1. AI模型本身的不确定性随机性。2. 审查规则不够具体无法捕捉到所有质量问题。1.设置温度参数如果所用AI工具支持将“温度”Temperature调低如0.2降低随机性使输出更确定、可重复。2.强化审查在审查规则中加入更多具体检查项如“必须使用Slf4j注解记录日志”、“DTO类必须实现Serializable”。提供反面代码示例。团队成员不愿使用觉得不如直接问方便1. Skill的初始使用成本高需要填写模板。2. 未看到即时收益觉得是负担。3. Skill覆盖的场景不够。1.降低门槛提供最常用Skill的“快速模板”或开发简单的UI表单来收集输入。2.展示价值组织一次对比演示用传统随机提问 vs 用Skill在相同时间内完成同一个复杂功能对比代码完整度和质量。3.由点及面先在一个最痛苦、最重复的场景如生成增删改查API推广让大家尝到甜头再逐步扩展。最后一点个人体会构建和管理“未知项管理Skill”本身是一项元技能。它强迫你将自己的开发经验、设计模式、踩坑记录进行结构化的沉淀。这个过程本身就是对自身知识体系的极佳梳理。最初你可能会觉得设计这些提示和流程很繁琐但当你发现新来的同事也能通过调用Skill生成出符合资深工程师标准的代码时当你自己能在几分钟内搭建起一个需要半天才能手动完成的服务骨架时你就会明白这份投入是百倍回报的。AI编程的未来不属于最会提问的个人而属于最善于将知识转化为可复用协作流程的团队。