干货｜Comate Harness Engineering工程实践指南

导读

本文将通过概念和简单案例，引导大家更合理地使用AI Coding

1、必知的概念体系

2、上下文的重要性

3、从最简单的维度理解什么叫Harness Engineering

4、模型的边界

让AI真正帮你干活

大家是否碰到以下问题：

1、接到需求后, 不知道如何借助AI编程工具生成代码

2、想给AI对话描述需求, 但是不知道怎么写Prompt（能说出来，但写不出来）

3、对话几次后, 感觉结果十分不符合预期, 最后把它当"对话工具"只用来问问题, 或者TabTab···

本次分享你能收获什么：

分享主题：通过概念和案例引导大家合理地使用AI(上下文)

分享目标：让你明天就能把AI Coding的知识用在工作里。

1. 认知层·理解AI工具核心概念

不再对各种名词感到陌生；明白当前模型的能力边界在哪里，建立合理预期；清楚 Vibe Coding、Spec Coding 在什么场景用什么姿势；理解 Harness Engineering。

2. 工具层·掌握Comate+语音输入

知道 Comate 怎么用，替代 VSCode；掌握语音输入法的正确姿势，降低写长 Prompt 的门槛；知道 Rules 和 Skills 是什么、怎么配置、有哪些坑要避开

3. 实战层·标准开发流程+实用技巧

明白接到需求后使用 AI 的标准流程；能区分「让生成更准确」和「反复返工」的本质差异；掌握应对幻觉、管理长对话上下文等技巧

00 开篇 · 重新认识你的角色：AI到底替代了什么？

AI替代的是： 机械重复的编码动作（样板代码、CRUD、格式转换）；低价值的信息检索（查 API 文档、查语法）；简单的逻辑拼接。

AI没有替代的是： 理解需求背后的业务意图；做架构决策和技术选型；组织上下文、识别边界条件；对生成结果的质量判断与把控。

谁能更快、更准确地组织上下文，谁的 AI 生产效率就越高。 这是一项新的核心技能，而不是可选项。

01 AI Coding必知概念体系

1.1 大模型基础概念

1.2 Agent工程体系

随着 AI 工具越来越复杂，出现了一套「工程化 AI」的概念体系，理解这些有助于用好 Comate：

重要概念

📌Rules（规则） ------AI 行为的约束层，相当于「团队编码规范」。持久生效，不需要每次在 Prompt 里重复说。

📌Agent Skills（技能） ------可复用的能力片段，类似封装好的函数。如「Figma→React组件」封装为一个 Skill。

📌Hook（钩子） ------在特定时机触发 AI 行为，如保存文件时自动格式化、提交代码前自动 Review。

非必要了解

⚡Tool&MCP------AI的「手」，让 AI 能调用外部能力。MCP 是标准协议，接入 Figma、数据库等外部系统。

⚡Agent / SubAgent------能自主规划和执行多步任务的 AI 单元。复杂任务可拆分给多个 SubAgent 并行处理。

⚡Commands（命令） ------可以忽略，推荐使用Skills替代。

1.3 三种编程范式辨析

Vibe Coding vs Spec Coding------核心差别在于：你是先想清楚再让 AI 写，还是边让 AI 写边想清楚。

💨 Vibe Coding

• 凭感觉，随时开始
• 几乎不做上下文准备，直接发需求
• 输出质量不稳定，依赖运气
• 适合：个人原型、快速验证、一次性脚本
• 主要风险：上线代码质量难保证，返工率高

🎯 Spec Coding

• 规格先行，整理好再生成
• 提前整理边界、状态、约束
• 输出质量可预期，更高
• 适合：功能开发、团队协作、生产代码
• 前置整理有成本，但总体省时

一句话区分： Vibe 是「先射箭再画靶」，Spec 是「先画靶再射箭」。两者都有价值，但生产环境下 Spec 是正确选择。

