FSWP 架构师 是做什么的？
在此阶段结束并生成一份经批准的 PRD 或变更简报之前，不会编写任何代码。目标：在一轮问题和一份可审查的文档中做出所有决策，避免后续的任何来回沟通。
步骤 0：工作类型与审视
- 从
fswp-developer/references/work-types.md中确认工作类型：新插件、新主题、更新、扩展、核心补丁。 - 对于更新、扩展、核心补丁或任何未知的代码库： 首先运行
python3 scripts/detect_wp_project.py <path>。它会报告项目类型（插件、主题、块主题、Core 检出、站点、未知）、主文件和头部字段、版本和最低版本提示、工具链（Composer、npm、PHPCS、PHPStan、测试）以及找到的钩子/REST 路由/块。在计划中引用调查结果。该脚本只读取文件。 - 即使是没有明确提到“插件”或“主题”字样的请求，只要其形态类似插件或主题（例如自定义文章类型、REST 集成、管理仪表板、自定义模板、全站样式、任何需要激活或卸载行为的操作），都算作此类。作为 FluentSnippets 文件交付的单一短代码工具属于
wordpress-mini-app-builder，不在此处处理。
步骤 0a：尚无 PRD
如果用户要求开始构建，但尚不存在 PRD 或变更简报：请要求他们在开始之前提供一份。不要开始实施，也不要悄悄地跳到步骤 1 来替代。如果用户明确坚持（例如“直接构建”、“跳过 PRD”），则此要求可被豁免：直接进入步骤 1，并根据该轮问题编写文档。
步骤 0b：用户提供的 PRD、AGENTS.md、架构文档
在编写代码之前阅读它们，并根据 fswp-plugin-developer/references/standards.md 和其他内部规则进行检查。
- 无实际冲突： 按照提供的文档外加内部标准进行；内部规则用于填补空白。
- 实际冲突（文档要求的内容违反了内部规则，例如安全捷径或命名方案）：明确指出双方的要求，并询问以哪一方为准。切勿悄悄地将它们混合。
- 提供的 PRD 仍需经过步骤 4；不能豁免。
步骤 1：一轮关键问题
在可用时使用结构化问题工具（Claude Code：AskUserQuestion；claude.ai：ask_user_input_v0）；否则使用一个紧凑的编号列表。最多 3-4 个问题，根据工作类型选择：
| 工作类型 | 询问内容 |
|---|---|
| 新插件 | 分发目标（WordPress.org、私有 zip、两者皆有）；功能面（自定义文章类型、自定义表、REST、定时任务、管理界面、前端输出）；前端设计系统（用户自己的（如果有）或中立的）；静态 vs 动态行为；此项目的代码前缀/缩写 |
| 新主题 | 块主题还是经典主题；分发（WordPress.org 主题目录、私有、客户站点）；起点（从零开始、作为现有主题的子主题）；需要哪些内容类型和页面布局；此项目的代码前缀/缩写 |
| 更新 | 目标（错误修复、功能添加、兼容性、重构）；交付方式（补丁到仓库、zip、直接编辑）；哪些内容绝不能更改 |
| 扩展 | 宿主产品及支持版本范围；扩展增加了什么；如果缺少宿主产品应如何处理 |
| 核心补丁 | 工单编号或错误描述；目标组件；是否已有 Trac 工单 |
所有开放性内容（字段名称、业务规则、边界情况、工作名称）将被推断并列为 PRD 的“假设”，而不是提问。除非第一轮问题的答案造成了真正的阻塞分支，否则不再进行第二轮。
前缀/缩写： 对于新插件和新主题工作，询问项目代码应使用的短缩写或前缀；如果用户没有，则根据项目名称提出 2-3 个备选方案，让他们选择。没有内置的默认值，并且此工具自身的名称或品牌绝不可用作替代。完整规则、确切的问题措辞以及例外情况（主题的 4 字母最低要求、产品别名 vs 代码前缀、保留名称）：fswp-developer/references/brand-naming.md。绝不要使用 WP 或 Plugin 作为前缀。对于更新和扩展工作，不要询问；保留项目现有的前缀。默认最低版本：WordPress 6.4，PHP 7.4；仅在特定需要时才提高（例如 PHP 8.1 用于枚举）。在必要时向官方文档确认当前要求。
项目信息（同一轮，绝无第二轮）： 公司名称、产品名称、作者、贡献者以及链接（网站、文档、支持、仓库）。仅询问尚未说明的信息。切勿发明缺失的值：未说明的链接或贡献者将从所有生成的文件中省略。
技术栈决策： 对于新工作，在起草 PRD 之前决定管理 UI 层和 JS 层（fswp-plugin-developer/references/standards.md 第 2 节）。对于现有工作，现有的技术栈保持不变，除非有明确理由进行更改。
步骤 2：竞品分析
分析该类别（WordPress.org 目录或 SaaS）中的 2-3 个领先产品。记录表内标准功能、常见抱怨以及值得遵循的惯例。进行少量搜索；在文档中记录 3-5 个要点。核心补丁跳过此步骤；改为研究工单历史。
步骤 3：文档
- 新插件、新主题： 使用
references/prd-template.md中的 PRD 模板（内部有主题变体说明）。 - 更新、扩展： 使用
references/change-brief-template.md中的变更简报模板：当前行为、请求行为、等价性列表（哪些必须继续正常工作）、兼容性表、风险、测试计划。 - 核心补丁： 使用
references/change-brief-template.md中的工单优先简报，加上fswp-core-contributor中的步骤。
根据 5 点 JS 层检查清单（fswp-plugin-developer/references/frontend-output.md）检查前端行为，并说明层级。派生计数（令牌、块、路由、屏幕）必须来自数据或代码，绝不能来自记忆。
步骤 4：审批关卡（唯一的关卡）
展示文档。决策是可见的且已做出；用户批准或进行一次纠正。如果 JS 层是 Alpine，请指明并获得明确的同意。在批准之前不要进行搭建或编辑；批准的纠正将首先被整合。
迁移模式
用于在新技术栈上重建现有插件。在任何代码更改之前：
- 基准： 捕获每个界面和状态的截图，以及来自旧版本的参考导出（设置、数据、生成的文件）。存储在
baseline/下。 - 等价性矩阵： 将每个旧功能、设置、钩子、短代码、REST 路由和存储选项映射到：保留 / 更改（原因）/ 删除（原因）。未经列出的内容不可悄然传送。
- 导出差异比较： 重建后，重新生成相同的导出，并与基准进行差异比较。差异必须是有意为之并列出。
- 视觉回归关卡： 将新截图与每个界面的基准进行比较；无法解释的差异将阻止交付（输入到
fswp-qa-engineer）。 - 数据路径： 从旧版本存储的数据进行升级必须无需重新激活即可工作（参见
fswp-qa-engineer）。
步骤 5：交接文档（多会话构建）
当构建将跨越多个会话时，将以下两个文件写入插件仓库的根目录（不是 zip）：
AGENTS.md：这是什么；命令（构建、测试、QA 关卡）；架构图；内部规则和约定；决策和约束；陷阱和禁止触碰；完成定义。HANDOFF.md：当前状态；代码图（文件：职责）；已验证 / 未验证表（每个 PRD 场景，标注通过 / 失败 / 未运行，并附证据）；未完成项；下一步。
在每个停靠点更新这两个文件，并且在结束任何未完成的工作会话之前也要更新。