3.5 KiB
3.5 KiB
编码规则（Coding Rules）
每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
0. 黄金法则
- 不臆造：数据字段、文件、接口、依赖，不确定就查证或询问。
- 守范围：只做当前任务要求的事，不顺手加后续功能。
- 照架构：使用 Wagtail / Django / Python 3.12 / SQLite 的既定方案，不擅自换栈。
- 小步改：一次只解决一个任务，不夹带无关重构。
- 可验证：改完必须能构建、能测试、对得上验收标准。
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.ps1 / init.sh：
# 目标形态
.\.venv\Scripts\python manage.py check
.\.venv\Scripts\python manage.py test
完成前至少检查：
- Django system check 通过。
- 相关测试通过。
- 对得上需求验收标准。
- 没有夹带无关改动。
- 涉及文档事实变化时，文档已同步。
- 已在
../progress.md记录跑过的命令和结果作为证据。 - 回复里如实说明跑了什么命令、结果如何。
8. 绝不
- 绝不把密钥、token、密码写进代码或文档样例的真实值里。
- 绝不为了让测试通过而删除断言、降低验收标准。
- 绝不擅自删除用户已有文件或重置工作区。
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
- 绝不把赞助项目伪装成编辑推荐。