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”，存在几个致命缺陷：

1. 信息单点爆发：试图在一个问题里塞进所有要求（鉴权方式、数据库模型、错误处理、响应格式），导致AI要么忽略部分要求，要么生成臃肿且难以维护的代码块。
2. 缺乏验证闭环：生成代码后，没有内置的检查点。你只能人工阅读代码，凭经验判断对错，效率低下且容易看走眼。
3. 上下文易丢失：在多轮对话中，重要的前期决策（如“我们决定使用JWT而非Session”）可能被后续对话淹没，AI在回答新问题时可能“忘记”之前的约定。
4. 无法积累经验：每次遇到类似任务（如“分页查询”），都需要重新组织语言描述，无法沉淀为可复用的资产。

2.2 “未知项管理Skill”的范式转换

我的Skill体系，正是为了突破这些局限。它的核心不是“如何问得更好”，而是“如何系统地识别并填充所有未知信息”。其运作范式基于一个简单的认知：任何编程任务，都可以分解为“已知条件”和“未知项”。我们的工作，就是设计一个流程，引导AI（和开发者自己）协同探索，将这些“未知项”逐一转化为“已知条件”。

这个流程通常包含四个阶段：

1. 需求结构化澄清：将模糊的自然语言需求，转化为结构化的技术规格说明书。这不仅仅是翻译，更是通过一系列预设问题，挖掘出隐藏的边界条件和业务规则。
2. 测试驱动设计：在写一行实现代码之前，先与AI共同定义验收标准（测试用例）。这相当于为AI的代码生成提供了“目标函数”，极大提高了生成代码的准确性和可靠性。
3. 分步实现与审查：将大任务拆解为小步骤，每完成一步，都进行一次轻量级的“AI自审查”或“交叉审查”，确保代码符合之前约定的所有规格。
4. 上下文封装与复用：将整个任务解决过程中形成的有效提示、决策记录和验证方法，打包成一个命名的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 模块三：分步实现与即时审查流水线

现在，我们有了清晰的规格（模块一）和验收标准（模块二）。这个模块负责以“小步快跑”的方式生成实现代码，并在每一步植入质量检查点。

实操步骤：

1. 任务分解：Skill将大的开发任务（如“实现Product的CRUD API”）分解为原子性子任务，并排序。例如：
   • 子任务1：创建Product实体类（JPA Entity）。
   • 子任务2：创建ProductRepository接口。
   • 子任务3：创建ProductService接口及实现类。
   • 子任务4：创建ProductController，实现GET /api/products端点。
   • 子任务5：实现POST /api/products端点。
   • ...以此类推。
2. 循环执行：对每个子任务，执行一个“生成-审查”循环：
   • 生成：Skill将当前子任务、规格说明书、已生成的相关代码（如实体类）作为上下文，发送给AI，要求生成代码。
   • 审查：代码生成后，Skill自动触发一个内置的“代码审查子Skill”。这个子审查Skill会检查：代码风格是否一致（如命名规范）、是否使用了项目约定的库、是否有明显的安全漏洞（如SQL注入风险）、是否遵循了规格中的业务规则。
   • 反馈与修正：如果审查发现问题，Skill会将问题列表和修正要求反馈给AI，要求其重新生成或修正代码。这个过程可以迭代1-2次。
3. 集成测试：当一个逻辑模块（如整个Controller）的所有子任务完成后，Skill会引导AI运行该模块对应的单元测试（来自模块二），确保所有测试通过。

这个流水线的精髓在于“即时反馈”。它把传统开发中后期才进行的代码审查和测试环节，提前并自动化地嵌入到生成过程中，确保了每一段新生代码的质量基线。

3.4 模块四：Skill封装与上下文管理器

这是实现“可复用”的关键。一个任务完成后，所有有价值的“过程资产”需要被妥善保存。

封装内容：

1. 核心提示模板：模块一中使用的需求澄清模板。
2. 领域特定问题集：针对该领域（如“API开发”、“React组件”）的自动追问问题列表。
3. 任务分解策略：模块三中使用的任务分解逻辑。
4. 审查规则集：内置代码审查子Skill所依据的规则（如“必须使用@Transactional注解”、“React组件必须使用TypeScript”）。
5. 示例输入与输出：一次成功的任务执行记录，作为未来参考的范例。

调用方式：在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 5

4.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接口** - 扩展`JpaRepository<Entity, Long>`。 - 如有唯一字段查询，声明`findByXxx`方法。 - 如为软删除，考虑使用`@Query`覆盖默认删除方法。 ...（后续子任务：Service接口及实现、DTO、Controller、全局异常处理等，结构类似） ### 阶段C：代码自审查规则（在每个子任务后执行） 当我发出“审查”指令时，请根据以下规则检查刚生成的代码： 1. **风格一致性**：缩进为4个空格；类名大驼峰，变量小驼峰；常量全大写。 2. **框架规范**：Controller使用`@RestController`和`@RequestMapping`；Service使用`@Service`；事务管理使用`@Transactional`。 3. **安全与健壮性**：Controller方法必须有`@Valid`注解验证输入；Service方法需进行必要的空值检查；Repository查询考虑分页（`Pageable`）。 4. **业务规则符合性**：核对生成的代码是否完全实现了【规格说明书】中定义的所有业务规则（如唯一性约束、软删除逻辑）。 5. **测试覆盖**：确保生成的实现代码能够通过阶段A中编写的单元测试（逻辑上可行）。 如果审查发现问题，请直接输出修正后的代码片段。

4.4 第四步：使用与迭代

在实际的Cursor对话中，我的操作流程如下：

1. 输入!crud，然后粘贴填写好的输入模板。
2. 根据Skill的追问逻辑，逐一回答AI（或我手动模拟的追问）提出的问题。
3. 将最终确认的规格说明书发送给AI，并附上核心执行提示的开头部分，然后发出指令：“请开始执行阶段A：生成单元测试。”
4. AI生成测试代码。我检查无误后，回复“继续，开始子任务1”。
5. AI生成实体类代码。我回复“审查”。AI根据审查规则进行自我检查并输出结果。
6. 重复“继续” -> “审查”的循环，直到所有代码生成完毕。
7. 最后，运行生成的单元测试，进行最终验证。

踩坑实录：

• 坑1：AI的“创造性”偏离：有时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，了解团队的编码风格（如是否使用Lombok，DTO命名习惯等）。”然后让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体系的过程中，我和团队遇到了不少问题。这里列出一个速查表，希望能帮你绕过这些坑。

最后一点个人体会：构建和管理“未知项管理Skill”本身，是一项元技能。它强迫你将自己的开发经验、设计模式、踩坑记录进行结构化的沉淀。这个过程，本身就是对自身知识体系的极佳梳理。最初，你可能会觉得设计这些提示和流程很繁琐，但当你发现，新来的同事也能通过调用Skill，生成出符合资深工程师标准的代码时；当你自己能在几分钟内，搭建起一个需要半天才能手动完成的服务骨架时，你就会明白，这份投入是百倍回报的。AI编程的未来，不属于最会提问的个人，而属于最善于将知识转化为可复用协作流程的团队。