1.4 Harness Engineering（工程化约束驱动）

Harness Engineering 是比 Spec Coding 更进一步的概念：把 Rules、Skills、标准流程打包成团队工作流，让每个人的 AI 辅助开发都在一套约束下运行。

为什么同样的模型（比如 GPT-4），用不同的工具，生成效果差很多？

原因不在模型，在工具：

核心结论：

模型只是原材料，工具决定上下文质量，Harness 决定团队规模化复用的能力。

1.5 认清模型能力的边界

你用的是推理模型，不是AGI

最近 ARC-AGI-3 测试结果出来，各大模型成绩普遍不理想，这说明了什么？当前我们能用到的模型，本质上是**「在海量代码和文本上训练出来的概率预测机器」**------它预测的是「给定这些输入，最合理的下一段输出是什么」，而不是真正理解了需求、进行了推理。

推理模型是如何「理解」设计稿图片并生成 HTML 的？不是真的看懂了设计稿，而是：图片 → 转换为视觉特征描述 → 匹配训练数据中相似的 UI 模式 → 输出对应的 HTML 结构。所以它生成的结果高度依赖于输入的质量。你给的信息越完整、越准确，它匹配到的模式越精准，生成结果越好。

正所谓：道生一，一生二，二生三------上下文缺失会导致误差放大

上下文不完整的需求  → AI 基于假设生成代码    → 生成结果有偏差      → 你在有偏差的基础上继续追加需求        → 偏差继续放大          → 最终代码面目全非

投入到前期上下文整理的时间，是整个开发流程里回报率最高的时间。

02 工欲善其事，必先利其器：工具层全解

2.1 语音输入法（重点推荐）

💡 大家放弃认真写 Prompt 的核心原因往往不是「不知道怎么写」，而是「太麻烦了，打字太慢」。语音输入直接消除这个障碍。 语音比打字快 3--5 倍。

结构化口述

先说「做什么」，再说「约束」，最后说「不要做什么」

让 AI 先复述

说完需求后，先让 AI 复述其理解，确认无误再生成代码

检查后再提交

错别字会影响 AI 理解，特别是变量名、组件名等关键词。让AI再优化一次

2.2 AI 编程配置层（研发必知）

Rules 是什么？ Rules 是写给 AI 看的「持久约束」，每次生成代码时都会自动生效。相当于把团队的编码规范、技术约定、禁止事项提前告诉 AI。

Skills 是什么？ Skills 管的是「教 AI 做某件具体的事」。Skills 是可复用的任务模板，把一类重复性的生成任务封装起来，下次直接调用。

把 AI 想象成刚入职的实习生：Rules 是《团队开发规范手册》------不管做什么任务，都要遵守。Skills 是《标准作业流程 SOP》------做具体任务时按对应 SOP 执行。

Rules内部结构示例：

# 团队编码规范 Rules ## 技术栈约定- 使用 React 18 + TypeScript，禁止使用 class 组件- 状态管理统一使用 Zustand，禁止引入 Redux 或 MobX- 样式方案使用 CSS Modules，禁止内联样式 ## 命名规范- 组件文件名和组件名使用 PascalCase- Hook 名称以 use 开头，使用 camelCase- 工具函数文件使用 camelCase，常量使用 UPPER_SNAKE_CASE ## 代码质量要求- 禁止使用 TypeScript any 类型，用 unknown 替代- 每个函数必须声明返回类型- 异步操作必须处理 loading、error、empty 三种状态 ## 禁止事项- 不引入 package.json 未声明的第三方库- 不提交包含 console.log 的代码

Skills 内部结构示例：

