Spiga

AI 辅助编程4：从指令约束到全链路项目交付

2026-05-23 23:37:19

一、面向智能体的协作心智与边界控制

先把终端智能体从“高级补全器”的位置挪出来。它能快速写代码，但需要我们给出业务意图、模块职责和工程底线。

1. 建立“结对编程”的协作心智

早期代码补全像“填空题”：写好函数名和注释，等待中间过程自动补齐。到了终端智能体时代，如果仍然只丢一句“帮我实现购物车计算逻辑”，通常能得到可运行代码，却不一定能融入现有工程。

  • 低效用法：把它当外包团队，只交付模糊目标，等待完整结果，事后再大面积返工。
  • 推荐用法：把它当结对伙伴，我们坐在主驾驶位，明确架构方向、业务边界和质量底线。

关键转变： 不需要教它怎么写 for 循环，要告诉它这段代码在业务里承担什么责任。

2. 用高级确定性对抗工程复杂性

现代模型默认倾向于尽快交付能跑的 Demo。缺少约束时，它可能把请求、状态、DOM 操作揉在一起。强约束的目的，是把输出拉回企业级工程代码。

实操案例：发送验证码倒计时按钮

  • 基础需求生成：
用原生 JS + HTML 写一个发送验证码的倒计时按钮。点击后禁用按钮并倒计时 60 秒。
  • 架构级约束生成：
使用原生 JS + HTML 开发一个发送验证码的倒计时按钮。
为了保证代码的可维护性，请严格遵守以下架构约束：
1. **职责分离**：请将逻辑层与视图层拆分。不要写在一坨代码里。
   - 先封装一个纯粹的 `CountdownTimer`类负责处理时间逻辑（需支持传入自定义总时长，对外暴露 `onTick`和 `onEnd`两个回调钩子）。
   - 然后再写具体的 DOM 操作逻辑去调用这个类。
2. **防御性编程**：在 `CountdownTimer`类中，必须提供一个 `destroy`方法，用于在组件卸载时手动清除内部所有的定时器，防止内存泄漏。
3. **技术栈**：严格使用原生 JS，不要任何外部依赖。
4. **文件结构**：确保 HTML 和 JS 代码文件分离，不要把上述 JS 代码写在 HTML 文件中。
  • 约束如何改变输出质量：
业务意图 → 职责分离 → 防御边界 → 可复用代码

你输入什么样的工程规范，智能体就会还给你什么级别的代码质量。

二、标准化提示结构与约束设计

接下来把“怎么说清楚”标准化。角色、业务、任务、规定四个维度，可以显著提高输出的一致性和可落地性。

1. 四维度标准化模板

维度 说明 示例
角色 唤醒高质量代码特征 “资深前端工程师”“熟悉模块化设计”
业务 交代运行环境 说明页面、系统、团队约定和复用场景
任务 描述输入输出 字段、交互、数据格式、结果展示都要具体
规定 画出工程红线 禁止依赖、拆分职责、不得直接操作 DOM 等

2. 实操案例：企业级表单验证模块

[角色]
请担任一位拥有丰富前端架构经验的资深工程师，精通原生 JavaScript 的模块化设计与防御性编程。

[业务]
我们正在开发一个没有任何前端构建工具的极简静态官网。所有脚本需要通过 <script> 标签直接在浏览器运行，且这段验证逻辑未来会被多个不同的登录注册页面复用。

[任务]
请编写一个表单验证工具集，以及 HTML 示例。需验证的字段包括：
1. 用户名：只允许中英文，长度 2-10 位。
2. 手机号：需符合中国大陆手机号规则。
3. 密码：至少 8 位，必须包含大小写字母和数字。

[规定]
1. 高内聚低耦合：不要把 DOM 元素的获取逻辑与验证逻辑混写在一起。请将验证规则与错误提示文案抽离成一个独立的字典（或策略对象）。
2. 纯粹性：该工具只负责接收数据、执行正则匹配并返回验证结果与错误信息，严禁在验证逻辑中直接操作 DOM 或调用 console.log。
3. 无依赖：严格使用 JS 原生语法，禁止引入第三方校验库。

3. 输出格式与代码规范的确定性控制

逻辑对了还不够，物理规范也要可控。文件拆分、语义化结构、CSS 变量、命名规范都会影响后续维护成本。

规范要点：

  • HTML：语义化标签（section、article、header 替代无意义嵌套）
  • CSS：变量化管理（颜色、边框、背景统一放到 :root）
  • 命名：BEM 规范（避免 .box1、.wrap这类临时命名）

