zhuiguang-ai/.trae/rules

追光AI — 规则体系索引

版本: v1.0 | 更新: 2026-10-01 | 所有 .trae 内容均在代码仓库 zhuiguang-ai/.trae/ 内，跟着 git 走

一、这套规则解决什么问题

AI 代理每次会话都是无状态的（不记得上次讨论）。规则与知识库的唯一作用，就是把跨会话的持久上下文注入进来。 没有它们，AI 每次都会重新问、重新猜、重复踩坑 —— 迭代效率无法复利。

二、四层结构（单一事实源，互不复制）

层	载体	内容	何时加载
L0 方法论	.trae/ai_coding_knowledge.json	AI 编程效率的方法/工具/工作流/原则/反模式（机器可解析，不写业务）	每次任务开始前
L1 协作规则	.trae/rules/ai_agent_rules.md .trae/rules/ai_collaboration.md	启动加载顺序、小任务豁免、Plan-first 流程、验收标准、完成自动记录	每次任务开始前 / 收尾时
L2 工程标准	.trae/rules/project_rules.md	技术栈、数据获取、导航图片、无障碍、安全、定时任务、部署等硬规范	写代码时按需
L3 项目事实	.trae/knowledge_graph.jsonl（MCP 源） .trae/knowledge_graph.json（渲染版） .trae/knowledge/*（能力/过程/成果自动记录）	模块、部署、定时任务、仓库、约定、巡检问题等事实	需要项目具体知识时

⚠️ 禁止跨层复制：同一事实只允许有一个权威载体，其余位置只写引用。复制必然漂移（见反模式 divergent-copies）。

三、快速导航

我要…	读哪个
开始一个开发任务	ai_agent_rules.md §0
知道怎么和 AI 协作、怎么算做完	ai_collaboration.md
查 AI 编程方法论 / 选工具	.trae/ai_coding_knowledge.json
查项目某个模块/部署/定时任务的事实	.trae/knowledge_graph.jsonl
查编码硬规范（安全/API/图片/无障碍）	project_rules.md
部署、运维、容器	project_rules.md §14–15（工程侧见 specs/modules/09-devops.md）

四、自动化闭环

开发完成
   │
   ├─ npm run knowledge:update          ← 手动/收尾执行
   └─ git post-commit hook              ← 本机自动触发
          │
          ▼
   scripts/update-knowledge.mjs
          │
          ├─ .trae/knowledge/capabilities.json   能力特征（API/页面/组件/模型/脚本/任务/依赖）
          ├─ .trae/knowledge/dev_process.jsonl   开发过程（按提交追加）
          ├─ .trae/knowledge/artifacts.jsonl     模型成果（迁移/脚本/提交统计）
          └─ .trae/knowledge_graph.json / .jsonl 事实层增量 upsert

五、维护规则

1. 方法/工具层变化 → 改 .trae/ai_coding_knowledge.json，同步 ai_collaboration.md
2. 协作流程变化 → 改 ai_collaboration.md，同步更新 ai_coding_knowledge.json 中对应 workflow:*
3. 项目事实变化 → 跑 npm run knowledge:update，或直接维护 .trae/knowledge_graph.jsonl
4. 工程标准变化 → 改 project_rules.md
5. 废弃而非删除：用 > **已废弃 (date)** 标注并写明替代方案，保留至少一个大版本周期

六、版本历史

日期	版本	变更
2026-10-01	v1.0	初始版本：建立四层结构；新增 AI 编程知识库、AI 代理规则、AI 协作流程、自动记录脚本