EP15. "wp-site-audit-and-onboarding 项目诊断与上手路由"

• 接手一个从没见过的 WordPress 项目，第一件事该做什么？不是打开每个文件从头看，而是先搞清楚「这是个什么样的项目」——wp-site-audit-and-onboarding 就是干这个的
• 这是 jorgerosal/wordpress-skills 开源 skill 包里的其中一个，定位是整套 18 个 skill 的「大门」：先分类项目、定位架构热点、标出风险信号，再把你路由到对应的专门 skill
• 核心原则：不是一次审完每个文件，而是先分类、再定位、再路由——审计新手上路的目标是「知道下一步该查哪里」，不是「一次查完所有东西」
• 前置知识：先看过 Overview 系列的「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」两篇，知道 Skill 是什么、怎么装

重点内容

这个 Skill 是做什么的

wp-site-audit-and-onboarding 走七步流程：确定审查目标 → 判断项目形态（插件为主？主题为主？headless？WooCommerce 重度定制？multisite？）→ 盘点关键文件面 → 找风险信号 → 路由到专门 skill → 排出优先顺序 → 汇报没查清楚的地方。它不是要取代 wp-security-review、wp-plugin-development 这些专门 skill，而是帮你决定「这个项目该先用哪个专门 skill 查」。

适合用在：

• 接手一个新的 WordPress 代码库
• 第一次审查客户的网站代码
• 搞清楚一个项目是插件驱动、主题驱动、headless、WooCommerce 重度定制、multisite 还是页面构建器（builder）重度依赖
• 迁移/审计/现代化改造/发版前，先摸清风险范围
• 深挖之前先出一份架构地图
• 有人问「审查一下这个 WordPress repo」「帮我上手这个项目」「这个项目用了什么技术栈」「该从哪里开始查」

不适合用在：

• 纯安全审查（交给 wp-security-review）
• 纯性能审查（交给 wp-performance-review）
• 已经确定范围是某个插件的深度架构审查（交给 wp-plugin-development）
• 已经确定范围是某个主题的深度审查（交给 wp-theme-development）
• 已经很清楚是 WooCommerce/ACF/REST/headless 某个领域的专项分析

触发方式

七步审计流程

1. 确定审查目标 — 整个 repo？单个插件？单个主题？wp-content/ 子树？还是把 WordPress 当成其中一个面的 monorepo？
2. 判断项目形态 — 见下面「项目形态识别信号」表
3. 盘点关键文件面 — 入口文件、repo 里的插件/主题、自定义代码目录、构建工具、部署脚本、测试、说明环境假设的文档；不逐条列文件清单，要归纳成有意义的结构
4. 找风险信号 — 多个自定义插件/主题逻辑铺得很散没有清楚边界、直接写 SQL 或自定义表、自定义 REST/GraphQL/认证代码、WooCommerce 结账/订单/支付/webhook、build 系统可能跟已提交的产物不同步、大量依赖 ACF/meta query、multisite 假设、发版自动化关卡不清楚、页面构建器锁定的痕迹、没有测试也没有静态分析
5. 路由到专门 skill — 见下面「路由去哪个 skill」表
6. 排出优先顺序 — 输出要分「立即该查」「次要跟进」「架构备注（不紧急）」三档
7. 严重度要看上下文，不能瞎报 — 不能光靠「架构复杂」就编出 CRITICAL

项目形态识别信号

路由去哪个 skill

实操示例：审计输出报好报坏的差别

# ❌ BAD：直接把文件列表倒出来，没有归纳，看的人还是不知道从哪下手
src/
  components/
    Header.js
    Footer.js
    ProductCard.js
  ...(还有 340 个文件)

# ✅ GOOD：归纳成有意义的结构，并标出这是什么形态
项目形态：Headless WordPress（WPGraphQL）+ Next.js 前端
- wp-content/plugins/custom-graphql-auth/ —— 自定义 GraphQL 认证/预览逻辑（未见文档说明）
- frontend/ —— Next.js 应用，webhook 触发 ISR 更新
- 没有发现 CI/CD 配置，发版流程不明
建议：先查 wp-headless-and-wpgraphql（自定义认证/预览没文档），再查 wp-ci-cd-and-release-engineering（发版流程空白）

# ❌ BAD：光看到「有好几个自定义插件」就报 CRITICAL
CRITICAL：项目架构复杂，包含 5 个自定义插件，建议重构

# ✅ GOOD：架构复杂本身不是漏洞，只有具体风险信号才升级严重度
WARNING：5 个自定义插件里有 3 个都在处理订单相关逻辑，边界不清楚，建议先用 wp-woocommerce-dev
   深挖，确认有没有重复处理或竞态问题
INFO：插件数量偏多，可以考虑合并或理清代码归属，不紧急

怎么安装

这个 skill 是 wordpress-skills 这个开源仓库（jorgerosal/wordpress-skills）打包的 18 个技能之一，安装一次，18 个技能一起到位，不用逐个装：

Claude Code：

装完重启 Claude Code，进到一个 WordPress 项目里跑 /wordpress-skills:wp-onboard-review 验证有没有装成功（用 marketplace/submodule 方式装的话，指令前面会带插件命名空间 wordpress-skills:；用「只装这一个 skill」的方式则不带命名空间，直接 /wp-onboard-review）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传技能文件夹（把 claude-skills/wp-site-audit-and-onboarding 这个文件夹打包上传，里面要包含 SKILL.md）——跟 Claude Code 的 git submodule/marketplace 安装方式不同，Desktop 端是手动上传 UI，装好之后同样能用自然语言或 slash 指令触发。

常见错误

• ❌ 把这个 skill 当成万能审查工具，一路查到底、每个子系统都深挖一遍——它的定位是「路由」，不是「一次审完」，查太深该交给专门 skill 接手
• ❌ 光凭「代码库复杂」「插件数量多」就报 CRITICAL——正常的架构复杂度不该无中生有编出风险等级
• ❌ 汇报时把原始文件列表整个倒出来——这份 skill 明确要求归纳成有意义的结构，不是丢一堆路径
• 💡 目标范围不是整个 repo 时（比如只指定了一个插件），报告里要老实说明哪些部分是刻意没查的，不要假装扫过了整个项目

Sources

官方文档：

1. wordpress-skills（GitHub 仓库）— https://github.com/jorgerosal/wordpress-skills
2. wp-site-audit-and-onboarding SKILL.md — https://github.com/jorgerosal/wordpress-skills/blob/main/claude-skills/wp-site-audit-and-onboarding/SKILL.md