示例约束：

请编写一个产品定价页面的 HTML 与相应的 CSS 样式。包含三个并排显示的定价卡片（基础版、专业版、企业版）。
请在生成代码时，严格遵守以下团队工程规范：
1. **结构语义化**：严禁使用全篇的 `<div>`嵌套。必须合理使用 `<section>`, `<article>`, `<header>`等 HTML5 语义化标签。
2. **CSS 变量化管理**：卡片中涉及到的所有颜色（背景色、边框色、字体色），严禁使用硬编码。必须在 CSS 的 `:root`中统一定义为 CSS 变量，并且变量名强制使用 `--theme-`作为前缀（例如：`--theme-card-bg`）。
3. **命名空间一致性**：CSS 类名严格遵循 BEM 命名规范（块、元素、修饰符，如 `pricing-card__title--active`）。

三、文件精准读取与视觉设计图转换

随后进入本地工作区。终端智能体的优势不是把代码吐在聊天窗口里，而是读取指定文件、理解上下文，再直接写入磁盘。

1. 工作区精准读取与跨文件操作

工程目录文件很多时，不要让智能体漫无目的扫描。明确告诉它读取哪个文件、写入哪个文件、围绕哪个 DOM 节点实现逻辑。

已有文件：index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>用户列表</title>
</head>
<body>
    <div class="container">
        <h2>系统活跃用户</h2>
        <ul id="userList">
            <!-- 数据将通过 JS 渲染在这里 -->
        </ul>
    </div>
    <script src="./main.js"></script>
</body>
</html>

直接下达文件操作：

请读取当前目录下的 index.html文件，分析其 DOM 结构。
然后，请直接在当前目录下创建并写入一个 main.js文件。
任务要求：
1. 在 main.js中编写原生逻辑，模拟异步获取 3 个用户的数据（包含姓名和邮箱）。
2. 将这些数据渲染到 HTML 中 id="userList"的节点内。
3. 每个用户生成一个 <li>标签，内部使用 <strong>显示姓名，<span>显示邮箱。

2. 视觉设计图的高还原度转换

图片负责传递视觉，文字负责划定工程结构。只给图不加约束，代码很容易退回绝对定位和低可维护性布局。

请仔细观察这张设计草图，并在当前目录下创建一个 HTML 和对应的 CSS 文件来还原该页面。
架构与布局约束：
1. 整体骨架严禁使用绝对定位。必须使用 CSS Grid 网格布局实现左侧固定宽度、右侧自适应的经典结构。
2. 页面中所有的卡片元素排列，必须使用 Flexbox 布局。
3. 页面风格和配色采用赛博修仙风格，并在 CSS 的 `:root` 伪类中定义为全局 CSS 变量。
4. HTML 中需要保留足够的内容占位符，以便直接在浏览器中打开 HTML 时能看到完整的页面结构。

四、复杂业务逻辑的引导策略

复杂需求不能一次性扔给智能体。先让它推演状态，再分段实现，最后检查边界条件。

1. 伪代码先行验证机制

在代码生成前，先让智能体用中文步骤推演状态流转。方向正确后，再进入文件创建和代码实现。

多条件搜索分页的状态流转：

  1. 定义全局状态：关键词、分类、当前页码、总页数。
  2. 输入搜索词或切换分类时，先更新条件。
  3. 条件变化后，把当前页码重置为 1。
  4. 发起请求并渲染结果。
  5. 后端返回空数组时，展示空状态。

提示词示例：

我们需要用原生 JS 开发一个商品列表页面，包含文本搜索、分类筛选和分页条这三个交互控件。
请注意，请先用中文伪代码和步骤罗列的方式，清晰地向我们描述这个模块的逻辑走向。
必须涵盖以下逻辑点的推演：
1. 全局状态变量应该如何定义？
2. 当用户在“文本搜索框”输入内容并触发搜索时，除了更新搜索条件，针对“当前页码”这个变量应该怎么处理？
3. 当获取到后端返回的空数组时，视图层应该如何展示？

2. 任务分解与状态机引导

长流程需求可以拆成多个可验证阶段。每次只推进一小段，完成后检查，再继续下一步。

拖拽方块实现步骤：

  1. 创建 HTML 文件，放入绝对定位的蓝色方块。
  2. 创建 JS 文件，只写事件监听骨架和日志。
  3. 补充坐标偏移量计算，实现跟随鼠标移动。
  4. 加入边界碰撞检测，限制在视口内。

提示词示例：

