多客户端项目核心/客户端边界审计与重构：检测共享代码与客户专…

当多客户端项目需要审计共享平台代码（core）与各部署专属代码（client）的边界是否清晰，并据此重构时使用。

适用场景

解决思路

1. 判断项目类型：检查是否存在 clients/ 或 tenants/ 目录（显式多客户端）、多个带客户名的配置文件（配置驱动）、packages/ 中共享与按客户分包（monorepo）、CLIENT_NAME 或 TENANT_ID 等环境变量（运行时多客户端）、或仅单一部署无客户目录（单客户端，可能正走向多客户端）。若为单客户端，检查 CLAUDE.md 或代码库是否暗示将变为多客户端，是则做就绪审计，否则不需要本技能。
2. 构建边界地图：扫描代码库，将路径归类为 CORE（如 src/server/、src/client/、src/db/schema.ts、migrations/0001-0050）、CLIENT（如 clients/acme/config.ts、clients/acme/kb/、clients/acme/seed.sql、migrations/0100+）和 BLURRED（需关注，如 src/server/routes/acme-custom.ts、src/config/defaults.ts 中硬编码的客户域名）。
3. 查找违规——核心代码中的客户名：用 grep -rn "acme\|smith\|client_name_here" src/ --include="*.ts" --include="*.tsx" 搜索硬编码客户标识；用 grep -rn "if.*client.*===\|switch.*client\|case.*['\"]acme" src/ --include="*.ts" --include="*.tsx" 搜索客户专属条件分支；用 grep -rn "CLIENT_NAME\|TENANT_ID\|process.env.*CLIENT" src/ --include="*.ts" --include="*.tsx" 搜索共享代码中基于环境的客户检查。严重度：高。
4. 查找违规——配置替换而非合并：检查客户配置是整体替换还是覆盖默认值。坏例子是 clients/acme/config.ts 导出完整对象导致默认值丢失；好例子是客户配置只覆盖差异字段，其余由 config/defaults.ts 提供。识别信号：客户配置文件异常大（接近默认文件大小）或定义了默认值已处理的字段。严重度：中。
5. 查找违规——客户代码散落：用 find src/ -name "*acme*" -o -name "*smith*" -o -name "*client-name*" 查找 src/ 内路径含客户名的文件；用 grep -rn "// only for\|// acme only\|// client-specific" src/ --include="*.ts" --include="*.tsx" 查找仅服务单一客户的路由或页面。严重度：高。
6. 查找违规——缺失扩展点：检查核心是否提供无需修改即可定制客户的机制，包括配置合并（config/ 是否有合并函数）、动态导入（核心是否查找 clients/{name}/custom/）、功能开关（功能是否由配置而非代码切换）、主题令牌（颜色/样式是否为变量而非硬编码）、内容注入（客户能否提供种子数据、模板）、钩子/事件系统（客户能否在不打补丁的情况下扩展行为）。严重度：中。
7. 查找违规——迁移编号冲突：用 ls migrations/ | sort | head -20 列出迁移文件及编号，检查客户迁移是否落在保留区间（核心 0001-0099，客户领域 0100-0199，客户自定义 0200+）。严重度：低，直到引发冲突则变为严重。
8. 查找违规——功能开关 vs 客户检查：搜索按客户身份而非配置分支的行为。坏例子是 if (clientName === 'acme') { showEmailOutbox = true; }；好例子是 if (config.features.emailOutbox) { showEmailOutbox = true; }。
9. 产出报告：写入 .jez/artifacts/fork-discipline-audit.md，包含项目名、日期、模式、客户列表、边界地图（Core 共享表含路径/用途/是否干净，Client 按部署表含配置/内容/Schema/自定义，Blurred 表含路径/问题/建议修复）、违规（按高/中/低严重度列出 file:line、描述、修复）、扩展点表（配置合并/动态导入/功能开关是否存在及备注）、健康分（1-10 及说明）、Top 3 建议。
10. 文档模式：在项目根生成 FORK.md，包含架构说明、什么是 Core（不要按客户修改）、什么是 Client（随部署变化）、如何新增客户（复制 clients/_template/ 到 clients/new-client/、编辑 config.ts 覆盖项、向 content/ 添加种子数据、创建 0100+ 编号迁移、用 CLIENT=new-client wrangler deploy 部署）、Fork 测试（修改任何文件前问这是 core 还是 client）、迁移编号表（0001-0099 核心平台，0100-0199 客户领域 Schema，0200+ 客户自定义功能）、配置合并模式（展示项目实际的合并代码）。
11. 重构模式——将客户代码移出核心：对每个客户代码位于 src/ 的违规，执行 mkdir -p clients/acme/custom/routes、git mv src/routes/acme-custom.ts clients/acme/custom/routes/，并更新核心导入以使用动态发现。
12. 重构模式——用功能开关替换客户检查：对核心中每个 if (client === ...)，改为在 src/ 中用 if (config.features.emailOutbox) 判断，并在 clients/acme/config.ts 中导出 features: { emailOutbox: true } 启用。
13. 重构模式——实现配置合并：若项目替换而非合并配置，创建 config/resolve.ts，导入 defaults，导出 resolveConfig(clientConfig: Partial<Config>): Config，返回 { ...defaults, ...clientConfig, features: { ...defaults.features, ...clientConfig.features }, theme: { ...defaults.theme, ...clientConfig.theme } }。
14. 重构模式——为客户自定义路由添加扩展点：若客户需要自定义路由但当前修改核心，在 src/server/index.ts 中自动发现客户路由：const clientRoutes = await import(`../../clients/${clientName}/custom/routes`).catch(() => null); if (clientRoutes?.default) { app.route('/custom', clientRoutes.default); }。
15. 重构模式——生成重构脚本：写入 .jez/scripts/fork-refactor.sh，创建客户目录结构、移动已识别文件、更新导入路径、生成 FORK.md。
16. 按客户数量决定时机：1 个客户不要重构，只写 FORK.md 记录边界；2 个客户运行审计，修复高严重度违规，开始配置合并模式；3+ 个客户执行完整重构模式，边界必须干净。遵循纪律第 5 条：客户 #3 之前不要抽象——1 个客户是猜测，2 个是模式匹配，3+ 才知道真正变化的是什么。
17. 实践提示：在新增客户之前运行而非之后；配置合并是 ROI 最高的重构，优先做；即使只有一个客户，功能开关也优于 if (client)，「除了……基本一样」意味着功能开关而非分叉；FORK.md 是给团队看的，要像给人阅读一样写。

适用边界 · 注意事项

• 项目确实是永久单客户端且无多客户端计划时，不需要本技能。
• 客户数量为 1 时不要做重构，只需记录边界（FORK.md）。
• 客户数量为 2 时不要做完整重构，只修复高严重度违规并开始配置合并。