XIUNOX AI 辅助开发规则集
这是一套在 XIUNOX 项目实践中沉淀下来的 AI 辅助开发规则，用于约束 TRAE IDE、Codex、Claude Code、Cursor 等 AI 编码工具在 XIUNOX 项目中的行为。规则源自真实事故复盘——每一条 ⚠️ 已违反 N 次 背后都是一次线上故障或开发踩坑。
为什么需要这套规则
XIUNOX 基于 XIUNO BBS 4 重构，引入了 htmx 4、Bootstrap 5、_include() 编译缓存、hook 内联机制等技术特性。这些机制在带来性能和灵活性优势的同时，也埋下了一批隐蔽的陷阱：hook 里的 return 会从宿主函数返回、_include() 不比较源文件 mtime 导致修改不生效、CacheHelper::remember() 的哨兵格式与 set() 裸值不兼容等等。AI 工具如果不了解这些底层机制，会反复踩同样的坑。
这套规则把项目特有的技术约束、历史事故教训、以及一套"懒惰高级开发者"的工程哲学固化下来，让 AI 在动手前先过一遍检查清单，减少返工。
三个文件各自做什么
project_rules.md — 项目统一开发规范
定义 XIUNOX 的技术栈、前端强制规范、安全规范、数据与 SQL 规范、缓存规范、URL 与伪静态规则等。这是 AI 在本项目工作前必须了解的"宪法"级文档。
核心内容涵盖：
htmx 4 事件名格式（冒号分隔，禁止 2.x 旧名）
_include()编译缓存机制（修改源文件后必须删 tmp 缓存）hook 开发规范（禁止
return，终止性exit须注释）display_name是虚拟字段（SQL 中 SELECT 会报 1054）CacheHelper::remember()哨兵格式（set()写裸值会被判 MISS）URL 函数禁止双重包裹
密码等敏感字段
param()须传第 3 参FALSE
每个条目标注了 ⚠️ 已违反 N 次，次数越高优先级越高。
bugfix_rules.md — 修复流程与反思机制
定义 Bug 修复的标准流程、更新日志写入规范、各类检查清单（缓存/插件卸载/JS 迁移）、以及一份按违反次数降序排列的高频违规清单。
这份文件的关键价值在于：
更新日志写入规范：防并发覆盖，统一格式，强制写在项目根目录
检查清单：缓存修改 11 项、插件卸载 6 项、JS 迁移 10 项，逐项核对
高频违规清单：17 条已发生事故的规则，按 4 次/2 次/1 次分级，修改前必读
ponytail.md — 懒惰高级开发者哲学
这是一份工程哲学文件，约束 AI 在"写不写代码"和"写多少代码"上的决策。核心思想是：最好的代码是从未写过的代码。
7 级决策阶梯（按顺序判断，在第一个能停的地方停下）：
这东西真的需要构建吗（YAGNI）
代码库里已经有了吗（复用）
标准库能做吗
平台原生功能能覆盖吗
已安装的依赖能解决吗
能不能一行搞定
最后才写最小可用代码
但这个阶梯在理解问题之后才爬——先读完任务和相关代码、追踪完整调用链，再决定用什么方案。不理解问题就追求最小 diff，不是懒，是制造第二个 bug。
对某些事情不偷懒：输入验证、错误处理、安全、可访问性、硬件校准、任何明确要求的功能。非平凡逻辑要留一个可运行的检查（assert 或小测试文件，不用框架）。
如何安装
TRAE IDE 用户
将三个 .md 文件放到项目的 .trae/rules/ 目录下：
你的项目根目录/
├── .trae/
│ └── rules/
│ ├── project_rules.md
│ ├── bugfix_rules.md
│ └── ponytail.md
├── xiunobbs-master/
│ └── ...（XIUNOX 代码）
TRAE 会自动加载 .trae/rules/ 下的所有 .md 文件作为项目规则，在每次对话中注入到 AI 的上下文里。
Codex / Claude Code / Cursor 用户
这三个文件本质上是 Markdown 格式的指令文档，可以通过各自工具的"自定义指令"或"上下文文件"机制加载：
Claude Code：放在项目根目录，Claude Code 会自动读取
.md文件作为上下文；或在.claude/配置中引用Cursor：在
.cursorrules文件中@import这三个文件，或直接将内容粘贴到 Settings → General → Rules for AICodex：作为系统提示或项目上下文文件加载
由于 project_rules.md 文件头已声明"适用于所有 AI 工具"，内容不依赖 TRAE 特定功能，可直接通用。
实际工作流程
修复一个 Bug
假设用户报告"后台编辑用户积分后积分没有变化"。
AI 收到任务后，按 bugfix_rules.md 的流程执行：
前置评估：检索
project_rules.md和bugfix_rules.md，用 TodoWrite 列出待澄清问题定位根因：Grep 相关代码，追踪完整调用链（不是只看报错的那个文件）
核对高频违规清单：发现"表单提交前禁止
jform.reset()"——检查目标模板是否踩了这个坑修复：最小可用 diff，修复根因而非症状
清理缓存：如果改了
_include()加载的文件，删tmp/下对应编译缓存写更新日志：用
printf >>追加到根目录的update_YYYYMMDD.md反思沉淀：如果是新类型的问题，更新规则文件；如果是已违反过的，递增
⚠️ 已违反 N 次
开发一个新功能
假设用户要"给帖子详情页加一个相关帖子推荐模块"。
AI 按 ponytail.md 的阶梯决策：
真的需要构建吗：确认需求，避免过度设计
代码库里有了吗：Grep 是否已有相关帖子插件或 hook 点
复用现有模式：参考已有插件的 hook 注册、缓存使用、Service 类结构
最小代码：不引入新依赖，不创建不必要的抽象层，复用
CacheHelper::remember()而非手写缓存样板遵循 project_rules.md：hook 禁止
return、语言键双写hook/lang_*_bbs.php、缓存键用CacheHelper::pluginKey()、JS 放plugin/<dir>/static/js/
