1. 从“未知”到“可控”：AI编程中的核心痛点与我的解法

如果你最近也在用Cursor、Claude Code或者各种AI编程助手，大概率经历过这种场景：你给AI提了一个需求，它噼里啪啦生成了一堆代码，乍一看逻辑清晰，功能完整。你满心欢喜地运行，结果要么是报了一堆你看不懂的依赖错误，要么是功能跑起来和你想的完全不是一回事。更常见的是，AI生成的代码里，夹杂着一些它“自以为”存在，但实际上你项目里根本没有的模块、函数或者配置文件。这些“幽灵代码”就像埋下的地雷，让你在后续的集成和调试中苦不堪言。

这就是典型的“未知项管理”问题。AI不是全知全能的，它基于训练数据中的模式进行生成，当你的项目上下文、技术栈细节或业务逻辑存在它未曾“见过”或无法准确推断的部分时，它就会创造性地“捏造”一些内容来填补空白。这些被捏造出来的、与实际情况不符的“未知项”，是阻碍AI编程从“玩具”走向“生产力工具”的最大障碍之一。

我花了大量时间与各种AI编程工具“搏斗”，从最初的惊喜到中间的烦躁，再到最后的系统性思考。我发现，与其每次遇到问题再手忙脚乱地排查，不如建立一套标准化的处理流程。于是，我把这些零散的经验、验证步骤和决策逻辑，整理成了一个可复用的“Skill”——你可以把它理解为一个高度结构化、可配置的“心智模型”或“工作流检查清单”。这个Skill的核心目标，就是把AI输出中不可控的“黑盒”部分，通过一系列可执行、可验证的步骤，转化为可控、可预期的“白盒”过程。

这个Skill不只适用于某一种AI工具，它是一种元方法。无论你是用Cursor的Chat模式边聊边写，用Claude Code进行长文档分析生成，还是在Coze、Dify里搭建自动化编程工作流，甚至是集成n8n、Flowable来处理更复杂的流程，这套方法都能帮你建立起质量护栏。接下来，我就把这个Skill的完整结构、核心环节和我的实战心得拆解给你。

2. Skill核心架构：四层防御体系与标准化工作流

我构建的这个Skill，本质上是一个四层防御体系，它像漏斗一样，层层过滤AI输出中的风险。它不是要替代AI的创造力，而是为它的创造力框定一个安全的“游乐场”。

第一层：需求澄清与上下文锚定这是所有问题的起点。AI误解需求，往往是因为我们给出的指令过于模糊或充满歧义。这一层的核心是“结构化提问”和“上下文投喂”。我不会只说“帮我写一个用户登录的API”，而是会提供一份结构化的“需求说明书”：

• 输入/输出规格：明确请求体（如{username: string, password: string}）和响应体（如{code: number, token: string, userInfo: object}）的精确JSON Schema。
• 边界条件与异常：说明密码错误、用户不存在、账号被锁定等场景下应返回的HTTP状态码和错误信息。
• 技术栈约束：指明框架（如Spring Boot 3.1.5）、数据库（PostgreSQL 15）、ORM（MyBatis-Plus）、依赖注入方式等。
• 现有代码引用：如果项目中已有相关的工具类、配置类或模型类，直接贴出关键部分代码或文件路径，告诉AI“请基于此风格/此类继续开发”。

我的经验是，把AI当成一个需要详细需求文档的新同事。你给的信息越结构化、越无歧义，它“脑补”和“捏造”的空间就越小。在Coze或Dify的工作流中，这一层可以设计为一个专门的“需求解析与丰富”节点，通过表单或对话收集上述结构化信息。

第二层：测试驱动开发（TDD）先行验证这是对抗“幽灵代码”和逻辑错误最有力的武器。在让AI生成主体代码之前，我强制要求先生成测试用例。具体操作是：基于第一层澄清的需求，指令AI先为我编写单元测试或集成测试。 例如：“请为上述登录API编写Spring Boot的JUnit 5单元测试，覆盖成功登录、密码错误、用户不存在三种场景。请使用MockMvc，并假设我们已经有了UserService和JwtUtil这两个Bean。”

