diff --git a/CLAUDE.md b/CLAUDE.md index 8c9a05f..02ceee2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,14 @@ - **Implementer**(便宜模型,用户指定):一次一个任务,严格按任务卡,不扩范围。 - **Reviewer**(强模型,用户指定):实现完成后起 Reviewer sub-agent,按任务卡 `Acceptance criteria` + `Reviewer checklist` 复核、**独立重跑校验闸门**,驱动 implementer 返工直到本轮 PASS。 +#### Reviewer 盲审纪律(M1 教训) + +M1 里 review **从未触发过一次 rework**,根因是 orchestrator 把自己的结论 / 辩护喂给了 reviewer,造成 context bleed、review 沦为橡皮图章。所以: + +- reviewer 必须**冷启动(Clear-Agent)、最小化喂料**——spawn prompt 只给:① 任务卡(`Acceptance criteria` + `Reviewer checklist`)、② 对应的 `review-notes/-impl|rework-.md` 路径、③ 要审的 diff / commit 范围。 +- **不要**在 prompt 里塞 orchestrator 自己的判断、"我觉得没问题"、对实现选择的辩护,或上一轮 reviewer 的倾向性结论。让它**独立得出结论、独立重跑校验闸门**。 +- 事后另起的整库**独立盲审**(如对抗复审)同理:Clear-Agent、最小上下文,把它当"**外部审计**"而非"确认自己没错"。 + ### 校验闸门(每个任务结束都要全绿) 根目录、激活 `.venv` 后: @@ -56,6 +64,14 @@ python scripts/export_openapi.py && git diff --exit-code openapi/ # 改了路 前端任务(M2)在 `frontend/` 下另跑 `npm run lint && npm run typecheck && npm run test && npm run build`(详见 m2 文档 §8)。 **不过闸门就不算完成**,不得跳过、不得留红给下一轮。 +### 构建上下文完整性(M1 Dockerfile 教训) + +`docker build` **不在 pytest/ruff 闸门里**——M1 删了 `alembic_location/poo` 后忘了同步 `Dockerfile` 的 `COPY`,单元闸门全绿却把坏掉的镜像构建一路漏到 release tag。所以: + +- 任务**删除 / 移动 / 重命名文件或目录**时,必须 grep 构建清单是否还在引用它们:`Dockerfile`(尤其 `COPY` 源)、`docker/`、`*.ini`、CI workflow、`requirements*.txt` 等。 +- 已有回归测试 `tests/test_deployment.py::test_dockerfile_copy_sources_exist` 守"Dockerfile `COPY` 源必须存在于构建上下文";新增 / 改动 `COPY` 时确保它仍覆盖得到。 +- Reviewer 审"删 / 移文件"类任务时,**必须顺带核对构建清单引用**,把它当 acceptance 的一部分。 + ## 每轮简报(`review-notes/`) 每轮工作都要在 `review-notes/` 下产出**中文简报**。该目录**已在 `.gitignore` 忽略**,纯本地、不入库——它是 agent 之间和与人之间的交接载体,不是仓库产物。 @@ -97,12 +113,13 @@ python scripts/export_openapi.py && git diff --exit-code openapi/ # 改了路 - 每次提交前**自检**:`git log -1 --format=%B` 的输出**不得包含** `Co-authored-by`(大小写不限)。若发现,立即 `git commit --amend` 去掉后再继续。 ### Review 后返工 -- 返工产生的提交**一律用 fixup**,指向本轮对应的 base commit,**不写新的独立 message**: +- **自动化 orchestration 模式内**的 review 返工:**一律用 fixup**,指向本轮对应的 base commit,**不写新的独立 message**: ```bash git add -A git commit --fixup= ``` -- 多轮返工就多个 `fixup!` 提交,都指向同一个 base commit。 +- 多轮返工就多个 `fixup!` 提交,都指向同一个 base commit;收尾时 auto-squash(见下)。 +- **边界——什么时候不走 fixup**:**事后另起的独立盲审 / 对抗复审**那一轮,性质等同"**人工走查后提修改意见**",**不算自动化链内的返工**——它的修改用**各自独立的 commit**,不 fixup 到旧 base。判据:这轮返工是否在**同一条自动化 implement→review 链**里?是 → `fixup`;是事后另起的独立审计 → 独立 commit。 ### 本轮 / feature 收尾(用户确认收尾后) - 用 **auto-squash** 把所有 `fixup!` 合并进各自目标,保证**一个 feature 一个干净 commit**: @@ -115,6 +132,15 @@ python scripts/export_openapi.py && git diff --exit-code openapi/ # 改了路 ### 一般约束 - commit / push 只在用户要求时进行;push、force-push、开/改 PR 等对外操作先确认。 +## 发版前置走查(打 tag 前必做) + +单元闸门绿 ≠ 真的能跑、能构建、能用。M1 出过"绿了但 docker 构建坏了"的事故,所以**打版本 tag(触发镜像 CI)之前**,除了 `pytest` / `ruff` 全绿,还要: + +- **真起 app**:迁移(`python -m scripts.run_migrations`)→ `uvicorn app.main:app ...`,确认能正常启动、关键路由不 500。 +- **真跑镜像构建**:本地 `docker build`(多阶段就跑完整条),确认构建通过、`COPY` 源都在。 +- **关键功能人工瞄一眼**:尤其前端 / 可视化类(M2 的热力图、首页地图)——自动闸门判断不了"渲染对不对、UX 顺不顺",这部分**靠看跑起来的 app,不靠读代码**。 +- 上述任一不过 → **不打 tag**。tag 一旦 push 会触发 docker 镜像 CI / 对外发布,属对外操作,**先确认**。 + ## 数据安全红线(不可违反) - 任何脚本 / migration **都不得删除或覆盖用户数据文件**(旧 `.db`、备份、volume)。删除只能是人工、事后、保留归档的独立步骤(见 `docs/design/m1-db-consolidation.md` §6 runbook)。 diff --git a/docs/future-ideas.md b/docs/future-ideas.md new file mode 100644 index 0000000..b881ccb --- /dev/null +++ b/docs/future-ideas.md @@ -0,0 +1,20 @@ +# Future Ideas / Backlog(暂无 Milestone) + +记录尚未排期的想法。等某条成形、值得集中推进时,再升级为 `docs/roadmap.md` 里的 milestone 并展开成 `docs/design/` 任务卡。**这里只是备忘,不是承诺。** + +> 项目定位:**个人自用、针对自家场景特化,不开源**。因此设计可按单用户 / 自家需求简化,不必为通用性、多租户、对外发布做过度抽象。 + +## 数据与存储 +- 增加更多数据类型 / 来源(持续扩展)。 +- 针对**需要长期保存**的数据,考虑更合适的存储方案(当前全 SQLite;长期 / 大量数据可能需要更强的数据库)。 +- 把 **Home Assistant 接收到的数据**纳入本系统做持久化 / 展示。 + +## 集成 +- **MQTT**:让后端作为一个 MQTT client,双向收发数据。 + +## 前端 / 移动端 +- **PWA**(**近期、可能并入 M2 或单独小里程碑**):在 React Native(M3)之前,用 PWA 把 web SPA 包装成"准手机 App"——可安装到桌面、响应式、离线壳。 + - 影响当下设计:**M2 的 UI 从一开始就按移动端布局考虑**(响应式 + 合理的参数显示),为之后加 PWA 铺路。 + +## 备注 +- 以上为临时记录(讨论 M2 范围时随手想到),后续可增删、重排优先级。