zcbot/CLAUDE.md

zcbot 开发笔记 (给 Claude Code)

环境

• Python 虚拟环境: .venv/(项目根目录下),所有依赖装在里面
• 跑脚本 / 测试一律用 .venv/Scripts/python.exe ...,不要用全局 python(没装 litellm/python-pptx 等会报 ModuleNotFoundError)
• requirements 见 requirements.txt

开发阶段心智

当前处于开发阶段(尚未发布给真实用户)。改需求 / 重构时,以最优实现为准,不为旧数据 / 旧字段 / 旧 API 留兼容层:

• DB schema 变 → 直接改 model + 写一条干净的 migration(必要时清空旧 row,不写双向兼容代码)
• 字段语义变 → 全量替换,不留 legacy_xxx / *_v2 并存
• CLI / REPL 选项变 → 直接改,不留 deprecated 别名
• 只有当用户明确说"这条要保留兼容"时才写兼容代码

理由:兼容层就是技术债,开发期写了之后忘记删反而拖累;真上线后再视情况补迁移路径。

文档维护

每完成一步实现(commit 前),必须更新 PROGRESS.md:

• "已完成关键能力" 段加一条 YYYY-MM-DD / <短标题>:<改了什么>
• 状态表(§7 B Step 几 / Phase 几)若变化跟着改
• 文件清单若新增 / 删除模块跟着改

只有以下情况才动 DESIGN.md(避免把工程笔记沉淀成设计):

• 架构 / 心智模型变化(如 §7.1 task-primary 重写)
• 取舍决策推翻或新增(§5 / §7.9 类内容)
• API / schema 字段语义变化(§7.2 / §7.4)
• 实施中发现 DESIGN 描述与代码偏离 → 同步改回

bug 修复、重构、新加 skill、调参 —— 不动 DESIGN,只更 PROGRESS。

改任何对外行为(CLI 选项 / REPL 命令 / env 变量 / 文件布局 / migration 步骤)→ 同步更新 RUN.md:

• 新加 / 改 / 删 CLI 子命令 + 选项时,改"日常命令"段
• env 变量 / 启动初始化变化时,改"环境" / "一次性初始化"段
• 真实踩过的坑(用户报或自己跑出来),加一行到"故障兜底"表
• 纯内部重构 / 不影响用户怎么跑的 —— 不动 RUN

三文档边界:DESIGN=为什么(架构 / 取舍),PROGRESS=做到哪(状态 / 历史),RUN=怎么跑(命令 / env / 兜底)。一次改动可能动多个,但每个动的理由要符合上述边界。