# Skills：生成标准业务列表组件 ## 触发条件当用户需要生成一个业务列表页面时调用此 Skill。 ## 执行前需要收集的信息1. 列表的数据结构（字段名、字段类型）2. 是否需要分页？分页方式（前端分页 / 后端分页）3. 是否需要搜索和筛选？筛选字段有哪些？4. 是否需要多选和批量操作？5. 数据量级（决定是否需要虚拟滚动） ## 执行步骤Step 1：生成 TypeScript 类型定义文件（types.ts）Step 2：生成 Zustand store，包含 loading、error、分页状态Step 3：生成列表容器组件，包含数据请求逻辑Step 4：生成列表项组件，处理字段渲染和交互Step 5：生成搜索/筛选组件（如果需要）Step 6：生成空状态、错误状态、loading 状态展示组件 ## 输出要求- 每个 Step 生成完后，等待用户 Review 确认，再继续下一步- 生成完成后，输出组件依赖关系图

常见 Skills 示例：

上下文注入机制的差异（重要）

这是 Rules 和 Skills 一个容易被忽略的关键差别：

每次对话开始时：  ┌─────────────────────────────────────┐  │  Context Window                     │  │  ┌──────────┐  ┌─────────────────┐  │  │  │  Rules   │  │   你的 Prompt   │  │  │  │ (自动注入)│  │                 │  │  │  └──────────┘  └─────────────────┘  │  └─────────────────────────────────────┘调用 Skill 时：  ┌──────────────────────────────────────────────┐  │  Context Window                              │  │  ┌──────────┐  ┌─────────┐  ┌─────────────┐ │  │  │  Rules   │  │  Skill  │  │  你的 Prompt │ │  │  │ (自动注入)│  │(调用时注入)│ │             │ │  │  └──────────┘  └─────────┘  └─────────────┘ │  └──────────────────────────────────────────────┘

Rules 始终占用 Context，所以要保持精简

Skills 只在需要时才占用 Context，所以可以写得详细

如果把大量流程描述写进 Rules，会持续消耗 Context，导致 AI「记不住」其它重要信息

💡 Spec Coding、 Rules、Skills 上面讲的这些，其实本质都是为了解决"上下文"问题 1. Spec Coding = 给 AI 固定骨架，减少发散 2. Rules = 给 AI 划红线，避免犯错 3. Skills = 给 AI 塞套路，提升质量工程规范 = 上下文的持久化与标准化。

03 实战：从需求到代码的标准流程

3.0 演示需求说明

📋 需求：实现虚拟列表 + 多选 + 权限控制

· A + B 角色多选 → 展示操作按钮1

· C + D 角色多选 → 展示操作按钮2

· A + C 角色多选 → 不展示任何按钮

· 列表数据量大（万条级别），需要虚拟滚动

这个需求涉及三个独立维度，有一定复杂度，适合用来演示正确和错误的协作方式。

3.1 正例与反例对比

✅ 正例：分层 Spec + 激活 Rules + 分步生成

Step 1：让 AI 先出技术方案，不写代码

你：我需要实现一个虚拟列表组件，支持多选和权限控制。    技术栈：React 18 + TypeScript，组件库 antd 5.x，状态管理 Zustand    列表数据量：约 1-5 万条    权限规则：选中角色组合不同，展示的操作按钮不同（规则后续提供）        请先给我一个技术方案，包括：    1. 组件拆分建议    2. 虚拟列表使用哪个方案？为什么？    3. 多选状态放在哪里管理？    4. 权限判断逻辑建议放在哪个层？    不要写代码，先给方案。

Step 2：确认边界，让 AI 提问

你：方案看起来合理。在开始写代码前，你还有哪些不确定的地方需要我补充？ # AI 会主动提问：权限数据结构是什么、按钮的操作是什么、列表数据结构......# 这些补充信息让后续生成更准确，也让你意识到哪些上下文之前没想到。

Step 3：分模块生成，每次 Review 后再继续

你：好的，现在开始写代码。先只实现虚拟列表的基础结构，    不需要多选逻辑，不需要权限判断，只需要：    - 虚拟滚动正常工作    - 列表项组件结构符合后续扩展需要    - 使用 react-virtual 方案 # Review 通过后：你：虚拟列表部分没问题。现在在这个基础上，加入多选逻辑。    多选状态存放在 Zustand store 中，store 的结构我已经定义好了：[附上 store 定义]

