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. 测试与验证

生产代码尚未初始化。完成 T-001 后，把真实命令填入这里，并同步 init.sh（init.ps1 可选）：

# 目标形态
.venv/bin/python manage.py check
.venv/bin/python manage.py test

完成前至少检查：

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

8. 绝不

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