请从零实现一个任意拖拽方块的功能。
为了保证逻辑清晰，请严格按照以下 4 个步骤执行。
1. 创建 HTML 文件。在其中写好基础的 HTML 骨架，并用内联 CSS 画一个处于绝对定位的蓝色方块。
2. 创建 JS 文件。只编写事件监听的骨架结构（给方块绑定鼠标按下，内部嵌套鼠标移动和鼠标松开）。不要写具体的坐标计算逻辑，直接使用 console.log打印事件触发状态即可。
3. 在上一步的基础上，补充具体的鼠标坐标偏移量计算逻辑，实现方块跟随鼠标移动。
4. 在上一步的基础上，补充边界碰撞检测逻辑，确保方块不能被拖拽出浏览器的可视区域。
规定：每完成一个步骤的代码生成后，必须立即停止，等待我们回复“继续”后，才能进行下一步的输出。

3. 思维链触发与边界条件分析

业务规则交织时，先问清楚优先级和极端情况。尤其是结算、积分、折扣、权限这类逻辑，不能直接按文字顺序翻译成代码。

规则示例：

  • 运费规则：商品金额满 20 元免运费，否则收取 5 元运费。
  • VIP 权益：VIP 用户可享受商品金额 9 折优惠。
  • 现金券：使用后直接在订单总额上抵扣 10 元。
  • 兜底防御：最终结算金额绝不能小于 0。

提示词示例：

开发一个电商结算面板。你需要创建一个HTML（包含金额输入框、VIP 勾选框、20 元现金券勾选框、计算按钮和账单明细展示区）以及对应的计算逻辑 JS 脚本。
核心计价业务规则如下：
1. 运费规则：商品金额满 20 元免运费，否则收取 5 元运费。
2. VIP 权益：VIP 用户可享受商品金额 9 折优惠。
3. 特殊优惠券：使用后直接在订单总额上抵扣 10 元。
任务要求：在创建文件和编写任何代码前，请先开启逐步推理，必须明确回答以下两个业务问题：
* 问题 1：运费的免邮门槛（满 20 元），是基于打折前的原始金额判断，还是基于 VIP 打折后的金额判断？请给出合理的商业推断，并据此排定代码中的计算先后顺序。
* 问题 2：如果一个非 VIP 用户购买了 5 元的商品，并且勾选使用了 10 元的优惠券，最终的结算金额会变成负数吗？在真实的 JS 逻辑中应该如何做兜底防御？
请先输出你的逻辑推演文本，确认梳理无误后，再开始编写代码，实现完整的界面和极其严谨的计价逻辑。

五、项目的健壮性构建与性能审查

功能跑通只是起点。网络异常、非法输入、海量数据和后续修改，才是代码质量的真实考场。

1. 防御性编程与异常边界处理

不要让智能体写“乐观请求”。请求超时、HTTP 异常、加载中和降级展示都要提前约束。

状态覆盖： 加载中 · 超时断开 · 接口报错 · 友好降级

提示词示例：

使用 HTML + 原生 JS 开发一个“随机名言获取” 页面，包含展示面板和“换一句”按钮。
在编写 JS 时，不要使用基础的“乐观请求”。请严格落实以下防御性编程要求：
1. 请求超时控制：设置 5 秒超时强制中断。
2. HTTP 状态码校验：不要仅仅捕获网络断开的错误。必须手动检查响应状态，拦截 500、404 等异常状态。
3. UI 降级展示：针对“加载中”、“超时断开”、“接口报错”三种状态，必须在页面中渲染出对应的中文提示文案，不能让页面白屏。

2. 核心逻辑的测试驱动开发

金额格式化、密码校验这类核心函数，先写测试边界，再实现逻辑。没有测试保护，后续修改很容易引发连锁问题。

测试用例：

  • 正常数字：1234.5 返回 "¥1,234.50"
  • 负数：-50 返回 "-¥50.00"
  • 非法数据：null 或 "abc" 返回 "--"
  • 极端长数字仍保持千分位

提示词示例：

采用测试驱动开发（TDD）的模式，开发一个核心的金额格式化函数。
请按以下步骤进行：
1. 创建 HTML 文件，页面上画一个测试结果展示区（例如一个 id="testReport"的列表），用于直观呈现测试用例的通过情况。
2. 创建 JS 文件，在编写函数内部逻辑之前，先在页面底部写 5 个原生断言测试用例，将测试结果渲染到 HTML 中。这 5 个用例必须包含极端边界：
* 正常数字（如 1234.5 返回 "¥1,234.50"）
* 负数处理（如 -50 返回 "-¥50.00"）
* 非法数据类型（如传入 null或字符串 "abc"时，必须返回占位符 "--"）
* 极端长数字的处理。
3. 根据上述测试用例的约束，最终完善函数的内部实现，确保打开 HTML 时，页面上所有的测试结果都显示为绿色的“通过”。