Step 4：Rules 全程托底

⚙️ Rules 已经定义了组件规范、命名风格、TypeScript 要求------不需要每次都在 Prompt 里重复说，AI 会自动遵守。

完成下面的mdr，你就实现了一套最简的 Harness Engineering

这也是 Harness Engineering 的价值：约束在背后持续生效，你专注于业务逻辑即可。

# virtual-list.mdr---alwaysApply: false  (写false的需要再输入中@xx.mdr显示引用，否则会自动携带)---# 虚拟列表开发规则技术栈：React 18 + TypeScript，组件库 antd 5.x，状态管理 Zustand

新输入：

@virtual-list.mdr 你：我需要实现一个虚拟列表组件，支持多选和权限控制。列表数据量：约 1-5 万条权限规则：选中角色组合不同，展示的操作按钮不同（规则后续提供） 请先给我一个技术方案，包括：1. 组件拆分建议2. 虚拟列表使用哪个方案？为什么？3. 多选状态放在哪里管理？4. 权限判断逻辑建议放在哪个层？不要写代码，先给方案。

❌ 反例：

❌ 反例一：把 AI 当搜索引擎用

你：帮我做一个可以多选的列表，有权限控制

结果： AI 生成了最简单的 checkbox list，没有虚拟列表、没有权限矩阵。追加需求→上下文越来越乱→最终重写。

问题根源： Prompt 里没有任何上下文，AI 只能按最通用的方式理解和生成。

❌ 反例二：上下文残缺，关键约束没说

你：帮我实现一个虚拟列表组件，支持多选，选中后根据角色权限展示不同按钮    权限规则：A+B→按钮1，C+D→按钮2，A+C→无按钮

结果： 缺少组件库（AI 自选了项目没有的库）、数据量级（没有加虚拟滚动）、权限数据结构（和后端不兼容）、状态管理方式（用了 useState 而非 Zustand）。

问题根源： 生成代码需要大面积修改，返工成本 > 自己手写成本。

❌ 反例三：一次性要求实现全部功能

你：帮我完整实现这个需求（附完整需求文档）    包括：虚拟列表、多选逻辑、权限判断、loading 状态、空状态、错误处理

结果： AI 生成了 600 行代码。其中虚拟列表 API 调用有误（幻觉），权限判断有边界条件未处理，代码量大 Review 困难，修复一处又引入新问题。

问题根源： 生成粒度太大，单次 Review 负担过重，出错后难以精准定位和修复。

❌ 真实案例分析（需求拆散表达）

以下是一个我构造的来自网络的对话记录：

问题分析：

错误一：需求拆散表达，应该一次说完

一个完整需求分成了 4 轮才说清楚：

这些其实是同一个功能的完整需求，一开始就应该全部描述清楚，导致 AI 反复重构同一段代码。

错误二：没有提供业务上下文

第一个问题只说"实现并发控制"，但没告诉 AI

• 失败后是否要继续跑其他任务，还是直接中断* 最终结果怎么处理（需要按顺序收集吗）* 任务完成后要实时更新 store，还是全部完成再更新

这些是影响设计决策的关键信息，缺失导致 AI 每次都猜了一个方案，用户再纠正。

错误三：打断后重新提问，内容基本重复

09:55 发送了一条消息，立刻中断（[Request interrupted by user]），09:56又发了一条几乎相同的消息，只是多加了"按顺序返回结果"这一点。

这说明用户没想清楚就发送了，打断后才意识到没说完整。

错误四：用模糊动词描述需求

"失败时不阻塞后续的其他任务" ------这句话有歧义：* 是指失败直接跳过，还是失败后重试再跳过？* 失败的结果怎么处理，丢弃还是收集？

