From e9477d84d8f8db090c70d12ea2e24e3eb15d8b7d Mon Sep 17 00:00:00 2001 From: Yaojia Wang Date: Fri, 26 Jun 2026 21:03:35 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E6=AF=8F=E6=AC=A1?= =?UTF-8?q?=E7=BC=96=E7=A0=81=E7=9A=84=E7=A1=AC=E9=97=A8=E7=A6=81(Definiti?= =?UTF-8?q?on=20of=20Done)=E4=B8=8E=E6=8F=90=E4=BA=A4=E7=BA=AA=E5=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 明确 TDD/≥80%覆盖/三类自动化测试必跑/全门禁绿/合规/每次commit/禁署名尾注； 如实标注覆盖率工具尚未接入并列出补齐待办。 --- CLAUDE.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 7222c4c..98ab672 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -89,6 +89,37 @@ Aligns `ARCHITECTURE.md §9.3`. This is how every failure gets diagnosed. - **Errors** logged with full context at the boundary, mapped to the error envelope (`ARCHITECTURE §7.1` is the source of truth for envelope shape + error codes). Frontend logs client errors with the same `request_id`. - **Redact**: never log API keys; truncate/hash full prompts and manuscript text (log lengths/hashes, not the novel). +### Definition of Done (每次编码完成的硬门禁) — 不通过不算完成 + +每一次代码改动（无论多小）在声明「完成」前，**必须**按顺序全部通过以下门禁。任一项失败就回去修，不得跳过、不得只跑部分、不得仅靠肉眼判断。 + +1. **TDD 已遵守** — 先写失败测试（RED）→ 实现到通过（GREEN）→ 重构（REFACTOR）。新增/修改的逻辑都有对应测试；改 bug 先写能复现的失败测试。见上文 §TDD。 +2. **测试覆盖率 ≥ 80%** — 改动涉及的模块覆盖率不得低于 80%（全局规则）；新代码不许拉低整体覆盖率。 + - ⚠️ **当前覆盖率工具尚未接入**（后端无 `pytest-cov`，前端 vitest 未装 coverage provider），所以数字暂时量不出来。在工具补齐前，至少保证每段新增/改动逻辑都有对应测试覆盖，用 review 把关。 + - **待办（@devops/@qa）**：后端加 `pytest-cov` + `[tool.coverage]` 配置（`uv run pytest --cov=packages --cov=apps --cov-report=term-missing --cov-fail-under=80`）；前端装 `@vitest/coverage-v8` 并在 `vitest.config.ts` 设 `coverage.thresholds.lines=80`（脚本 `pnpm test -- --coverage`）；接好后把 80% 门禁加进 CI，并把本条改成「跑覆盖率命令、核对数字」。 +3. **跑完三类自动化测试**（改动触及的那侧必跑，跨栈改动两侧都跑）： + - **后端 Unit + Integration**：`uv run pytest -q`（需要 pg 的集成测试先 `docker compose up -d pg`）。 + - **前端自动化测试**：`cd apps/web && pnpm test`（vitest）。 + - **E2E**（动到 write→review→accept 主链路时）：跑相关 E2E 流程（mock gateway）。 + - LLM 一律 mock，**绝不在测试/CI 命中真实 LLAPI**（见上文 §TDD）。 +4. **全部门禁绿**（与 §Toolchain、CI 一致）： + - 后端：`uv run ruff check .` · `uv run ruff format .` · `uv run mypy packages apps` · `uv run pytest -q` · 动过模型时 `uv run alembic check` 无漂移。 + - 前端：`cd apps/web && pnpm lint` · `pnpm typecheck` · `pnpm test` · `pnpm build`；动过后端 schema 先 `pnpm gen:api` 再校验。 +5. **符合架构与编程规范** — 不违反上文 §Architectural invariants、§Locked tech stack、§Python/§Frontend/§LangGraph 实践，以及全局编码风格（不可变更新、KISS/DRY/YAGNI、文件 <800 行、函数 <50 行、显式错误处理、边界校验、无硬编码密钥）。安全敏感改动（auth/输入处理/DB 查询/外部 API/加密）按 §code-review 触发安全自查。 +6. **提交（每次完成都 commit）** — 见下文 §Commit discipline。 +7. **回写状态/文档** — 按 §Per-task workflow 更新 `PROGRESS.md`；若实现暴露 spec 缺口，回写对应 spec（见 §Conventions）。 + +> 报告要诚实：测试失败就如实说明并贴输出；跳过了哪一步要讲明；只有真正跑过且全绿，才说「完成」。 + +### Commit discipline (提交纪律) — 每次完成即提交 + +- **每次完成一个可工作的改动就 commit**，小步提交、一次一个聚焦改动；不要把多个无关改动堆进一个提交。 +- **提交前** Definition of Done 的门禁（1–5）必须已全绿——不提交跑不过测试或 lint/类型不干净的代码。 +- **提交信息格式**：遵循 Conventional Commits —— `: `（type ∈ feat/fix/refactor/docs/test/chore/perf/ci），中文描述与本仓库现有提交风格一致；需要时附 body 说明「为什么」。 +- **提交信息禁止任何署名/归属尾注** — **不得包含 `Co-Authored-By:` 或任何 `Generated with` / AI 署名行**（全局已在 `~/.claude/settings.json` 关闭 attribution；此处再次明确，覆盖任何默认加尾注的行为）。 +- **分支**：不在 `main` 上直接提交；按 §Git Workflow 在特性分支工作。`develop` 为当前集成分支。 +- **push / 开 PR 仅在用户明确要求时**进行；PR body 同样不加 AI 署名。 + ## Toolchain (Phase 0 已落地) 工具：**uv**(Python workspace，4 members: `apps/api` + `packages/{shared,config,db}`) + **pnpm**(前端，`apps/web`)。Python 3.12+，Node 22。