AI生成的测试代码本身也可能有问题，但这恰恰是它的价值所在：测试代码比业务代码更简单、更结构化。通过阅读AI写的测试，我可以立刻发现它对我项目结构的理解偏差。比如，如果它写的测试里引用了UserDao.login()方法，而我的项目实际用的是UserMapper.selectOne()，这个“未知项”在编写阶段就被暴露了。此时，我可以立即纠正：“我们使用MyBatis-Plus，请用LambdaQueryWrapper查询用户，而非UserDao。”

在Cursor或Claude Code中，这是一个独立的对话回合。在自动化工作流（如n8n）里，可以设计为一个“生成测试用例”的节点，其输出作为后续代码生成的“契约”。

第三层：生成代码的即时审查与“未知项”扫描AI生成主体代码后，不要急着运行。进入系统的、人工辅助的代码审查环节。这个审查不是泛泛地看代码风格，而是有针对性的“狩猎未知项”。我总结了一个检查清单（Checklist）：

1. 依赖扫描：逐行检查import语句或require/include。每一个引入的包、模块、文件，我都要在项目的pom.xml、package.json或go.mod中确认其是否存在，版本是否匹配。AI经常“想当然”地引入一些流行但本项目未使用的库。
2. API与函数验证：对于代码中调用的所有非原生函数、类方法，快速在项目中全局搜索，确认其是否正确定义。特别是AI经常“发明”一些看似合理的工具方法，如StringUtils.generateToken()，而实际项目可能用的是JwtUtil.createToken()。
3. 配置与路径确认：检查代码中硬编码的配置项（如数据库URLjdbc:mysql://localhost:3306/my_db）、文件路径（如/etc/app/config.yaml）、环境变量名（如getEnv("REDIS_HOST")）是否与项目实际配置一致。
4. 业务逻辑对齐：快速通读核心逻辑，判断其是否严格遵循了第一层中定义的需求规格。AI有时会添加一些“锦上添花”但未经确认的功能，或误解了某个业务规则。

这个环节在VS Code或Cursor中，可以结合侧边栏的工程文件树和全局搜索（Ctrl+Shift+F）快速完成。在Agentic Coding场景下，可以设想一个“审查Agent”，其Skill就是执行这份检查清单，并标记出所有存疑点。

第四层：集成与执行环境的安全沙箱即使通过了前三层，在最终运行前，我仍会采取隔离措施。最实用的方法是使用容器化技术。

• 本地Docker沙箱：对于新功能或改动较大的模块，我会先在一个干净的、与生产环境镜像一致（或与docker-compose.yml定义一致）的Docker容器中运行测试。命令很简单：docker run --rm -v $(pwd):/app -w /app my-project-image npm test。这能立刻暴露环境依赖类“未知项”，比如某个系统库缺失、Node.js版本不兼容等。
• CI/CD管道先行：将AI生成的代码和测试直接推送到一个特性分支，触发CI流水线（如GitHub Actions）。CI环境是纯净且标准化的，它的构建和测试失败报告，是发现环境、依赖问题最直接的反馈。这相当于让自动化系统帮你做了一次终极审查。

这四层体系，从需求输入到代码运行，形成了一个闭环的质控流程。它把一次充满不确定性的AI代码生成，拆解成了多个可监控、可干预、可回退的标准化步骤。

3. 实战推演：以“Markdown转Word报告”工作流为例

让我们用一个具体案例，看看这个Skill如何落地。假设我要构建一个自动化工作流：每周将Git仓库中的Markdown格式周报，转换为格式规范的Word文档，并邮件发送。

第一步：需求澄清与上下文锚定（应用Skill第一层）我向AI（比如在Coze工作流编辑器中配置的LLM节点）提供结构化输入：

