docs: 增加每次编码的硬门禁(Definition of Done)与提交纪律
明确 TDD/≥80%覆盖/三类自动化测试必跑/全门禁绿/合规/每次commit/禁署名尾注; 如实标注覆盖率工具尚未接入并列出补齐待办。
This commit is contained in:
31
CLAUDE.md
31
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`.
|
- **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).
|
- **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>: <description>`(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 已落地)
|
## Toolchain (Phase 0 已落地)
|
||||||
|
|
||||||
工具:**uv**(Python workspace,4 members: `apps/api` + `packages/{shared,config,db}`) + **pnpm**(前端,`apps/web`)。Python 3.12+,Node 22。
|
工具:**uv**(Python workspace,4 members: `apps/api` + `packages/{shared,config,db}`) + **pnpm**(前端,`apps/web`)。Python 3.12+,Node 22。
|
||||||
|
|||||||
Reference in New Issue
Block a user