doc: 新建文章

source/_posts/从一次tenantId联调bug，看我们该怎么给AI项目补齐harness.md

@@ -0,0 +1,264 @@
+---
+title: 从一次 tenantId 联调 bug，看我们该怎么给 AI 项目补齐 harness
+author: Gamehu
+date: 2026-03-07 20:30:00
+tags:
+  - AI Coding
+  - Harness
+  - 多租户
+  - 工程化
+categories:
+  - AI
+---
+<div class="tag-container">
+  <span class="ai-tag">AI</span>
+  <span class="sub-tag">工程化</span>
+</div>
+
+前几天我读了 OpenAI 那篇文章：[Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)。
+
+我读完最大的感受不是“AI 又强了”，而是另一个更接地气的结论：
+
+<span class="highlight-text">很多时候，不是模型不够强，而是你的工程环境没有把“正确性”暴露给模型。</span>
+
+这两天我正好在自己项目里处理一个非常典型的问题：运营端新增门店和校验门店名时，如果和其它租户重名会误报；员工后台接口也有类似的租户范围问题。表面上看只是个 `tenantId` bug，但整个过程把一个事实暴露得很彻底：
+
+**AI 想高效干活，前提不是 prompt 更长，而是 harness 更清楚。**
+
+---
+
+## 一、这次 bug 表面是租户问题，实质是“环境表达不清”
+
+最初的现象其实很迷惑：
+
+1. 运营端调用 `admin/store/checkName`
+2. 明明传了 `tenantId`
+3. 但接口判重却像是按别的租户在查
+
+如果只看 Controller 参数，你会以为“不是都传进来了吗”。  
+但真正往下追，就会发现系统里其实混着两套租户来源：
+
+- 请求里显式传入的 `tenantId`
+- 线程上下文里的 `TenantContextHolder`
+
+理论上，`TenantContextHolder` 也不是错的。因为网关或 filter 确实会从 header 里解析租户并写入上下文。问题在于：
+
+**后台管理接口的业务语义，不是‘当前会话属于哪个租户’，而是‘当前运营账号要操作哪个目标租户的数据’。**
+
+这两个概念，在多租户后台系统里根本不是一回事。
+
+所以这次真正的问题不是一句“代码写错了”，而是：  
+<span class="highlight-text">系统没有把“哪一个租户才是业务真相”表达得足够显式。</span>
+
+这就是 harness 问题。
+
+---
+
+## 二、OpenAI 那篇文章对我最有启发的，不是模型能力，而是“把环境当产品做”
+
+那篇文章里有几层意思我特别认同，我这里不逐字复述，只说我自己的理解。
+
+### 1）Agent 的上限，很大程度取决于它能不能直接看到真实运行环境
+
+如果模型只能读代码，看不到：
+
+- 实际 HTTP 请求长什么样
+- token 从哪里来
+- 当前服务到底连的是哪套数据库
+- 逻辑删除字段的业务语义是什么
+
+那它就很容易陷入一种“静态推理正确，动态结论错误”的状态。
+
+这次我们项目里就连续遇到了：
+
+- 代码已经改了，但运行中的服务没重启
+- `checkName` 返回 `true/false` 的语义，调用方理解反了
+- 数据库里能查到门店记录，但那条记录其实已经逻辑删除
+
+这些都不是大算法问题，而是**工程上下文没有被收束成一个可验证的工作台**。
+
+### 2）入口文档不该是经验大杂烩，而应该是导航页
+
+以前很多项目的 `AGENTS.md`、模块说明文档，最后都会越写越长。  
+每次踩坑补一条，最后谁都不想看，AI 也很难稳定执行。
+
+所以我这次顺手把项目里的规则做了一个调整：
+
+- `AGENTS.md` 和 `CLAUDE.md` 保留高层原则
+- 具体的联调、token、租户、契约规则下沉到 `docs/testing/`
+
+这不是为了“文档好看”，而是为了让规则能被持续修正，而不是散落在三个地方互相漂移。
+
+{% asset_img 1.jpg %}
+
+### 3）真正有价值的，不是“写了规则”，而是“规则能被验证”
+
+如果规则只是：
+
+- 显式传 `tenantId`
+- 统一走网关
+- 做真实 HTTP 测试
+
+那它还是有点抽象。
+
+真正有效的规则必须长成下面这样：
+
+- 运营端接口测试时，直接向用户索取运营端 token
+- 同一个 token，对照请求 `tenantId=A/B`
+- 至少保留一条原始 HTTP 响应
+- 必要时补查数据库解释“为什么接口返回这样”
+
+一旦规则写到这个粒度，AI 和人都更难自欺欺人。
+
+---
+
+## 三、这次我把项目规则怎么改了
+
+结合这次联调前后对比，我最后把项目里的规则改成了三层。
+
+### 第一层：入口文档只讲方向，不再堆细则
+
+我在项目根目录 `AGENTS.md` 和 `goodsop-app-server/CLAUDE.md` 里增加了一个明确入口：
+
+- `docs/testing/README.md`
+- `docs/testing/admin-http-harness.md`
+- `docs/testing/tenant-data-scope.md`
+
+意思很简单：  
+<span class="highlight-text">入口文档只负责告诉 AI“去哪儿看”，真正经常变化的实战规则集中维护。</span>
+
+### 第二层：把运营端 HTTP harness 写成可执行规则
+
+这次新增的 `admin-http-harness.md` 里，我重点固化了几件事：
+
+1. 所有运营端联调统一走 `http://localhost:9999`
+2. 测试运营端接口时，必须直接问用户要 token
+3. 同一轮验证里，优先用同一个 token 只切换 query `tenantId`
+4. 每次改动至少保留 1 个真实业务接口的原始响应
+5. 失败排查顺序固定为：连通性 -> 网关 -> Nacos -> 鉴权上下文 -> 业务代码/SQL
+
+这几条看起来朴素，但非常关键。因为 agent 一旦没有这些硬边界，就会在“如何拿 token”“是不是该直连服务”“这个请求到底算不算验证”上浪费很多轮次。
+
+### 第三层：把租户数据范围语义写明白
+
+`tenant-data-scope.md` 里，我把这次最核心的结论直接写死了：
+
+1. 后台管理接口的数据范围以显式传入的目标 `tenantId` 为准
+2. `TenantContextHolder` 是上下文机制，不是后台业务真相
+3. `checkName/checkPhone` 必须同时校验接口契约和逻辑删除语义
+
+尤其是第三点，这次特别有代表性。
+
+我们一开始看到有些门店名“库里明明有记录，接口却返回可用”，很容易怀疑代码没改对。  
+后来一查数据库才发现：那几条是逻辑删除记录。也就是说，**数据库里有行，不等于业务上仍占用名称**。
+
+这个结论如果不被写进规则里，下次还会重复争论。
+
+{% asset_img 2.jpg %}
+
+---
+
+## 四、这次代码层面的前后对比，也很说明问题
+
+如果只看代码，这次改动其实不算复杂，核心就是两件事。
+
+### 改动前
+
+- Controller 收到了 `tenantId`
+- 但部分 service 逻辑还是依赖 `TenantContextHolder`
+- `checkName` 的返回在失败时没有稳定给出 `data=false`
+- 联调时容易把“请求头租户”“目标业务租户”“逻辑删除记录”混在一起
+
+### 改动后
+
+- `admin/store/*`、`admin/consultant/*` 显式把 `tenantId` 往下传
+- 需要上下文的地方用 `TenantBroker.applyAs(tenantId, ...)`
+- `checkName` 改成：
+  - 可用：`data=true`
+  - 不可用：`data=false`
+- 真实接口回归不只看代码，还做了：
+  - `tenantId=5584` 与 `tenantId=1` 对照请求
+  - 门店新增、关店、员工新增、修改、离职
+  - 必要时补查 PG 解释结果
+
+这里最关键的，不是“把某个 if 改对了”，而是从“我觉得这样应该对”变成了“我能证明它对，而且能解释为什么”。
+
+这就是 harness 的价值。
+
+{% asset_img 3.jpg %}
+
+---
+
+## 五、对我们这种业务项目来说，AI 真正缺的不是智商，而是工作台
+
+很多人谈 AI Coding，喜欢把重点放在模型选择、prompt 技巧、上下文窗口大小。
+
+这些当然重要，但我现在越来越觉得，对真实业务项目来说，下面这些东西更值钱：
+
+### 1）可直接使用的环境入口
+
+- 正确的网关地址
+- 正确的 token 获取方式
+- 正确的数据库连接信息
+- 正确的日志和服务发现排查路径
+
+### 2）可复用的验证脚本或验证模板
+
+不是“你自己去测一下”，而是给出：
+
+- 请求地址
+- header
+- body
+- 对照 tenantId
+- 预期差异
+
+### 3）不会漂移的规则系统
+
+很多团队的问题不是没有规则，而是规则散在聊天记录、群公告、项目文档、某个人脑子里。
+
+一旦 AI 进场，这种问题会被放大得更厉害。  
+因为 AI 特别依赖“哪个文档才是 system of record”。
+
+---
+
+## 六、我准备继续往前做的，不只是写博客
+
+这次规则改完以后，我更想补的是一套更完整的 harness，而不只是几段说明文档。
+
+如果继续做，我下一步大概率会补这些东西：
+
+1. `scripts/verify-admin-store.sh`
+   - 自动完成 `page/checkName/create/close`
+2. `scripts/verify-admin-consultant.sh`
+   - 自动完成 `page/checkPhone/create/update/resign`
+3. 运行态环境说明
+   - 当前服务实际连接哪套 PG/Redis
+4. 接口契约回归样例
+   - 尤其是 `data/code/msg` 这种容易被误解的接口
+
+因为写到最后我越来越确信一件事：
+
+<span class="highlight-text">AI 工程化的竞争力，不是“谁的模型更像天才”，而是“谁先把自己的真实环境整理成一个不会误导 agent 的工作台”。</span>
+
+---
+
+## 结语
+
+OpenAI 那篇文章给我的最大提醒，是别把 agent 当成一个只会补代码的聊天机器人。
+
+它更像一个能力很强、速度很快，但极度依赖环境质量的工程协作者。
+
+如果你的环境是模糊的：
+
+- 文档入口混乱
+- token 获取方式混乱
+- 租户语义混乱
+- 接口契约混乱
+
+那 AI 就会在这些噪音里反复打转。
+
+但如果你把 harness 补起来，很多原来需要人肉盯着的事情，就会突然顺很多。
+
+所以这次一个看似普通的 `tenantId` bug，最后给我的启发反而比 bug 本身更大：
+
+**以后优化 AI Coding，不只是继续追模型，也要继续做环境。**