AI 只能猜测一种理解，用户需要后续再澄清。精确的描述应该是： "失败时捕获错误不抛出，继续执行剩余任务，最终返回所有任务结果（含失败信息），顺序与入参一致"

💡 如果第一轮就说清楚这些，AI 只需要生成一次代码：

1. 说清楚函数签名：输入是什么、返回值是什么

2. 说清楚失败策略：失败重试几次、失败后继续还是中断

3. 说清楚副作用时机：实时回调还是全部完成后处理

4. 说清楚调用场景：在哪里用、需要通用还是业务特定

3.2 标准开发流程总结

3.3 场景演示

Rules效果对比

演示同一个组件需求，没有 Rules 时 AI 的「自由发挥」（混用 CSS 方案、随意命名、未处理 loading 状态），加入团队 Rules 后的约束效果（统一规范、代码风格一致）。

3.4 小结：三条原则

1. 不要把 Comate 当对话工具用

它不是 ChatGPT，它的价值在于深度集成到你的开发环境，用好Rules 和 Skills才能发挥最大价值。

2. 质量在Prompt里，不在频繁的追问对话里

前置多花10分钟整理上下文，比后续反复迭代修改省时得多。

3. AI 负责生成，你负责决策

技术方案由你确认，生成结果由你 Review，不要把判断力外包给 AI。

04 让AI更好使，你需要知道的几件事

4.1 应对幻觉：识别、止损、果断重启

什么是幻觉？ 幻觉（Hallucination）是指 AI 生成了看起来合理、实际上不正确的内容：调用了不存在的 API；生成的逻辑在边界条件下行为错误；引用了已废弃的方法。

识别信号：

🛑 在一个已经「偏了」的对话上继续追问，是最低效的做法。AI 会在错误的上下文基础上继续生成，越陷越深。正确做法：重启，但不是从零开始。

重启前的关键动作：

你：在我们结束这个对话之前，请你帮我总结：    1. 我们要实现的需求是什么    2. 目前已经完成了哪些部分（可以列出已生成的代码模块）    3. 还有哪些没有完成    4. 当前遇到的问题是什么    5. 你认为问题的根因是什么

# 把这个总结复制到新对话的开头，作为起点 Prompt，比从头描述需求高效得多。

4.2 长对话的上下文管理

AI 没有「真正的记忆」，随着对话变长：早期的约束和规范信息开始「掉出」Context Window；AI 开始「忘记」你在对话开始时说的技术栈要求；生成质量逐渐下降，但你可能没有意识到。

4.3 其它实用技巧

Think before Code（先出方案，再写代码）

# ❌ 不好的做法"帮我实现 XX 功能"# ✅ 好的做法"帮我实现 XX 功能，先给我技术方案，不要写代码"→ 确认方案后 →"方案没问题，现在开始写代码"

善用「反问」模式------让 AI 先提问，把它认为缺失的信息问出来：

"我要实现 XX，在开始之前，你有哪些不确定的地方需要我补充？"

这个技巧的价值在于：AI 的提问会帮你发现自己忽略的边界条件。 很多时候你以为需求说清楚了，AI 一提问才发现还有很多没想到的地方。

用边界条件约束生成结果

"实现这个功能时，需要处理以下情况：- 数据为空时- 接口报错时- 用户无权限时- 数据量超过 1 万条时"

多轮 Review 策略------不要一次性 Review 所有东西，分层进行：

1. 逻辑正确性：这段代码在做什么？方向对吗？

2. 边界处理：异常情况有没有处理？

3. 代码规范：命名、类型、风格是否符合团队规范？（Rules 已帮你做了大部分）

4.4 Rules使用注意事项

第二章介绍了 Rules 怎么写，这里专门讲容易踩的坑。Rules 配置不当，轻则 AI 行为不符合预期，重则团队之间互相覆盖。

⚠️ 陷阱①

路径与作用域

