From ac780c4e25bdaf6e3e9b10b46697ff95870af077 Mon Sep 17 00:00:00 2001 From: dingdugan <266583785+dingdugan@users.noreply.github.com> Date: Mon, 13 Jul 2026 14:27:03 -0700 Subject: [PATCH] docs: add CLAUDE.md (docs conventions + enforcement rules) + docs/ scaffold MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补齐标准项目结构：CLAUDE.md（文档前缀约定 + frontmatter + 三件套硬 规则 + docs index + 项目铁律：registry 精确匹配 / 防脏值闸 / 发现策 略）+ docs/_archive/ 骨架。架构权威源仍是 README，CLAUDE.md 不重复。 Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 77 ++++++++++++++++++++++++++++++++++++++++++ docs/_archive/.gitkeep | 0 2 files changed, 77 insertions(+) create mode 100644 CLAUDE.md create mode 100644 docs/_archive/.gitkeep diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..bc27ada --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,77 @@ +# model.tracker + +> 本项目继承 `~/.claude/CLAUDE.md`（Execution Discipline + Plan→Code→Ship 工作流）。下面只补充本项目特有的规则。 + +自动监控全球 14 家 AI 厂商的模型发布、定价、性能表现，每日更新。架构图和健壮性设计详见 [README.md](README.md)（README 是架构权威源，本文件不重复）。 + +## 文档约定（活文档） + +所有项目文档放 `docs/`，**扁平 + 前缀**，不开子目录： + +| 前缀 | 用途 | 例 | +| --- | --- | --- | +| `spec-.md` | 功能规格 / PRD | `spec-price-alerts.md` | +| `decision-.md` | 决策快照（选 X 不选 Y 的 why） | `decision-registry-matching.md` | +| `research-.md` | 调研、外部参考 | `research-benchmark-sources.md` | +| `design-.md` | UI/交互稿、视觉规范 | `design-health-page.md` | +| `_archive/` | 过期/被取代的文档（不删，仍可回查） | | + +每份文档**头部必须有 frontmatter**： +```yaml +--- +status: active | draft | superseded | done +updated: YYYY-MM-DD +--- +``` + +`status` 含义： +- `active` —— 当前权威源，写代码必须信它 +- `draft` —— 还在草稿，**不构成承诺**，AI 看到 draft 不要当作 spec 执行 +- `superseded` —— 已被 `<指向新文档>` 取代，挪去 `_archive/` +- `done` —— 描述的功能已落地（用作历史记录而非待办） + +注：`README.md` / `CONTRIBUTING.md` / `SECURITY.md` 是 GitHub 标准根文件，留在根目录，不进 docs/。 + +## 强制规则（防止"聊半天没实现"） + +### ① Checklist 条目自带验收证据 + +`IMPLEMENTATION_CHECKLIST.md` 每条按下面格式写，**没"证据"行不准打 `[x]`**： + +```markdown +- [ ] <动词 + 屏幕/文件 + 行为> + 验收: <可观察的标准，如截图/跳转/数值> + 证据: <填截图路径 / file:line / 测试名> +``` + +打 `[x]` 时必须把"证据"行的占位符替换为可核对的内容。**Stop hook 会自动审计**：缺证据或证据是占位符（`<...>`），harness 拦下来不让本轮结束。 + +### ② Plan→Code 切换点必须"封板" + +用户说「开工 / 写吧 / 干」等切换信号 → AI 在调 Edit/Write 之前必须： +1. 把本次共识落成 checklist 的具体条目 +2. **逐字引用**本次要做的 N 条（quote，不总结），并显式说"不做 M, K，原因 X" +3. 等用户回 OK 才动手 + +### ③ Code 结束输出对齐表 + +报告完成时**禁止**只用"已实现 / 搞定 / done"。必须输出： + +| checklist 条目 | 改了什么 (file:line) | 证据 | +| --- | --- | --- | + +任何条目缺"改了什么"或"证据"列 = 未完成，明说"未做"或"做不了，原因 X"。 + +## docs index（每次新增文档同步更新） + + + +- _(尚无文档 —— 架构说明在 [README.md](README.md)，待办在 [IMPLEMENTATION_CHECKLIST.md](IMPLEMENTATION_CHECKLIST.md))_ + +## 项目特定上下文 + +- **Stack**: Python scrapers（pydantic schema + Supabase 写入）+ Next.js ISR web（Vercel）+ Supabase Postgres（RLS 全开）+ GitHub Actions 每日 02:00 UTC cron +- **目录**: `scrapers/`（采集 + 发现 + 校验闸）· `apps/web/`（前端，含 `/health` 数据健康页）· `supabase/migrations/`（schema 权威源）· `scripts/` +- **身份匹配铁律**: 模型身份只在 `scrapers/core/model_registry.py` 一处定义（catalog ∪ 自动发现），归一化**精确**匹配 —— 受控剥离 `-thinking`/日期后缀，**绝不剥 size/version**，CI 强制无别名碰撞。改匹配逻辑前先读该文件头部注释 +- **防脏值闸**: 价格 >3× / ELO >100 跳变 → 隔离进 `pending_changes`，同值持续 2 次才确认应用。不要绕过 validation 直写库 +- **发现策略**: 厂商官方 Models API = 权威信号（自动入库）；arena/AA 榜单名 = 噪声（永不自动收，仅 `/health` 可查）。不要把榜单名当新模型 diff --git a/docs/_archive/.gitkeep b/docs/_archive/.gitkeep new file mode 100644 index 0000000..e69de29