source/_posts/搭建我的专属AI助手：OpenClaw云服务器部署实战指南.md

@@ -10,10 +10,11 @@ tags:
 categories:
   - 工具
 date: 2026-02-27 22:30:00
-updated: 2026-03-06 14:10:00
+updated: 2026-03-09 14:30:00
 ---
 
 > 📢 **更新日志**：
+> - 2026-03-09 补充 `HEARTBEAT.md` 抢占主会话的排障记录，修正文中 Docker Compose 版本与记忆机制描述，新增“升级是否成功”的核验方法。
 > - 2026-03-06 新增 `Step-3.5-Flash` 接入与会话级 `/model` 切换说明，补充默认模型不切全局、只切当前会话的使用方式。
 > - 2026-03-03 新增"记录系统优化"章节，解决会话文件膨胀问题，添加自动归档和结构化存储方案。
 
@@ -24,7 +25,7 @@ updated: 2026-03-06 14:10:00
 
 ## 写在前面
 
-最近刷到不少 OpenClaw 的文章，演示零成本安装、智能体集群、国内部署经验。我手头正好有台 2 核 3G 的云服务器闲置着，决定动手搭建一个专属 AI 助手。
+最近刷到不少 OpenClaw 的文章，演示零成本安装、智能体集群、国内部署经验。我手头正好有台配置不高的云服务器闲置着，决定动手搭建一个专属 AI 助手。
 
 但这篇文章不是推广，是<span class="highlight-text">真实的部署踩坑记录</span>。整个过程历时数小时，遇到了 OOM 内存不足、配置验证失败、防火墙规则冲突等一系列问题，把完整的解决过程记录下来。
 