子目录不会自动继承父级 Rules，需显式配置。局部 Rules 优先级高于全局。常见问题：以为全局覆盖了，但新项目里实际没有生效。

⚠️ 陷阱②

多份 Rules 的冲突与覆盖

相同条目以局部为准，不同条目会合并生效。合并叠加容易出现意料外行为，建议团队只维护一份项目级 Rules。

⚠️ 陷阱③

内容写法陷阱

❌「写好代码」→ AI 会忽略

✅「函数单一职责，超过 50 行必须拆分」 单个文件控制在 200 行以内，避免相互矛盾的规则。

⚠️ 陷阱④

Rules与Skills 职责混淆

把执行步骤写进 Rules → Rules 越来越重；把约束写进 Skills → 约束只在调用时生效。判断：「任何时候」→ Rules；「做某件事时」→ Skills。

✅ 最佳实践⑤

纳入 Git 版本管理

Rules 变更需走 Review 流程，文件顶部维护变更日志，任何人不得单独修改影响全团队的 Rules。

✅ 最佳实践⑥

修改后验证生效

修改 Rules后需重启 Comate 或重新加载上下文。验证：问AI「你当前有哪些 Rules 在生效？」让它复述确认。

# 团队 Rules 版本管理示例（文件顶部）# 版本：v1.3 | 最后修改：2025-06-01 | 修改人：xxx# 变更记录：# v1.3 新增禁止 console.log 提交规则# v1.2 补充 Zustand 状态管理约定

4.5 Skills 使用注意事项

Skills写得好，能把团队效率拉上一个台阶；写得不好，反而比不写更混乱。以下是实际使用中的高频问题。

⚠️ 陷阱①

Skills粒度：不要贪大

❌「完整业务开发 Skills」（读需求+出方案+写代码+写测试+写文档） ✅ 拆分为：需求分析 / 组件生成 / 测试用例，各自独立。

⚠️ 陷阱②

步骤缺少终止条件

❌「Step 2：生成组件代码」

✅「Step 2 完成后，输出『Step 2 完成，等待 Review』，等待确认后再进入 Step 3」

⚠️ 陷阱③

检查脚本流于形式

❌「检查代码质量」（AI 不知道如何量化）

✅「检查是否有未处理的 Promise rejection」

✅「检查所有 props 是否有 TypeScript 类型声明」

⚠️ 陷阱④

Skills引用的上下文来源不明

❌「根据数据结构生成类型定义」（数据结构从哪来？）

✅「读取用户在当前对话中提供的接口返回示例 JSON」

✅ 最佳实践⑤

标注适用版本范围

文件顶部标注「适用版本：React 18 + antd 5.x + Zustand 4.x」，定期 Review 并删除过时 Skills。

✅ 最佳实践⑥

约束不能只放在Skills里

Skills中的约束只在该 Skills被调用时生效。「任何时候都要遵守」的约束必须写进 Rules，不能只写在某个Skills里。

# Skills内嵌检查报告输出示例## 内嵌检查脚本生成完成后，输出以下格式的检查报告：检查项                    | 结果-------------------------|------loading 状态已处理         | ✅ / ❌error 状态已处理           | ✅ / ❌TypeScript any 未使用      | ✅ / ❌props 类型定义完整          | ✅ / ❌

AI Coding不是让你少思考，而是让你思考更值钱的部分。早建立正确的协作方式，越早把生产力的杠杆握在自己手里。

05 总结

最后做个总结：其实讲了这么多概念，Skills、Rules、Spec Coding、Vibe Coding、模型边界等等，可以发现一个词自始至终都在贯穿：「上下文」。

上下文缺失不好，但上下文过多同样是个坏事。结合Harness Engineering，就是用工程化手段，稳定、可控地构造:「合理的上下文」

理解这些，就可以慢慢地从 「会用 AI 写代码」，升级成 「会工程化驾驭 AI 写高质量、稳定、可规模化代码」。