Files

T

joywayerandClaude Opus 4.8 a931143c1e 强制遵守三套开发文档：README @import + PreToolUse 提醒 hook

把"必须严格遵守 docs 三套文档"从软指令变成硬机制，同时消除 SSOT 重复：

- CLAUDE.md 用 @import 把三份 README（含各自红线速查/一页纸总则）
  常驻每次会话上下文，删掉手写的红线摘要——红线以 README 权威源为准，
  不再在 CLAUDE.md 另抄一份
- 新增 .claude/hooks/remind-docs.js：PreToolUse 钩子，编辑 client/**、
  server/** 前按路径把"必须遵守的对应编号文档 + 红线"注入上下文（非阻塞）
- 新增 .claude/settings.json 注册该 hook（matcher Edit|Write|MultiEdit）；
  已 pipe-test 各路径分支 + sentinel 验证 hook 实际触发

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-06 07:57:25 +08:00

6.6 KiB

Raw Blame History

CLAUDE.md

本文件为 Claude Code（claude.ai/code）在本仓库中工作时提供指导。它是入口与强制指引：三套文档的 README（含各自「红线速查 / 一页纸总则」）已通过 @import 常驻上下文（见下「文档」一节），红线以它们为权威、始终在上下文里，本文件不再另抄一份；规范的完整细节在 docs/ 编号文档里，改动前先读对应文档。

这是一个什么仓库

一个友乐/gameabc 房卡类小游戏平台：浏览器端由私有的 gameabc.min.js 2D Canvas 引擎驱动，服务端是一个 Node.js 游戏服务器平台（youle 应用），双方通过 WebSocket/HTTP 收发 JSON 包通信。项目根目录没有 package.json、没有 npm 构建/lint/测试流水线——这是纯静态 JS：客户端靠 <script> 标签加载，服务端靠平台自带的 min_loadJsFile/require 加载。

client/js/01_SubGame/codes/ 和 server/games 目前都是空的——尚未接入任何具体子游戏。本仓库是平台层 + 可复用框架的脚手架，未来第一个子游戏会在此基础上搭建。

常用命令

没有配置任何构建/lint/测试工具。仓库里唯一的脚本：

# 根据 client/assets/spine/*.json 重新生成 client/generated/spine_assets.js 与 spine_data.js
client/scripts/build_spine_data.cmd        # 内部调用 build_spine_data.ps1

在 client/assets/spine/ 增删 Spine 导出文件后运行；不要手改这两个生成文件。

查看客户端效果需用 HTTP 方式（而非 file://）打开 client/index.html，例如 npx http-server client -p 8080。

shared/（共享算法，待子游戏接入后才有）的改动应按两套文档「§10 测试纪律」的要求跑 Node 单测验证——目前尚未接入测试框架，意味着需要直接用 node 运行相应脚本。

架构速览

完整的分层、模块清单与数据流以各 README 及编号文档为权威（client 01 / server 01）；此处只留改动前必须在上下文里的骨架。

两套代码库、一份协议：client/（浏览器，严格 ES5，gameabc 引擎）与 server/（Node.js，严格 ES5，youle 平台）通过 { app: "youle", route, rpc, data } JSON 包通信——route→模块、rpc→方法（mod[pack.rpc](pack)，一操作一 RPC，无二次 switch(action)）。服务端只靠主动推送（o_room.method.sendpack_toseat/toother）告知结果，DoPack 返回值不是下发通道。
客户端依赖严格单向：01_SubGame/codes → gameabc-framework → gameabc.min.js；index.html 的加载顺序就是依赖图，新增文件须插在依赖之后、使用者之前（无模块系统，否则拿到 undefined）。框架必须游戏中立，禁止渗入任何具体玩法逻辑/常量。
服务端三层路由 app→mod→method；每房间状态挂 o_room.o_desk.data.*（export.makewar 内创建，双向引用 o_room.o_desk ⇄ o_desk.o_room），按房间隔离。子游戏只在 server/<游戏容器目录>/<游戏>/ 内开发。
子游戏接入二选一、不混用：内联模式（逻辑写进三个契约文件）或 Hooks 外置模式（三契约文件退化为转发壳，逻辑放 codes/SubGameHooks.js + codes/，模板见 gameabc-framework/templates/subgame-entry/）。详见 client 06。

可编辑范围（完整规则见各 README「可编辑范围 / 红线速查」）：

路径	规则
`js/vendor/`、`js/00_Surface/`、`server/` 平台代码	禁止修改
`01_SubGame/00_SubGame_Config.js`	仅可改已有 `Game_Config.*` 配置项的值——禁止新增/删除/改名/改结构
`01_SubGame/01_SubGame_modify.js`	仅可填顶部「配置区」（`Type_1/Type_2/CreateRoomData/combat/game_config/roomDes`）；转发壳部分不碰
`01_SubGame/02_SubGame_Input.js`	完全不碰
`js/gameabc-framework/`	可改，但须保持游戏中立（不含具体玩法常量/逻辑）
`01_SubGame/codes/`（除 `shared/`）、`server/<游戏容器目录>/<游戏>/`	子游戏自由开发区
`01_SubGame/codes/shared/`	服务端 `shared/` 的只读同步副本；改服务端一侧后再同步

文档（改动前先读——这三套是权威源）

本仓库开发必须严格遵守以下三套文档；改哪块就先读对应 README 与编号文档，而不是从代码反推约定：

docs/client/development-guide/（01→06）、docs/server/development-guide/（01→04）——项目专属的平台接入规范与红线。
docs/games/engineering/（01→03）——位于两者之上、与平台无关的工程方法论（SSOT、单向依赖、职责单一、OCP、配置优先于硬编码、显式失败优于隐式兜底）。

三者互补不冲突：engineering 讲「该怎么设计、怎么长久演进」，dev-guide 讲「平台怎么接、红线是什么」；硬红线冲突时以 dev-guide 为准。

以下三份 README（含各自「红线速查 / 一页纸总则」）通过 @import 自动加载进每次会话的上下文——红线以它们为权威，无需在本文件另抄一份；改动具体区域时再深入读对应编号文档：

@docs/client/development-guide/README.md @docs/server/development-guide/README.md @docs/games/engineering/README.md

各编号对应主题（改哪块查哪篇）：

文档	编号与主题
`client/development-guide/`	01 前端架构与运行环境 · 02 渲染与UI组件体系 · 03 事件·动画·音频·Spine · 04 网络对接与启动编排 · 05 开发规范与红线 · 06 子游戏接入模式与Hooks外置
`server/development-guide/`	01 服务端环境与框架基础 · 02 子游戏接入与开发流程 · 03 数据收发与通信协议 · 04 开发规范与红线
`games/engineering/`	01 架构总则与分层 · 02 可扩展性与配置化 · 03 数据权威·错误处理·演进

测试与 Git

测试纪律：细则见 client 05 §10 / server 04 §10。要点——测试代码可用现代语法（只跑 Node，不上线）；正式代码禁止为测试而加逻辑/放宽校验，禁止为过测而改正式代码或降低测试标准（skip、软化断言、吞异常等）；失败先用证据裁定「业务缺陷 vs 脚本缺陷」；正面/反面/边界用例都要覆盖。
Git 提交（细则见 server 04 §11）：完成一个可独立成立的逻辑改动即可自动提交、无需逐次确认（push 按需）；提交信息用中文、聚焦一件事、结尾保留 Co-Authored-By 署名；不用 git add -A/git add .、不跳过 hooks、不做 reset --hard/push --force。

6.6 KiB Raw Blame History Unescape Escape