• 输入：指定一个Git仓库目录，内含多个YYYY-MM-DD.md文件。提供其中一个文件的实际样本内容，展示其结构（如包含## 本周工作、## 问题与风险等二级标题）。
• 输出：需要生成.docx文件，要求标题为“技术部周报（YYYY年MM月DD日）”，正文部分保留Markdown的标题层级（但转为Word样式），代码块需有灰色底纹，超链接需保持可点击。
• 技术栈：使用Python语言，优先考虑python-docx库操作Word，使用markdown库进行初始解析。工作流运行环境为Ubuntu 22.04，Python 3.9。
• 约束：不能使用付费API；转换后的文档页边距设为常规，字体为宋体（中文）和Calibri（英文）。

通过这样清晰的输入，AI“捏造”一个完全不同技术栈（比如用Pandoc命令行）的可能性就大大降低。

第二步：TDD先行验证（应用Skill第二层）我要求AI先为这个转换函数的核心部分编写测试。提示词如下： “请编写一个Python单元测试（使用pytest），测试一个名为convert_md_to_docx(md_text, output_path)的函数。测试用例应包含：1. 输入包含标题、列表和代码块的Markdown文本，验证生成的docx文件存在且可读。2. 输入空字符串，应抛出ValueError。3. 验证输出路径后缀是否为.docx。”

AI可能会生成如下测试代码：

import pytest from my_converter import convert_md_to_docx import os def test_convert_md_to_docx_success(tmp_path): md_content = "# Title\n\n- item1\n- item2\n\n```python\nprint('hello')\n```" output_file = tmp_path / "test.docx" convert_md_to_docx(md_content, output_file) assert output_file.exists() # 这里AI可能会假设一个并不存在的 `read_docx_text` 函数 # assert "Title" in read_docx_text(output_file) def test_convert_md_to_docx_empty_input(): with pytest.raises(ValueError): convert_md_to_docx("", "test.docx")

看，问题立刻出现了！AI在测试中假设了一个名为read_docx_text的辅助函数来验证docx内容，但这个函数在我的上下文中并不存在。这是一个典型的“未知项”。我在审查测试时就能发现，并立即澄清：“我们不需要验证docx内部文本，只需验证文件成功创建且非空即可。请移除对read_docx_text的调用，改用os.path.getsize()检查文件大小。”

第三步：生成代码与审查（应用Skill第三层）基于修正后的测试契约，AI生成主函数代码。我的审查清单开始工作：

1. 依赖扫描：检查import。看到from docx import Document，import markdown。我需要立刻检查我的requirements.txt或虚拟环境，确认是否安装了python-docx和markdown。如果没有，这就是一个待办事项。
2. API验证：AI代码中使用了document.add_heading('周报', 0)。我需要查阅python-docx官方文档或我的记忆，确认add_heading方法的参数顺序和含义是否正确（级别0是否是最高级标题）。
3. 配置与路径：代码中可能硬编码了字体名称'SimSun'（宋体）。我需要确认，在无中文字体的Ubuntu基础镜像中，这个字体是否可用，是否需要回退到其他字体或添加字体安装步骤。
4. 逻辑对齐：检查AI是否正确处理了Markdown代码块到Word“突出显示”样式的转换逻辑，是否符合我样本中“灰色底纹”的要求。

第四步：沙箱运行（应用Skill第四层）我将AI生成的脚本、测试文件以及requirements.txt打包，在一个干净的Python 3.9 Docker容器中运行测试。命令：docker run --rm -v $(pwd):/app -w /app python:3.9-slim bash -c "pip install -r requirements.txt && pytest"。如果测试通过，说明环境依赖无误。我还可以在容器内手动运行一次转换，检查生成的Word文档格式是否符合预期。

通过这个案例，你可以看到，四层防御是如何在每一个环节拦截潜在问题的。从模糊的需求到可运行、可验证的代码，整个过程变得可控且高效。

4. 不同AI编程场景下的Skill适配与调优

我总结的这个Skill框架是通用的，但在不同的AI编程工具和场景下，侧重点和具体操作需要微调。

在Cursor/Claude Code等IDE智能助手场景下：这类工具的特点是深度集成开发环境，上下文感知能力强。Skill的应用更侧重于“对话管理”。

