CLAUDE.md · diff

git:20260909.b0a274d to git:20261004.a5c71fa

1 added, 100 removed. Audit A to B.

- ## 发布规范（硬约束）

- 完整发版流程见 `.claude/skills/release/SKILL.md`（发版时必读），机制设计见

- `docs/design/in-app-update.md`。任何时候都不可违反的三条：

- 1. **版本号三处一致**：`pyproject.toml` 的 version、`src/movieclaw_api/__init__.py`

- 的 `__version__`、Release tag（去 `v`）必须完全一致，构建脚本会强制校验。

- 2. **动了运行时依赖必须 bump `docker/runtime-version`**：pyproject dependencies、

- Node 大版本、Dockerfile 系统包/基础镜像、entrypoint 契约，任何一项变更都要 +1

- 并在合并后发布新镜像（CI 守卫会拦截漏 bump 的 PR）。改 `cli/` 不在此列——

- mclaw 随 app-backend 产物一起发布、由 entrypoint 改软链指向

- （见 `docs/design/in-app-update.md`「CLI 也走 overlay」）。

- 3. **数据库迁移只能向前兼容**：应用内更新支持一键回退，迁移是单向的，

- 用户回退跨版本时靠更新前的自动备份恢复数据。

- 4. **`data/` 下新增目录必须登记**：任何落在运行期数据目录下的新目录都要在

- `src/movieclaw_api/services/storage/registry.py` 登记（用途、能否清理、后果），

- 路径在 `core/config.py` 声明成 Settings 字段而不是手写 `data/...` 字面量；

- CI 守卫（`tests/api/test_storage.py`）会拦截漏登记的 PR，设计见

- `docs/design/cache-management.md`。

- ## 注释和日志

- 1. 每一个关键类的设计和实现，补充完善的中文注释，好的注释可以帮助项目其他成员看懂关键设计思路，有利于后续的扩展和迭代。

- 2. 日志可以使用中文输出明确的错误信息，这是一款开源软件，非开发者可能也会部署，遇到任何错误，他们需要能够看懂。

- ## 项目约定

- - 业务接口成功响应统一 `success/code/message/data`，错误响应统一

- `success/code/message/details`

- - 运行期数据（SQLite、日志、图片缓存与资产、上传文件、模型）全部落在

- `data/` 目录，部署时挂载该目录即可持久化

- - 新站点接入用声明式 YAML，模板见

- `src/movieclaw_tracker/sites/configs/_template.yaml`

- - 测试门禁由 CI 与发版流程承担（每个 PR 自动跑 `pytest -m "not integration"`，

- 发版以发版 PR 的 CI 全绿为准，见 `.claude/skills/release/SKILL.md`），

- 本地不要求跑全量测试

- ### 1. 编码前思考

- **不要假设。不要隐藏困惑。呈现权衡。**

- LLM 经常默默选择一种解释然后执行。这个原则强制明确推理：

- - **明确说明假设** — 如果不确定，询问而不是猜测

- - **呈现多种解释** — 当存在歧义时，不要默默选择

- - **适时提出异议** — 如果存在更简单的方法，说出来

- - **困惑时停下来** — 指出不清楚的地方并要求澄清

- ### 2. 简洁优先

- **用最少的代码解决问题。不要过度推测。**

- 对抗过度工程的倾向：

- - 不要添加要求之外的功能

- - 不要为一次性代码创建抽象

- - 不要添加未要求的"灵活性"或"可配置性"

- - 不要为不可能发生的场景做错误处理

- - 如果 200 行代码可以写成 50 行，重写它

- **检验标准：** 资深工程师会觉得这过于复杂吗？如果是，简化。

- ### 3. 精准修改

- **只碰必须碰的。只清理自己造成的混乱。**

- 编辑现有代码时：

- - 不要"改进"相邻的代码、注释或格式

- - 不要重构没坏的东西

- - 匹配现有风格，即使你更倾向于不同的写法

- - 如果注意到无关的死代码，提一下 —— 不要删除它

- 当你的改动产生孤儿代码时：

- - 删除因你的改动而变得无用的导入/变量/函数

- - 不要删除预先存在的死代码，除非被要求

- **检验标准：** 每一行修改都应该能直接追溯到用户的请求。

- ### 4. 目标驱动执行

- **定义成功标准。循环验证直到达成。**

- 将指令式任务转化为可验证的目标：

- | 不要这样做... | 转化为... |

- |--------------|-----------------|

- | "添加验证" | "为无效输入编写测试，然后让它们通过" |

- | "修复 bug" | "编写重现 bug 的测试，然后让它通过" |

- | "重构 X" | "确保重构前后测试都能通过" |

- 对于多步骤任务，说明一个简短的计划：

- ```

- 1. [步骤] → 验证: [检查]

- 2. [步骤] → 验证: [检查]

- 3. [步骤] → 验证: [检查]

- ```

- 强有力的成功标准让 LLM 能够独立循环执行。弱标准（"让它工作"）需要不断澄清。

+ @AGENTS.md