@@ -79,7 +80,7 @@ curl -fsSL https://get.docker.com | sh
 
 # 验证安装
 docker --version  # Docker version 29.2.1
-docker compose version  # Docker Compose version v5.5.1
+docker compose version  # Docker Compose version v5.1.0
 ```
 
 国内用户建议配置镜像加速，编辑 `/etc/docker/daemon.json`：
@@ -471,7 +472,7 @@ OpenClaw 的持久记忆系统让它能跨会话记住你的偏好、项目信
 
 1. **自动记忆**：所有对话自动存入 SQLite，跨会话保持上下文
 2. **结构化记忆**：AI 主动读取 MEMORY.md 了解你的背景和偏好
-3. **持续更新**：OpenClaw 会定期根据对话更新记忆文件
+3. **持续更新**：OpenClaw 可以通过 heartbeat 或维护任务定期整理记忆，但主会话不建议配置成高频主动提醒模式
 
 ### 测试持久记忆
 
@@ -1610,6 +1611,7 @@ cd /opt/openclaw && docker compose restart
 | 16 | 会话记录膨胀失控 | 部署结构化记录系统 + 每日自动归档 + 分类存储 |
 | 17 | 定时任务推送全到 main bot | `jobs.json` 每个 job 加 `agentId` + `delivery.accountId` |
 | 18 | 想切 Step 却误改全局默认模型 | 保持默认模型不动，使用 `/model ...` 做会话级切换 |
+| 19 | `HEARTBEAT.md` 抢占 `main` 主会话 | 保留 heartbeat，但改成低风险静默版；主动提醒交给 cron 或其他 bot |
 
 ---
 
@@ -1869,6 +1871,89 @@ OpenClaw 默认上下文预算与实际模型窗口不一致时，会导致系
 
 ---
 
+## 补充坑位：HEARTBEAT 抢占主会话（第19坑）
+
+后来我又遇到过一次比 compaction 更隐蔽的问题：**Telegram 能收到消息，但主 Bot 要么完全不回，要么要等很久才回。**
+
+### 现象
+
+- 给 `@GameHuOpenclaw_bot` 发消息，长时间没有任何回复
+- 日志能看到消息进入 `lane=session:agent:main:main`
+- 但执行结束后没有正常的 `sendMessage`
+- 重启后可能短暂恢复，过一阵又复发
+
+### 真实根因
+
+这次不是 Telegram 渠道挂了，也不是容器死了，而是 **`HEARTBEAT.md` 的主动任务把 `main` 主会话占掉了**。
+
+排查时我在 `sessions.json` 里发现，`agent:main:main` 这条映射的 `origin.provider` 已经不是 Telegram，而是 `heartbeat`。结果就是：
+
+- 你的正常聊天消息仍然会进入 `main`
+- 但 `main` 会话上下文已经被 heartbeat 任务污染
+- 最终表现成“不回复”或“回复极慢”
+
+### 为什么会发生
+
+这里有个很容易误解的点：`HEARTBEAT.md` 很有用，但它**不是核心运行时依赖**。OpenClaw 的 heartbeat 机制本身会启动，但如果你把 `HEARTBEAT.md` 写成“主动检查 git、主动提醒发博客、主动输出长段内容”的详细任务单，它就可能在重启、升级尝试或异常恢复后占用 `main session`。
+
+我这次现场看到的情况是：
+
+- 启动日志显示 `update available (latest): v2026.3.7 (current v2026.2.27)`
+- 说明当时服务器实际跑的仍然是 `v2026.2.27`
+- 也就是说，之前那次“升级”并没有真正成功
+- 但升级尝试或相关重启之后，`main` 会话映射被 heartbeat 改写了
+
+所以这次故障更准确地说，是**升级尝试触发重启后，暴露了 heartbeat 抢占主会话的问题**，而不是“新版本本身有 bug”。
+
+### 如何判断是不是这个问题
+
+如果你遇到“消息进来了但 Bot 不回”，重点看两处：
+
+1. `docker compose logs -f openclaw-gateway`
+2. `~/.openclaw/agents/main/sessions/sessions.json`
+
+如果日志里反复出现主会话执行，但没有正常发消息，同时 `sessions.json` 里 `agent:main:main.origin.provider = heartbeat`，基本就能确定是这个坑。
+
+### 我最终采用的修复方式
+
+1. 先备份 `sessions.json` 和当前 session 文件
+2. 删除被污染的 `agent:main:main` 映射
+3. 重启 `openclaw-gateway`
+4. 把原来的激进版 `HEARTBEAT.md` 改成低风险版
+
+低风险版的原则是：
+
+- 默认只返回 `HEARTBEAT_OK`
+- 只做静默的记忆维护
+- 不主动发博客提醒
+- 不做 git 巡检
+- 不输出聊天式长文本
+
+### 最稳的实践建议
+
+如果你的 `main` bot 是日常高频对话入口，我现在的建议很明确：
+
+- `HEARTBEAT.md` 可以保留
+- 但只保留**静默记忆维护**能力
+- 主动提醒类任务放到 cron 或单独 bot
+- 不要再把“像助手一样主动找你说话”的逻辑写进主工作区 heartbeat
+
+这样既能保留记忆整理能力，又不会再次把主聊天打挂。
+
+### 顺手补一句：如何确认升级到底成没成功
+
+不要只看自己执行过 `git pull` 或 `docker compose restart`，要以**启动日志里的版本号**为准。
+
+如果日志仍然显示：
+
+```text
+update available (latest): v2026.3.7 (current v2026.2.27)
+```
+
+那结论很简单：**你还在跑旧版本，升级并没有真正完成。**
+
+---
+
 ## 实际使用体验
 
 部署完成后，通过 Telegram 与 Bot 对话：
@@ -1912,3 +1997,4 @@ OpenClaw 默认上下文预算与实际模型窗口不一致时，会导致系
 - [X - @elvissun](https://x.com/elvissun/status/2025920521871716562)
 - [X - @stark_nico99](https://x.com/stark_nico99/status/2026235176150581282)
 - [X - @AI_Jasonyu](https://x.com/AI_Jasonyu/status/2026455606970954087)    
+- [乔帮主精选Skills](https://x.com/vista8/status/2029935446810308817?s=12&t=VOZ-RfoIknMyLO5G8PjbRg)

source/_posts/规范驱动开发的陷阱.md

@@ -14,17 +14,43 @@ categories:
   <span class="sub-tag">思考</span>
 </div>
 
-## 引言
+最近看到一篇关于规范驱动开发的文章，作者指出一个有趣的现象：<span class="highlight-text">规范也是文档，而文档总是过时的</span>。
 
-最近看到一篇关于规范驱动开发的文章,作者指出一个有趣的现象:<span class="highlight-text">规范也是文档,而文档总是过时的</span>。
+这话说的没错，但我有一点点不同看法。规范驱动开发不是过时了，而是在AI时代<span class="gradient-text">进化了</span>。
 
-这话说的没错,但我有一点点不同看法。规范驱动开发不是过时了,而是在AI时代<span class="gradient-text">进化了</span>。或者说抛开AI至少在所有重要业务实现的前期阶段是必要的。
+不过，在讲怎么进化之前，我想先聊一个更底层的问题——<span class="highlight-text">为什么有时候规范是最新的，效率还是没提升？</span>
 
-## 一、文档驱动发展的历史脉络
+<!-- more -->
 
-### 早期困境:口头沟通的代价
+---
+
+## 一、先讲一个快手的案例
+
+前段时间快手技术团队发了一篇复盘，讲他们万人组织怎么用AI提升研发效能。看完我挺有感触的。
+
+他们2024年就全员推广AI编程工具，代码生成率干到了30%+，部分业务线甚至40%+。调研结果显示，开发同学主观体感效率提升了20-40%。
+
+看起来很美对吧？
+
+但看组织层面的数据：<span class="warning">需求交付周期基本没变，需求吞吐量也没明显提升。</span>
+
+快手把这个问题叫做<span class="gradient-text">"AI研发提效陷阱"</span>：
+
+```
+用AI开发工具 ≠ 个人提效 ≠ 组织提效
+```
+
+这事给我提了个醒。我们聊规范驱动开发，不能只聊"规范怎么保持最新"，还得聊<span class="highlight-text">"规范怎么真正驱动交付"</span>。
+
+不然就像快手早期那样——工具用得很溜，但组织效率没动静。
+
+---
+
+## 二、文档驱动发展的历史脉络
 
-在软件工程的早期,项目主要依赖<span class="warning">口头沟通</span>和<span class="warning">个人记忆</span>。这种方式在小型团队里还行,但一旦团队扩大或人员流动,问题就暴露无遗:
+### 早期困境：口头沟通的代价
+
+在软件工程的早期，项目主要依赖<span class="warning">口头沟通</span>和<span class="warning">个人记忆</span>。这种方式在小型团队里还行，但一旦团队扩大或人员流动，问题就暴露无遗：
 
 - 需求在传递中变形
 - 知识随着人员离职而流失
@@ -33,137 +59,154 @@ categories:
 
 ### 文档驱动的出现
 
-为了解决这些问题,<span class="gradient-text">文档驱动开发</span>应运而生。它主要经历了几个阶段:
+为了解决这些问题，<span class="gradient-text">文档驱动开发</span>应运而生。它主要经历了几个阶段：
 
 **1. 瀑布模型的PRD时代**
 - 详细的PRD文档
 - 完整的设计文档
 - 严格的变更流程
-- 优点:标准化、可追溯
-- 缺点:僵化、响应慢
+- 优点：标准化、可追溯
+- 缺点：僵化、响应慢
 
 **2. 敏捷时代的轻文档**
 - 用户故事代替详细PRD
 - 活跃的代码注释
 - Wiki 风格的文档
-- 优点:灵活、快速迭代
-- 缺点:文档碎片化、维护困难
+- 优点：灵活、快速迭代
+- 缺点：文档碎片化、维护困难
 
 ### 文档驱动的核心价值
 
-不管哪个阶段,文档驱动都有其不可替代的价值:
+不管哪个阶段，文档驱动都有其不可替代的价值：
+
+- **知识沉淀**：团队知识不会随人员流动而丢失
+- **沟通效率**：减少反复沟通的成本
+- **质量保障**：明确的规范避免随意改动
+- **可追溯性**：决策过程有据可查
+- **新人友好**：降低入职门槛
 
-- **知识沉淀**:团队知识不会随人员流动而丢失
-- **沟通效率**:减少反复沟通的成本
-- **质量保障**:明确的规范避免随意改动
-- **可追溯性**:决策过程有据可查
-- **新人友好**:降低入职门槛
+但这里有个隐含假设：<span class="highlight-text">文档是给人看的，人会判断、会质疑、会沟通。</span>
+
+---
 
-## 二、AI时代的双重效应
+## 三、AI时代的三重效应
 
-### 负面影响:过时规范更危险
+### 第一重：过时规范更危险
 
-AI的出现,让文档过时的代价<span class="warning">成倍增加</span>。
+AI的出现，让文档过时的代价<span class="warning">成倍增加</span>。
 
-**人类工程师的行为模式**:
+**人类工程师的行为模式**：
 - 读到过时文档 → 发现不对 → 会问"这文档好像有问题"
-- 有判断力,会质疑,会沟通
+- 有判断力，会质疑，会沟通
 - 会用实际代码来验证文档
 
-**AI Agent的行为模式**:
+**AI Agent的行为模式**：
 - 读到过时规范 → 严格执行
-- 缺乏质疑能力,假设规范总是正确的
+- 缺乏质疑能力，假设规范总是正确的
 - 会按照过时的规范写出过时的代码
 
-<span class="important-note">问题就在这里:过时的设计文档只会误导碰巧读到它的人类工程师,而过时的规范会误导不知变通的AI Agent。</span>
+<span class="important-note">过时的设计文档只会误导碰巧读到它的人类工程师，而过时的规范会误导不知变通的AI Agent。</span>
+
+### 第二重：AI成为文档维护的解决方案
+
+但硬币的另一面是：<span class="gradient-text">AI恰恰是解决文档维护难题的最佳工具</span>。
+
+为什么这么说？因为文档维护的本质是：<span class="highlight-text">让文档与代码/现实保持同步</span>。
+
+而AI擅长的正是：
+- **理解代码**：分析代码结构和依赖
+- **生成文档**：根据代码自动生成文档
+- **检测差异**：对比文档和代码的差异
+- **自动更新**：根据代码变化更新文档
 
-AI Agent会自信满满地执行一个早已脱离实际的计划,根本不会发现哪里不对。
+### 第三重：个人提效≠组织提效（新增）
 
-### 正面影响:AI成为文档维护的解决方案
+这是快手案例给我最大的启发。
 
-但硬币的另一面是:<span class="gradient-text">AI恰恰是解决文档维护难题的最佳工具</span>。
+我们假设这样一个场景：
+- 规范是最新的，AI能自动维护
+- 每个开发同学都用AI写代码，个人效率提升30%
+- 但需求交付周期还是老样子
 
-为什么这么说?因为文档维护的本质是:<span class="highlight-text">让文档与代码/现实保持同步</span>。
+问题出在哪？
 
-而AI擅长的正是:
-- **理解代码**:分析代码结构和依赖
-- **生成文档**:根据代码自动生成文档
-- **检测差异**:对比文档和代码的差异
-- **自动更新**:根据代码变化更新文档
+<span class="highlight-text">规范只解决了"做什么"和"怎么做"，但没解决"怎么协作交付"。</span>
 
-这正是文档维护需要的核心能力。
+快手早期的"智能化1.0"就是这个状态：推广AI编码工具、AI测试工具、AI CR工具，单点看每个工具都很好用，但端到端的流程没打通。
 
-## 三、规范驱动在AI时代的进化
+就像一条高速公路，每辆车的引擎都升级了，但收费站还是人工收费，整体通行速度能快吗？
+
+---
+
+## 四、规范驱动在AI时代的进化
 
 ### 从静态文档到动态契约
 
-传统的规范驱动是这样的:
+传统的规范驱动是这样的：
 ```