• 需求澄清：充分利用“选中代码后对话”的功能。在提出新需求前，先选中相关的接口定义、模型类或配置文件，让AI获得精准上下文。例如，先选中User实体类，再问“请基于这个User类，编写一个注册用户的Service方法”。
• TDD实践：可以开启一个专门的“测试对话线程”。在主线对话生成业务代码后，立即切换到测试线程，指令AI：“请为上面刚生成的UserServiceImpl.register方法编写完整的单元测试，使用Mockito模拟UserMapper。” 将业务与测试对话分离，避免上下文污染。
• 审查与扫描：Cursor的“快速工程”和代码自动补全非常强大，但也更容易引入不存在的引用。我的习惯是，在AI生成一段代码后，先不急着接受全部建议，而是手动滚动查看所有被修改的文件，重点检查import部分的变动，这是“未知项”高发区。

在Coze/Dify/n8n等可视化AI工作流场景下：这类平台的核心是流程自动化，Skill需要被“节点化”。

• 节点化Skill：将我的四层防御体系拆解成不同的工作流节点。
  • 节点一：需求解析器。可以是一个“知识库”节点，里面存放了项目技术栈文档；也可以是一个“LLM”节点，其系统提示词（System Prompt）被精心设计成结构化提问模板，引导用户输入或自动从上游节点提取结构化信息。
  • 节点二：测试生成器。一个专门的LLM节点，其输入是“需求解析器”输出的结构化需求，其输出是测试代码。这个节点的Prompt需要专门优化，强调“仅生成测试，不生成实现”。
  • 节点三：代码生成与审查器。这是一个关键且复杂的节点。理想情况下，它可以是两个LLM的协作：第一个LLM生成代码；第二个LLM以“审查员”角色运行，其Prompt就是我第三层的检查清单，对第一个LLM的输出进行批判性分析，并输出问题列表和修改建议。在Dify中，这可以通过“条件判断”节点来实现分支逻辑。
  • 节点四：沙箱执行器。这是一个“代码执行”节点或“HTTP请求”节点（调用一个预置的、运行在隔离环境的API）。它的任务是运行测试，并返回成功或失败的日志。
• 参数传递与错误处理：工作流中，每个节点的输出（如生成的测试代码、发现的问题列表）都需要作为参数清晰地传递给下一个节点。同时，必须在关键节点后设置“条件分支”，例如，如果“审查器”节点输出的问题列表不为空，则流转到“人工审核”或“重新生成”分支，而不是继续执行。

在面向Agent的Skill编码（如Codex Skill）场景下：这是更前沿的应用，目标是让AI Agent能自主调用这个“未知项管理”能力。这需要将Skill抽象成一种Agent可理解、可执行的协议或API。

• Skill的接口化：将我的四层防御逻辑，封装成一组标准的函数或工具（Tools），供Agent在规划（Planning）阶段调用。例如：
  • clarify_requirements(user_query, project_context) -> structured_spec
  • generate_tests(structured_spec) -> test_code
  • review_code(generated_code, test_code, project_context) -> issue_report
  • run_in_sandbox(code, tests) -> execution_result
• Agent的决策逻辑：你需要设计Agent的推理逻辑，使其在接到一个编程任务时，能自动规划并调用这些Skill。例如，Agent的“思考过程”可能是：“用户要求添加登录功能。第一步，我需要调用clarify_requirements来获取详细规格。第二步，调用generate_tests建立验证标准。第三步，生成代码。第四步，调用review_code进行自查。第五步，如果审查通过，调用run_in_sandbox验证；如果不通过，则根据问题报告重新生成代码。”
• 上下文管理：Agent需要有能力在多个步骤间维护和传递“项目上下文”（如技术栈、现有代码片段、已澄清的需求等），这是Skill能否有效执行的关键。

5. 避坑指南：Skill实施中的常见陷阱与应对策略

在将这套Skill应用到不同项目和团队的过程中，我踩过不少坑。这里分享几个最典型的陷阱和我的应对之策。

