AI Coding 入门指南 - 如何更好地让AI真正帮你干活

​

导读

通过概念和简单案例引导大家合理的使用AI

1、必知的概念体系

2、上下文的重要性

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

4、模型的边界

让 AI 真正帮你干活

大家是否碰到以下问题：

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

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

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

本次分享你能收获什么：

三个层面的收获

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

本次分享的目标只有一个：让你明天就能把 AI 的知识用在工作里。

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 Skill（技能）------可复用的能力片段，类似封装好的函数。如「Figma→React组件」封装为一个 Skill。

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

非必要了解

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

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

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

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 工具层（厂内计费体系）

不对比两个工具的好坏，建议都用用

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

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

结构化口述

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

让 AI 先复述

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

检查后再提交

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

2.3 AI 编程配置层（RD 必知）

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 内部结构示例：

# Skill：生成标准业务列表组件

## 触发条件
当用户需要生成一个业务列表页面时调用此 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、Skill 上面讲的这些，其实本质都是为了解决"上下文"问题 1. Spec Coding = 给 AI 固定骨架，减少发散 2. Rules = 给 AI 划红线，避免犯错 3. Skill = 给 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 写得好，能把团队效率拉上一个台阶；写得不好，反而比不写更混乱。以下是实际使用中的高频问题。

⚠️ 陷阱①

Skill 粒度：不要贪大

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

⚠️ 陷阱②

步骤缺少终止条件

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

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

⚠️ 陷阱③

检查脚本流于形式

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

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

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

⚠️ 陷阱④

Skill 引用的上下文来源不明

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

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

✅ 最佳实践⑤

标注适用版本范围

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

✅ 最佳实践⑥

约束不能只放在 Skill 里

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

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

AI Coding 实战分享

AI Coding 不是让你少思考，

而是让你思考更值钱的部分。

越早建立正确的协作方式，越早把生产力的杠杆握在自己手里。

05 总结

最后做一个总结：

其实讲了这么多概念，Skill、Rules、Spec Coding、Vibe Coding、模型边界等等，

大家可以发现一个词自始至终都在贯穿：《上下文》

上下文缺失不好，但上下文过多同样是个坏事

在结合 Harness Engineering，就是用工程化手段，稳定、可控地构造:《合理的上下文》

理解这些，就可以慢慢的从 《会用 AI 写代码》

升级成 《会工程化驾驭 AI 写高质量、稳定、可规模化代码》

​