-人类写规范 → 代码实现 → 规范过时 → 人类更新规范(如果记得的话)
+人类写规范 → 代码实现 → 规范过时 → 人类更新规范（如果记得的话）
 ```
 
-AI时代的规范驱动是这样的:
+AI时代的规范驱动应该是这样的：
 ```
 人类描述意图 → AI草拟规范 → 人类审阅批准 → AI执行并更新规范
 ```
 
-<span class="gradient-text">关键变化:规范不再是静态的"圣旨",而是动态的"活文档"。</span>
+<span class="gradient-text">关键变化：规范不再是静态的"圣旨"，而是动态的"活文档"。</span>
 
 ### 从单向传递到双向反馈
 
-**传统模式**:
+**传统模式**：
 - 人类 → 规范 → 代码
-- 单向传递,信息单向流动
+- 单向传递，信息单向流动
 
-**AI模式**:
+**AI模式**：
 - 人类 ↔ 规范 ↔ AI ↔ 代码
-- 双向反馈,信息循环流动
+- 双向反馈，信息循环流动
 
-当AI Agent在执行过程中发现:
+当AI Agent在执行过程中发现：
 - API不支持规范中假设的方式
 - 有现成的组件可以复用
 - 某些方案不切实际
 
-它会<span class="highlight-text">自动更新规范</span>,而不是等人类发现问题。
+它会<span class="highlight-text">自动更新规范</span>，而不是等人类发现问题。
 
-这就像把任务交给优秀的初级工程师:
-- 发现问题自己更新工单
-- 不会等着你去发现问题
-- 会主动告诉你"之前的假设不对,我用另一种方式实现了"
+### 从单点规范到端到端流程（新增）
 
-### 从人工维护到自动同步
+这是结合快手经验的新认识。
 
-以前,文档更新完全依赖人工。工程师要:
-- 记得更新文档(总是忘记)
-- 抽时间更新文档(总被其他任务挤占)
-- 保持文档准确性(几乎不可能)
+以前我们理解的规范，主要是<span class="highlight-text">实现规范</span>——接口怎么设计、代码怎么写、测试怎么覆盖。
 
-现在,AI Agent在执行任务的同时,就能:
-- 检测到规范与实际实现的差异
-- 自动更新规范
-- 说明变更原因
+但AI时代，规范应该延伸到<span class="gradient-text">端到端的交付流程</span>：
 
-<span class="important-note">没有人需要专门记着去更新文档。因为更新文档本身就是AI工作的一部分。</span>
+- **需求分析规范**：AI怎么理解需求、怎么拆解任务
+- **协作规范**：AI Agent之间怎么分工、怎么交接
+- **质量门禁规范**：什么情况下可以进入下一阶段
+- **反馈规范**：AI怎么汇报进度、怎么暴露阻塞
 
-## 四、AI为什么能做得更好?
+快手"智能化2.0"的核心转变，就是从"推广AI工具"回归到"<span class="highlight-text">如何用AI提升需求端到端交付效率</span>"。
+
+---
+
+## 五、AI为什么能做得更好？
 
 ### 1. AI不知疲倦
 
-文档维护是<span class="warning">隐形工作</span>:
+文档维护是<span class="warning">隐形工作</span>：
 - 不容易被看见
 - 不容易被奖励
 - 但需要持续投入
 
-人类会厌烦、会忘记、会偷懒。但AI不知疲倦,每次执行任务都会更新规范。
+人类会厌烦、会忘记、会偷懒。但AI不知疲倦，每次执行任务都会更新规范。
 
 ### 2. AI有上下文理解能力
 
-传统工具(如Swagger生成API文档)只能:
+传统工具（如Swagger生成API文档）只能：
 - 基于代码注释生成
 - 基于代码结构推断
 - 缺乏业务上下文
 
-而AI能够:
+而AI能够：
 - 理解代码的业务意图
 - 分析代码的依赖关系
 - 推断代码的设计决策
@@ -171,166 +214,187 @@ AI时代的规范驱动是这样的:
 
 ### 3. AI可以双向沟通
 
-传统工具是单向的:代码 → 文档。
+传统工具是单向的：代码 → 文档。
+
+但AI可以双向：
+- 代码 → 规范（从实现推断规范）
+- 规范 → 代码（从规范生成代码）
+- 规范 ↔ AI（在执行过程中持续对话）
 
-但AI可以双向:
-- 代码 → 规范(从实现推断规范)
-- 规范 → 代码(从规范生成代码)
-- 规范 ↔ AI(在执行过程中持续对话)
+这种双向沟通，让规范真正"活"起来。
 
-这种双向沟通,让规范真正"活"起来。
+### 4. AI可以建立反馈闭环（新增）
 
-### 4. AI有持续学习能力
+这是组织提效的关键。
 
-随着项目进展,AI可以学习:
-- 哪些规范模式有效
-- 哪些规范会误导AI
-- 哪些细节需要反馈
-- 哪些变更需要批准
+快手的经验表明，要建立三个层面的反馈：
 
-通过机器学习,整个系统会越来越智能。
+**第一层：规范与代码的反馈**
+- AI发现实现与规范不符 → 更新规范
 
-## 五、如何实现进化的规范驱动?
+**第二层：个人与任务的反馈**
+- AI完成子任务 → 更新整体进度 → 人类看到阻塞点
+
+**第三层：任务与组织的反馈**
+- 度量数据回流 → 识别瓶颈 → 调整规范
+
+<span class="highlight-text">只有这三层反馈都打通，个人效率才能传导到组织效率。</span>
+
+---
+
+## 六、如何实现进化的规范驱动？
 
 ### 1. 确立双向维护机制
 
-规范不只是人类写的,也不只是AI写的。双方都要维护。
+规范不只是人类写的，也不只是AI写的。双方都要维护。
 
-**人类负责**:
+**人类负责**：
 - 设定目标和意图
 - 审阅和批准AI草拟的规范
 - 做架构决策和业务判断
 - 处理异常情况和边界条件
 
-**AI负责**:
+**AI负责**：
 - 根据意图草拟规范
 - 拆解任务和子任务
 - 执行代码实现
-- 更新规范(发现变化时)
+- 更新规范（发现变化时）
 - 反馈执行中的发现
 
 ### 2. 把握反馈颗粒度
 
-这是最难的平衡:
+这是最难的平衡：
 
-**反馈太多**:
+**反馈太多**：
 - 规范变成噪音
 - 人类习惯性无视
 - 失去规范的意义
 
-**反馈太少**:
+**反馈太少**：
 - 人类失去控制感
 - 不知道AI做了什么
 - 无法及时纠正方向
 
-<span class="important-note">把握好颗粒度的关键:只反馈那些改变方向的决策。</span>
+<span class="important-note">把握好颗粒度的关键：只反馈那些改变方向的决策。</span>
 
-AI不需要汇报每行代码怎么写,只需要汇报:
-- 发现了现成的组件(不用新建)
-- API不支持某种方式(换了个实现)
-- 发现了未预料的限制(调整了方案)
+AI不需要汇报每行代码怎么写，只需要汇报：
+- 发现了现成的组件（不用新建）
+- API不支持某种方式（换了个实现）
+- 发现了未预料的限制（调整了方案）
 
 ### 3. 建立审查和批准机制
 
-让AI更新规范,需要两个前提:
+让AI更新规范，需要两个前提：
 
-<span class="highlight-text">信任</span> - 相信AI不会乱改规范
-<span class="highlight-text">机制</span> - 有审查机制,让人类能看到并批准/驳回AI的更新
+<span class="highlight-text">信任</span> - 相信AI不会乱改规范  
+<span class="highlight-text">机制</span> - 有审查机制，让人类能看到并批准/驳回AI的更新
 
 缺一不可。
 
-### 4. 设计增量更新流程
+### 4. 配套度量机制
 
-不是每次都从头重写规范,而是:
-- 标记哪些部分被更新了
-- 说明更新的原因
-- 提供变更的上下文
-- 让人类可以快速审阅
+这是快手给我的最大启发。
 
-## 六、一个实际例子
+规范驱动进化不能只凭感觉，得有数据验证。快手建立了三层度量：
 
-来看一个我实际工作中的例子。当我让AI完成一个HTTP接口联调功能后,它自动更新了团队的开发规范文档:
+**过程指标**：AI代码生成率、AI CR采纳率  
+**结果指标**：需求交付周期、需求吞吐量  
+**健康度指标**：代码质量、线上稳定性
 
-{% asset_img ai-auto-update-spec.png AI自动更新规范文件的Git diff示例 %}
+<span class="highlight-text">关键是：不能只盯着过程指标。</span>
 
-上图展示了一个真实的场景:左侧是原有规范,右侧是AI自动补充的新内容。可以看到AI在`HTTP 自动化测试规范`部分新增了详细的测试要求,包括:
+AI代码生成率30%固然好看，但如果需求交付周期没变，说明规范只在编码环节生效，没有打通全流程。
 
-- **必须做1个真实接口自动验证** - 每次改动后自动执行业务接口测试
-- **默认验证用例(运营端)** - 提供具体的接口调用示例
-- **租户隔离对照测试(必做)** - 验证多租户隔离逻辑
-- **命令模板(可直接执行)** - 提供可执行的curl命令
-- **失败判定优先级** - 明确问题排查的顺序
+度量不是为了考核，是为了<span class="gradient-text">验证规范是否真的驱动了交付</span>。
 
-这个例子完美诠释了什么是"进化的规范驱动":**AI不仅执行代码,还主动更新配套文档,让规范始终保持与实现同步**。
+### 5. 设计增量更新流程
 
-再来看另一个更简单的例子。
-
-你写道:
+不是每次都从头重写规范，而是：
+- 标记哪些部分被更新了
+- 说明更新的原因
+- 提供变更的上下文
+- 让人类可以快速审阅
 
-> "在设置页面加个能跟随系统偏好的深色模式开关。"
+---
 
-协调Agent读取代码库,草拟一份规范:
+## 七、一个实际例子
 
-1. 添加开关组件
-2. 接入preference store
-3. 更新CSS变量
+来看一个我实际工作中的例子。当我让AI完成一个HTTP接口联调功能后，它自动更新了团队的开发规范文档：
 
-你扫了一眼,发现漏掉了"跨会话保存选择",于是补上一句。
+{% asset_img ai-auto-update-spec.png AI自动更新规范文件的Git diff示例 %}
 
-你点击批准。Agent开始干活。
+上图展示了一个真实的场景：左侧是原有规范，右侧是AI自动补充的新内容。可以看到AI在`HTTP 自动化测试规范`部分新增了详细的测试要求，包括：
 
-15分钟后,其中一个Agent更新了规范:
+- **必须做1个真实接口自动验证** - 每次改动后自动执行业务接口测试
+- **默认验证用例（运营端）** - 提供具体的接口调用示例
+- **租户隔离对照测试（必做）** - 验证多租户隔离逻辑
+- **命令模板（可直接执行）** - 提供可执行的curl命令
+- **失败判定优先级** - 明确问题排查的顺序
 
-> "在代码库里找到了现成的Theme Provider。已直接接入,未创建新store。"
+这个例子完美诠释了什么是"进化的规范驱动"：<span class="highlight-text">AI不仅执行代码，还主动更新配套文档，让规范始终保持与实现同步</span>。
 
-你审查代码变更(已按Agent和任务清晰分组)。
+但更重要的是，我开始关注另一个指标：<span class="gradient-text">这个规范更新后，团队的整体交付节奏有没有变化？</span>
 
-现在,这份规范反映了实际做出来的东西,而不是最初计划的东西。
+不只是"规范是最新的"，而是"最新的规范有没有让协作更顺畅"。
 
-<span class="gradient-text">最重要的是,没人需要专门记着去更新它。</span>
+---
 
-## 七、这种模式的推广
+## 八、这种模式的推广
 
-不只是代码规范,其他文档也可以这样进化:
+不只是代码规范，其他文档也可以这样进化：
 
 ### API文档
-- 传统:手动编写,过时即误导
-- 进化:AI解析代码和注释,自动生成和更新
+- 传统：手动编写，过时即误导
+- 进化：AI解析代码和注释，自动生成和更新
 
 ### 架构文档
-- 传统:画完就扔,没人更新
-- 进化:AI分析依赖关系,自动绘制和更新架构图
+- 传统：画完就扔，没人更新
+- 进化：AI分析依赖关系，自动绘制和更新架构图
 
-### 测试文档
-- 传统:手工编写,用例过时
-- 进化:AI执行测试,自动记录结果和覆盖率
+### 流程规范
+- 传统：写进Wiki，变成摆设
+- 进化：AI在执行中识别瓶颈，建议流程优化
 
-### 入职文档
-- 传统:一次性编写,快速过时
-- 进化:AI分析项目结构,动态生成入职指南
+<span class="highlight-text">流程规范特别值得强调。</span>快手的经验表明，AI时代的流程规范应该回答这些问题：
 
-## 八、结论
+- 需求怎么拆解成AI可执行的任务？
+- 多个AI Agent怎么协作？
+- 人类在什么节点介入？
+- 怎么度量端到端效率？
 
-文档维护是软件工程的老大难问题,AI时代这个问题变得更严重了。
+这些不是技术细节，是<span class="gradient-text">组织效能的基础设施</span>。
+
+---
+
+## 九、结论
+
+文档维护是软件工程的老大难问题，AI时代这个问题变得更严重了。
 
 但AI也带来了<span class="gradient-text">前所未有的机遇</span>。
 
-解决思路不是放弃文档驱动,而是让文档驱动<span class="highlight-text">进化</span>:
+解决思路不是放弃文档驱动，而是让文档驱动<span class="highlight-text">进化</span>：
 
 - 从静态文档到动态契约
 - 从人工维护到自动同步
 - 从单向传递到双向反馈
-- 从一次性编写到持续演进
+- 从单点规范到端到端流程
+- 从主观感觉到数据度量
+
+<span class="gradient-text">规范不是人类单方面写的"圣旨"，而是人类和AI共同维护的"活文档"。</span>
 
-<span class="gradient-text">规范不是人类单方面写的"圣旨",而是人类和AI共同维护的"活文档"。</span>
+但记住快手那个教训：<span class="highlight-text">规范保持最新只是第一步，让规范真正驱动端到端交付，才是最终目标。</span>
 
-这才是规范驱动开发在AI时代的正确打开方式。
+不然就会出现那种尴尬的局面——每个环节都很高效，但整体就是快不起来。
+
+---
 
 ## 参考
 
-原文: https://x.com/dotey/status/2026146560862474482
+原文：[https://x.com/dotey/status/2026146560862474482](https://x.com/dotey/status/2026146560862474482)
+
+快手研发范式复盘：[《快手万人组织 AI 研发范式 跃迁之路：从平台化、数字化、精益化到智能化》](https://mp.weixin.qq.com/s/Ejxpxn_MrJ1PDf-K38MpEg)
 
-相关阅读:
-- Multi-Agent Orchestration Patterns
-- Documentation as Code
-- Living Documentation
+相关阅读：
+- [Multi-Agent Orchestration Patterns](https://www.anthropic.com/research/multi-agent-orchestration)
+- [Documentation as Code](https://www.writethedocs.org/guide/docs-as-code/)
+- [Living Documentation](https://leanpub.com/livingdocumentation)