skelet/docs/05-coding-rules.md

# 编码规则（Coding Rules）

> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。

## 0. 黄金法则

1. **不臆造**：数据字段、文件、接口、依赖，不确定就查证或询问。
2. **守范围**：只做当前任务要求的事，不顺手加后续功能。
3. **照架构**：使用 Wagtail / Django / Python 3.12 / SQLite 的既定方案，不擅自换栈。
4. **小步改**：一次只解决一个任务，不夹带无关重构。
5. **可验证**：改完必须能构建、能测试、对得上验收标准。

## 1. 动手前

- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
- 先找现有 Wagtail/Django 结构、模型、模板和测试，复用优先。
- 如果需求含糊，或改动会偏离原则 / 架构，先问。

## 2. 事实来源纪律

- 只相信文档指定的权威需求、模型、路由、API 边界和当前代码。
- 不从聊天记录、备份、草稿、旧导出文件里推断当前事实。
- 不虚构字段、接口、状态码、配置项。
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md`、`routes.md` 和相关任务。

## 3. 范围纪律

- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
- V2 / V3 功能只记录，不实现。
- 需求明确排除的非目标不得实现。
- 不为“将来可能用到”提前抽象。

## 4. 架构纪律

- 技术栈以 `03-tech-stack.md` 为准。
- 新增依赖前先说明理由；未经确认不要引入重量级依赖。
- Page / Snippet / Template / Settings 的职责以 `04-architecture.md` 为准。
- 公开路由以 `routes.md` 为准。
- MVP 不提供公开 REST API；不要擅自新增 API 层。

## 5. Wagtail / Django 规则

- 模型字段必须有清晰业务含义，不能只为页面展示临时堆字段。
- 迁移文件必须随模型变化提交。
- Wagtail 后台字段分组要服务编辑体验。
- 前台模板不要写复杂业务查询；复杂查询放到模型方法、QuerySet 或 view/helper。
- URL slug 要稳定，避免上线后频繁修改。
- 上传媒体走 Wagtail / Django media 机制，不硬编码本地绝对路径。

## 6. SQLite 规则

- 不写 SQLite 专属 SQL，保持未来迁移 PostgreSQL 的可能性。
- 不做高频写入功能。
- 上线前启用 WAL 并记录备份策略。
- 如果出现 `database is locked`，先记录到 `current-state.md`，再规划 PostgreSQL 迁移任务。

## 7. 测试与验证

```bash
.venv/bin/python3.12.exe manage.py check
.venv/bin/python3.12.exe manage.py test
```

完成前至少检查：

- [ ] Django system check 通过。
- [ ] 相关测试通过。
- [ ] 对得上需求验收标准。
- [ ] 没有夹带无关改动。
- [ ] 涉及文档事实变化时，文档已同步。
- [ ] 已在 `../progress.md` 记录跑过的命令和结果作为证据。
- [ ] 回复里如实说明跑了什么命令、结果如何。

## 8. 绝不

- 绝不把密钥、token、密码写进代码或文档样例的真实值里。
- 绝不为了让测试通过而删除断言、降低验收标准。
- 绝不擅自删除用户已有文件或重置工作区。
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
- 绝不把赞助项目伪装成编辑推荐。