设计理念

AI Coding 的本质

AI Coding 的本质不仅仅是用 AI 写代码，而是用结构化的规范和工作流把不确定性消除在执行之前——AI 负责在确定性空间里高速执行，人负责维护和扩展那个确定性空间的边界。

这句话是 HCodeFlow 存在的意义。

问题：AI 写代码，为什么还需要框架？

AI 已经能写出高质量的代码，但团队协作中的真正挑战从来不是"代码怎么写"，而是：

• 需求是什么？ —— 产品、开发、AI 对需求的理解一致吗？
• 怎么做？ —— 技术方案是否经过了充分思考？
• 做得对吗？ —— 怎么验证 AI 生成的代码符合预期？

这些问题本质上是不确定性。如果带着不确定性直接让 AI 开始写代码，结果就是反复返工、越改越乱。

答案：把不确定性前置

HCodeFlow 的核心思路很简单：

传统方式：  需求(模糊) → 直接写代码 → 发现问题 → 返工
HCodeFlow： 需求(确认) → 设计(确认) → AI 写代码 → 验证

我们通过两个关键阶段把不确定性消除在执行之前：

1. 需求确认阶段

在 AI 写任何代码之前，先由 PM Agent 把需求梳理清楚，生成结构化的 Spec（规格说明）。人只需要审批这个 Spec，确认它完整、准确。

效果：消除"需求理解不一致"这个最大的不确定性。

2. 概要设计确认阶段

需求确认后，Architect Agent 基于已确认的 Spec 生成技术方案。人再次审批，确认技术路线正确。

效果：消除"技术方案考虑不周"的不确定性。

人机协作的边界

经过这两个确认阶段后，确定性空间已经建立。此时：

• AI 的职责：在这个确定性空间里高速执行——写代码、写测试、跑检查
• 人的职责：维护和扩展这个确定性空间的边界——审批需求、审批设计、把控方向

┌─────────────────────────────────────────┐
│           人负责的确定性边界              │
│  ┌───────────┐   ┌───────────┐          │
│  │ 需求确认   │   │ 设计确认   │          │
│  └─────┬─────┘   └─────┬─────┘          │
│        │               │                │
│        └───────┬───────┘                │
│                ▼                        │
│  ┌─────────────────────────────────┐    │
│  │     AI 高速执行的确定性空间       │    │
│  │  编码 → 测试 → 检查 → 交付       │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

人不需要写代码，但需要确保 AI 理解要做什么、怎么做。

从 Spec 到代码：三铁律

在确定性空间内，AI 的执行遵循三条不可违反的铁律：

铁律	含义
No Spec, No Code	没有 Spec 就不写代码，Spec 是一切的前提
Spec is Truth	Spec 就是真相，代码必须与 Spec 完全一致
No Approval, No Execute	没有人的审批就不能执行，人始终掌控关键节点

这三条铁律确保 AI 的每一步都在确定性边界内运作。

实践中的工作流

具体到日常开发，HCodeFlow 用四个工作流覆盖所有场景：

工作流	适用场景	特点
Q0 轻量	小修小补、bug fix	最少流程，快速响应
A 纯后端	API 变更、数据库调整	后端 Agent 链路
B 纯前端	UI 调整、交互优化	前端 Agent 链路
C 全栈联动	新增业务实体	PM → Arch → Dev/FE → QA 全链路

无论哪个工作流，核心原则不变：先确认，再执行。

框架的框架

HCodeFlow 自身也是一个"确定性框架"：

• 编排层（本仓库）：定义通用的规范、Agent 行为、工作流规则，版本化管理
• 执行层（各业务项目）：项目特有的知识库和配置，在框架规范下运行
• 双向同步：框架推送给项目（upgrade.sh），项目验证过的改进收割回框架（harvest.sh）

这种结构确保了：框架的确定性可以持续演进，而不破坏各项目的自定义空间。

---

想了解具体怎么使用？前往 快速入门。