3. 性能瓶颈分析与渲染优化

海量数据不能靠普通循环一次性塞进 DOM。要让智能体识别主线程阻塞风险，并选择时间切片、文档片段等方案。

10,000 条日志的非阻塞渲染流程：生成数据 → 分批渲染 → 更新进度 → 保持滚动

提示词示例：

使用 HTML + 原生 JS，开发一个“系统日志查看器”页面，需要模拟一次性接收并展示 10,000 条日志数据。
核心业务与体验约束如下：
1. 严禁页面假死：如果用普通的循环一次性把一万条数据塞进页面，浏览器一定会卡死。请你作为资深前端专家，自主选择一种高性能的渲染方案（无需额外库，纯原生实现），确保在加载大量数据时，页面的滚动依然丝滑，不能阻塞主线程。
2. 视觉加载反馈：在页面顶部放置一个状态栏。在数据慢慢渲染进页面的过程中，必须实时更新当前的进度（例如：已渲染 3000/10000 条）。
请在充分理解这个性能痛点后，实现这个高性能的列表流。

六、全链路实战：从 0 到 1 构建完整项目流

最后把前面的技巧串起来，模拟构建“天气查询与待办事项合一的仪表盘”。关键不是亲手写每一行代码，而是稳定地指挥智能体交付。

1. 阶段一：架构设计与思路对齐

文件规划： index.html、style.css、app.js、server.py

提示词示例：

我们现在准备开发一个原生的“天气与待办仪表盘”。请注意，现在绝对不要生成任何具体的代码。
作为资深架构师，请先帮我们梳理出这个项目的技术方案，必须包含以下两点：
1. **工程目录规划**：列出我们需要创建的文件清单。要求前端完全使用原生 HTML/CSS/JS，后端使用 Python 3 的内置标准库来做接口代理，解决跨域问题。
2. **核心状态流转**：待办事项的数据如何做本地持久化？前端如何与后端的 Python 代理进行通信？
请用清晰的条目向我们汇报你的架构思路。

2. 阶段二：前端基建与 UI 交互绑定

提示词示例：

架构思路非常完美。现在请根据上述规划，先开始前端（frontend）部分的开发。
具体的业务与工程约束如下：
1. **UI 布局规范**：使用 CSS Grid 将页面分为左右两栏。左侧显示天气信息占位符，右侧是一个待办事项列表。页面整体需具备现代化的简约设计感，颜色通过 CSS 变量统一管理。
2. **待办逻辑防腐**：待办事项的增删查改必须做边界防御：用户输入空字符串或纯空格时，必须拦截并给出弹窗提示，禁止添加无意义数据。
3. **数据持久化**：每次修改待办列表后，必须同步更新到本地 `localStorage`，确保页面刷新数据不丢失。

3. 阶段三：后端代理接口集成

提示词示例：

前端界面验证通过。现在请继续后端（backend）部分的开发。
技术与业务约束要求：
1. **零依赖要求**：严格限制只使用 Python 3 的内置模块，绝对不允许安装第三方包。
2. **接口规范**：请暴露一个 API 接口。当接收到前端请求时，后端去公共接口抓取一段天气 JSON 数据返回给前端。
3. **跨域放行**：必须解决浏览器的跨域问题。
完成后，我们请在后台启动它。

4. 集成联调与边界异常修复

全链路联调路径：页面加载 → 显示加载提示 → 请求后端代理 → 成功或降级展示

提示词示例：

后端服务已启动。现在我们需要修改前端的 ，把真实的天气数据接入到页面左侧的面板中。
任务要求：
在修改代码之前，请开启逐步推理，回答以下工程问题：
- 如果用户打开了网页，但我们的后端没有启动，前端发起的请求会怎样？如果不做处理，页面左侧会发生什么？
推理明确后，请修改相关文件。要求：
1. 必须在请求期间展示“正在获取气象卫星数据...”的加载提示。
2. 必须包含极其严密的异常拦截机制。如果请求失败，必须在界面上优雅地渲染出“气象服务暂不可用，请稍后再试”，绝不允许让页面左侧陷入永无止境的白屏或者打印一堆用户看不懂的底层报错。

收束：架构对齐、强硬约束、分步拆解、边界防御，是指挥 AI 交付工程代码的核心组合。