陷阱一：过度依赖AI的“常识”，省略需求澄清早期我常犯的错误是，认为一些“显而易见”的约定不需要说明。比如，我说“写一个RESTful API”，AI可能默认用JSON序列化、返回200状态码。但在我的老项目中，所有成功响应都包裹在一个ResultVO对象里，失败有特定的错误码体系。结果AI生成的代码完全不符合项目规范。

应对策略：建立“项目上下文清单”。这是一个活的文档，记录你项目的所有独特约定：通用的响应体结构、异常处理方式、日志格式、特定的工具类、内部中间件配置等。在每次向AI发起复杂任务前，把这个清单的相关部分作为前缀输入给AI。在团队协作中，这份清单应该共享并持续更新。

陷阱二：TDD测试用例过于肤浅或脱离实际让AI写测试，如果指令不明确，它可能会写出一些“走过场”的测试，比如只测试Happy Path，或者Mock过于理想化，掩盖了真实集成时的问題。

应对策略：细化测试指令。不要只说“写单元测试”，而要指明：

1. 测试框架和库：明确是用JUnit 5 + Mockito，还是pytest + unittest.mock。
2. 覆盖场景：明确列出必须覆盖的正常场景、边界场景（如空输入、极值）和异常场景（如网络超时、数据库连接失败）。
3. Mock规则：明确哪些外部依赖需要Mock，以及Mock对象应如何行为。例如：“请MockUserRepository.findByEmail方法，在传入test@example.com时返回一个预构造的User对象，传入其他邮箱时返回null。”
4. 断言重点：指明除了功能正确性，是否需要断言日志输出、性能耗时或特定副作用。

陷阱三：审查环节流于形式，陷入细节海洋面对AI生成的上百行代码，逐行人工审查效率极低，且容易因疲劳而遗漏关键问题。

应对策略：采用“分层聚焦式”审查法。

• 第一遍：依赖与导入扫描。快速浏览文件开头，只关注import/require语句，与项目依赖文件进行比对。这是最高效的风险排查。
• 第二遍：公共API与接口验证。只关注被调用的外部类、方法、函数名。在IDE中利用“跳转到定义”或全局搜索，快速确认其存在性和签名。
• 第三遍：核心逻辑流。暂时忽略细节实现，只看主干逻辑（如Controller->Service->Mapper的调用链），判断其是否符合业务流程图。
• 第四遍：细节与边界。最后再查看具体的算法、条件判断、循环等细节。这套方法能让你在15分钟内对一份中等复杂度的AI生成代码完成有效审查。

陷阱四：沙箱环境与生产环境差异导致“本地好使，上线就挂”即使在Docker中测试通过，也可能因为镜像版本、基础配置、网络策略等细微差异，在生产环境失败。

应对策略：追求环境一致性，并实施“渐进式集成”。

1. 镜像同源：确保本地测试用的Docker镜像，与CI/CD构建用的基础镜像，以及最终的生产镜像，尽可能来自同一来源（如官方同一版本Tag），或使用多阶段构建确保一致性。
2. 配置外置：AI生成的代码中，所有配置（数据库连接串、API密钥、服务地址）必须来自环境变量或配置文件，绝不能硬编码。在审查时要特别留意这一点。
3. 渐进式集成：不要一次性让AI生成一个完整的大模块。采用“切片式”开发：先让AI生成一个独立的、功能单一的小函数或工具类，集成测试通过后，再让它基于这个已验证的组件去构建更大的功能。这样，未知项被限制在很小的范围内，容易定位和解决。

将AI编程中的“未知项管理”整理成可复用的Skill，本质上是一次思维模式的升级。它要求我们从被动的、反应式的代码接收者，转变为主动的、流程化的质量管理者。这套方法不能保证100%消除问题，但它能将AI编程的风险从不可控的“随机故障”，转变为可管理、可追溯、可优化的“已知风险”。最让我受益的，不是某一次用AI快速写出了代码，而是在这套流程的约束下，我和AI的协作变得越来越有默契，产出质量的波动性越来越小，我终于可以更放心地将重复性、模式化的编码任务交给它，而自己则聚焦于更核心的架构设计和难题攻关。