From 525c53a51a89bc87460e5ea903027ea221bdbba9 Mon Sep 17 00:00:00 2001
From: hmo <staymo7777@gmail.com>
Date: Fri, 17 Jul 2026 13:18:23 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20add=204th=20red=20line=20=E2=80=94=20im?=
 =?UTF-8?q?plement=20then=20sync=20spec;=20record=20learned=20lesson?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/dev-spec.md | 13 ++++++++++---
 docs/learned.md  |  1 +
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/dev-spec.md b/docs/dev-spec.md
index c96a104..144b2d3 100644
--- a/docs/dev-spec.md
+++ b/docs/dev-spec.md
@@ -1,6 +1,6 @@
 # 开发规范
 
-> 版本: v2.1 | 更新: 2026-07-16
+> 版本: v2.2 | 更新: 2026-07-17
 
 ---
 
@@ -13,6 +13,7 @@
 1. **先写 Spec，再写代码** — 没有 spec 的模块在 dashboard 不可见，视为未完成
 2. **部署必验** — 部署后不打开 K Tab 验证 = 部署未完成
 3. **不可见即不存在** — 组件不在 dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
+4. **实现后同步 Spec** — 每轮开发完毕后，必须将 specs/{module}.json 更新为与实际实现一致的状态。文档过期 = 等于没写
 
 ---
 
@@ -138,8 +139,14 @@ H: 需求文档 — 双轨体系覆盖不到的架构级/跨模块需求（性
   │      - ai_spec.tests 添加对应测试标识
   │      - 或在 tests_api.py 添加测试用例
   │
-  └─ 5. 提交 → 部署 → 验证
-         即以下"操作规范"
+  ├─ 5. 同步更新 Spec
+  │      - 将 specs/{module}.json 的 api/constraints/dependencies/architecture
+  │        更新为与实际实现一致
+  │      - 删除过时的描述，修正错误的假设
+  │      - 新增的字段、端点、配置项必须在 spec 中体现
+  │
+  └─ 6. 提交 → 部署 → 验证
+          即以下"操作规范"
 ```
 
 ### Git 操作规范
diff --git a/docs/learned.md b/docs/learned.md
index d7b724e..2cce70a 100644
--- a/docs/learned.md
+++ b/docs/learned.md
@@ -6,4 +6,5 @@
 - [YYYY-MM-DD] 问题: xxx | 根因: xxx | 正确做法: xxx
 
 ---
+- [2026-07-17] 问题: 配置完 key6 后没同步更新 usage_monitor spec，也不知道用户看到的 Dashboard 后端是 246 本地采集而非 Windows bridge | 根因: 没有先看 § spec 了解实际架构，开发完成后也没更新 spec | 正确做法: ①改代码前先看对应模块的 § spec 了解架构 ②改完后同步更新 spec 的 api/constraints/dependencies 与实际实现一致