fit-gap-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fit-Gap Analysis

Fit-Gap分析

Compare a target (spec, vision, competitor, RFP, "to-be") against a system as actually built ("as-is") and turn it into a meeting-ready comparison: a capability matrix (coverage) + a journey comparison (behaviour), verified against the live system, rolled up into a few decisions. Stack-agnostic.

Output quality rests on two things: how completely you enumerated the target, and how honestly you grounded each verdict in the running system. Most fit-gaps fail on the first — a capability that never makes the list can never be verified.

将目标（规格说明、愿景、竞品、RFP、“未来态”设计）与实际构建的系统（“现状”）进行对比，转化为可直接用于会议的对比结果：一份能力矩阵（覆盖范围） + 旅程对比（行为表现），所有内容均基于实时系统验证，并汇总为若干决策依据。该方法与技术栈无关。

输出质量取决于两点：你对目标的枚举是否完整，以及每个结论是否如实基于运行中的系统。大多数Fit-Gap分析失败的原因在于前者——未被列入清单的能力永远无法得到验证。

When to invoke

适用场景

"fit-gap" · "gap analysis" · "capability comparison" · "as-is vs to-be" · "feature parity" · "how far are we from [vision/competitor]?" · "what would it take to support [X]?" · COTS/vendor evaluation · migration/re-platform scoping · "here's the deck/RFP — what changes, what's the impact?". If the user is measuring an existing system against a target, this applies even if they never say "fit-gap".

“Fit-Gap”·“差距分析”·“能力对比”·“现状与未来态对比”·“功能对齐”·“我们距离[愿景/竞品]还有多远？”·“支持[X]需要做什么？”·COTS/供应商评估·迁移/重新平台化范围规划·“这是演示文档/RFP——需要做哪些变更，影响是什么？”。只要用户是在衡量现有系统与目标的匹配度，即使从未提及“Fit-Gap”，也适用此方法。

Principles (the why)

核心原则（背后逻辑）

Ground truth = the live system, not the docs. Docs, wikis, diagrams, exports, READMEs drift. Verify against the running system — its live schema/contract and actual code/config.
Coverage ≠ behaviour. A checklist says what exists, never how it works. The expensive surprises live in the flow — trace the journey.
Completeness beats depth — you can only verify what you enumerated. The classic miss isn't shallow checking; it's a capability that never reached the list. Enumerate from several sources and in both directions (target→system = missing; system→target = orphaned), then have a critic hunt for what's left.
Evidence over opinion. Every verdict cites a concrete artifact — a field, an endpoint, a
```
file:symbol
```
, a config key, a live count.

真实依据 = 实时系统，而非文档。文档、Wiki、图表、导出文件、README都会过时。需基于运行中的系统验证——包括其实时架构/契约以及实际代码/配置。
覆盖范围≠行为表现。清单只能说明存在什么，永远无法说明运作方式。成本高昂的意外往往藏在流程中——需追踪完整用户旅程。
完整性优于深度——仅能验证已枚举的内容。典型失误并非检查不够深入，而是某项能力从未被列入清单。需从多个来源双向枚举（目标→系统=缺失项；系统→目标=孤立项），再由专人排查遗漏内容。
证据优先，拒绝主观判断。每个结论都需引用具体工件——字段、端点、
```
file:symbol
```
、配置项、实时数据统计等。

The steps

实施步骤

1 · Build the claim list — from several sources, not one. Smallest independently-verdict-able statements, drawn from all of:

a. Stated claims — prose, bullets, captions, acceptance criteria.
b. The UI — first list every screen, state, and role (you can't inspect a control you were never shown — note what's missing and get it). Then walk each screen element-by-element; for every control: (1) what is it? (2) if its value/state changes, does the flow or a calculation change? (3) does it change other UI? (4) which field/data feeds it?
c. The no-UI layer — plugins/triggers, workflows, scheduled & cloud-flow jobs, integrations, business rules, calculated/rollup fields, duplicate-detection, audit, security, storage. Source (b) never surfaces these; report "backend reviewed" separately from "screens reviewed".
d. The guards — visibility rules, business-rule conditions, enable-rules, feature flags, predicates. A static screen/role/state walk misses surfaces that appear only under specific data conditions.

Then a global/cross-cutting pass — these belong to no single screen and are the easiest to drop: identity, tenancy & act-as/impersonation, context-switch, search, notifications, settings, audit, export, navigation, auth, error-handling, feature flags, i18n (locale date/number/timezone), session timeout, environment banners.

Source fidelity & states: you can only enumerate what you're given — if captures are low-res/partial, say so and get the live prototype before claiming completeness. Record the target's version + which flows are drawn vs stubbed. Enumerate states, not just screens: empty, loading, error, validation-fail, no-permission, pagination.

2 · Classify each claim by layer — tells you where to look (and stops "absent" from the wrong layer): Data/State · Logic/Rules · Integration/External · Interface/UX. A claim often spans several.

3 · Extract live structural ground truth — from the running system, not the repo docs: relational app → live

information_schema

/ applied migrations; API → live OpenAPI/proto/real responses; low-code/CRM → metadata endpoint; ERP/SaaS → running config; frontend → deployed routes; infra → live cloud state. For data claims, diff at the metadata level (columns, types, required, option-set members & values, lookup targets, relationships) — a form can look identical while its option set diverges. Script it if it repeats; you'll re-run before implementation.

4 · Verify behaviour in the live code/config. Read the actual implementation; fan out read-only explorers (one per layer/journey) if you have subagents. Confirm semantics, not just names.

5 · Verdict each claim.

Fit / Partial / Gap / Mismatch (exists but a different concept under the same name → rework, not add — the trap a name match misses).
Prohibitions (must-NOT). For negative requirements ("the customer must never see commission"), a capability existing isn't the test — verdict by confirming the prohibition is enforced. Unenforced = Gap, even if the happy-path screen looks right.
"Absent" is a claim you must earn. A single pass can't prove absence (it may sit behind a role, flag, guard, scroll, or empty state). Default unproven items to NOT VERIFIED + the search you actually ran + a confidence; keep "spec is silent" distinct from "spec says absent".
Both directions. Also verdict the reverse — live capabilities the target never mentions — classifying each keep / intentionally-dropped / unknown. In a port, the dangerous regressions are the legacy fields/statuses/workflows the new spec forgot.
Separate schema supports it vs configured/has data (
```
[D]
```
= data-check) vs UI/flow exists.

6 · Actors & access. Not just which actor types exist (verify with live counts) but how identity behaves at runtime — impersonation/act-as, context-switch, dual attribution. Build a role/identity matrix: per privileged role, either observe the surface or mark "NOT INSPECTED under role R". Never conclude "absent" from a single-identity session.

7 · Trace the key journeys. For the high-value/high-risk flows, a step-by-step Target vs Actual table — user action + system behaviour per step, with an artifact each. Surfaces flow divergences a matrix can't: wrong entry point, different ordering, missing step, different mental model.

8 · Cluster + size. Add a Cluster axis (what kind of work: Reuse / Rework / Build-new / Mixed), distinct from the verdict (does it exist); then Effort (S/M/L) + risk/dependency. Cluster collapses many rows into few decisions.

9 · Produce multi-lens, self-explaining artifacts — matrix + journeys + actors/access + impact/effort + open

[D]

items, with a legend so any reader decodes it without you. Land it where it compounds (a living doc) and as a working tracker (spreadsheet). The living doc follows the diagram convention (

${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md

): one overview diagram up top;

sequenceDiagram

for traced journeys,

graph TD

for cluster/dependency views,

flowchart TD

for the decisions framing (step 10).

10 · Frame as decisions, not a feature list. Group gaps into the few choices the meeting can make; sequence by independence (greenfield + quick-wins before big rework); decide if before how.

1 · 构建需求清单——多源采集，而非单一来源。拆解为最小可独立验证的陈述，需涵盖所有以下来源：

a. 明确需求—— prose文本、项目符号、说明文字、验收标准。
b. UI界面——首先列出所有页面、状态和角色（无法检查未展示的控件——需记录缺失内容并补充）。然后逐元素检查每个页面；对于每个控件：(1) 它是什么？(2) 若其值/状态变化，流程或计算逻辑是否会改变？(3) 是否会改变其他UI元素？(4) 由哪个字段/数据提供支撑？
c. 无UI层——插件/触发器、工作流、定时与云流任务、集成、业务规则、计算/汇总字段、重复检测、审计、安全、存储。来源(b)永远无法覆盖这些内容；需将“后端审查”与“页面审查”分开报告。
d. 防护规则——可见性规则、业务规则条件、启用规则、功能开关、断言。静态页面/角色/状态检查会遗漏仅在特定数据条件下才会显示的元素。

随后进行全局/跨领域检查——这些内容不属于任何单个页面，最容易被遗漏：身份认证、租户与模拟身份/代理操作、上下文切换、搜索、通知、设置、审计、导出、导航、权限、错误处理、功能开关、i18n（本地化日期/数字/时区）、会话超时、环境标识。

来源保真度与状态：仅能枚举已获取的内容——若截图分辨率低/不完整，需明确说明，并获取实时原型后再声称完整性。记录目标版本以及哪些流程是已实现的、哪些是占位符。需枚举状态，而非仅页面：空状态、加载中、错误、验证失败、无权限、分页。

2 · 按层分类每个需求——明确检查位置（避免在错误层级标记“缺失”）：数据/状态层 · 逻辑/规则层 · 集成/外部层 · 界面/UX层。单个需求通常会跨多个层级。

3 · 提取实时架构真实依据——从运行中的系统获取，而非仓库文档：关系型应用→实时

information_schema

/已应用的迁移；API→实时OpenAPI/proto/真实响应；低代码/CRM→元数据端点；ERP/SaaS→运行中配置；前端→已部署路由；基础设施→实时云状态。对于数据需求，需在元数据层面对比（列、类型、必填项、选项集成员与值、关联目标、关系）——表单外观可能完全一致，但选项集可能已偏离。若需重复操作可编写脚本；在实施前需重新运行验证。

4 · 在实时代码/配置中验证行为表现。阅读实际实现代码；若有子代理，可为每个层级/旅程分配只读探索任务。需确认语义，而非仅名称。

5 · 为每个需求给出结论。

匹配 / 部分匹配 / 缺失 / 不匹配（存在但为同名异义的概念→需重构，而非新增——这是名称匹配容易忽略的陷阱）。
禁止项（必须不具备）。对于负面需求（“客户绝不能看到佣金信息”），不能仅以能力存在与否作为判断标准——需通过确认禁止规则是否已生效给出结论。未生效=缺失，即使正常路径下的页面显示无误。
“不存在”需经过验证。单次检查无法证明不存在（可能隐藏在角色、开关、防护规则、滚动区域或空状态后）。未验证的项默认标记为未验证，并记录实际执行的搜索操作及置信度；需区分“需求未提及”与“需求明确要求不存在”。
双向对比。同时反向验证——实时系统中存在但目标未提及的能力——将每个此类能力分类为保留 / 有意移除 / 未知。在迁移项目中，危险的回归往往来自新需求遗漏的遗留字段/状态/工作流。
区分架构支持 vs 已配置/有数据（
```
[D]
```
=数据检查） vs UI/流程存在。

6 · 角色与权限。不仅要验证存在哪些角色类型（通过实时统计确认），还要验证运行时身份的行为——模拟身份/代理操作、上下文切换、双重归属。构建角色/身份矩阵：对于每个特权角色，要么观察其界面，要么标记为**“未在角色R下检查”**。绝不能仅通过单身份会话就得出“不存在”的结论。

7 · 追踪关键用户旅程。针对高价值/高风险流程，制作分步式目标vs实际表格——每一步的用户操作+系统行为，并附上对应工件。该表格能发现矩阵无法覆盖的流程差异：错误的入口点、不同的步骤顺序、缺失的步骤、不同的心智模型。

8 · 聚类与评估规模。添加聚类维度（工作类型：复用 / 重构 / 新建 / 混合），与结论维度（是否存在）区分开；然后评估工作量（小/中/大） + 风险/依赖关系。聚类可将大量行数据汇总为少量决策依据。

9 · 生成多视角、自解释的工件——矩阵+用户旅程+角色/权限+影响/工作量+未完成的

[D]

项，附带图例以便任何读者无需额外解释即可理解。将结果存储在可复用的位置（动态文档），同时作为工作跟踪表（电子表格）。动态文档需遵循图表规范（

${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md

）：顶部放置一张概览图；追踪的旅程使用

sequenceDiagram

，聚类/依赖视图使用

graph TD

，决策框架使用

flowchart TD

（步骤10）。

10 · 以决策为框架，而非功能列表。将缺失项归类为会议可做出的少量选择；按独立性排序（先处理全新功能+快速获胜项，再处理大规模重构）；先决定是否做，再决定怎么做。

Completeness gate — before you ship

完整性检查——交付前必须完成

You verified everything on the list; now attack the list. Re-scan the source asking "what is visible or implied that isn't a row yet?", hunting the predictable blind spots from step 1 (UI chrome, global/cross-cutting, the no-UI layer, guarded/conditional surfaces, prohibitions, screens/states/roles you weren't shown). A second pair of eyes catches in seconds what the author's framing hid.

你已验证清单上的所有内容；现在需检查清单本身。重新扫描来源，询问**“哪些可见或隐含的内容尚未列入清单？”**，排查步骤1中提到的常见盲点（UI组件、全局/跨领域内容、无UI层、受防护/条件显示的元素、禁止项、未展示的页面/状态/角色）。他人的视角能在几秒内发现作者框架下隐藏的内容。

Verdict vs Cluster (don't conflate)

结论vs聚类（请勿混淆）

Verdict = does it exist? (diagnosis). Cluster = what kind of work? (treatment). The same Gap can be a cheap additive build or part of a risky rework — keep both axes.

结论 = 是否存在？（诊断）。聚类 = 工作类型？（解决方案）。同一“缺失”项可能是低成本的新增功能，也可能是高风险的重构——需保留两个维度。

Pitfalls (quick-ref)

常见陷阱（速查）

Pitfall	Guard
Enumerating from prose only	walk every control element-by-element (1b)
UI-only enumeration	a no-UI-layer pass (1c) + a guards pass (1d)
Stage/screen-organized list	a global/cross-cutting pass (step 1)
Only the screens/states/roles you were shown	enumerate them first; flag what's missing
Trusting the docs	re-pull from the live system
Same-word trap	verify semantics in code, not names
Prohibition scored "Fit"	verdict must-NOTs by enforcement
"Absent" from one identity/state	default NOT VERIFIED + record the search
Visual form diff only	diff metadata (types, option-set values, relationships)
Reverse-direction blindness	diff both ways; classify every live-only capability
"The matrix is enough"	trace the journeys
Schema = reality	flag `[D]` ; check it's configured/populated

陷阱	防范措施
仅从文本枚举需求	逐元素检查每个控件（步骤1b）
仅枚举UI内容	进行无UI层检查（步骤1c）+防护规则检查（步骤1d）
按页面/阶段组织清单	进行全局/跨领域检查（步骤1）
仅检查展示的页面/状态/角色	先枚举所有内容；标记缺失项
信任文档内容	从实时系统重新提取数据
同名陷阱	在代码中验证语义，而非仅名称
禁止项标记为“匹配”	必须根据生效情况判断禁止项结论
基于单身份/状态得出“不存在”结论	默认标记为未验证，并记录搜索操作
仅对比表单视觉差异	对比元数据（类型、选项集值、关系）
忽略反向对比	双向对比；分类所有仅存在于实时系统的能力
“矩阵足够”	追踪用户旅程
将架构等同于实际情况	标记 `[D]` ；检查是否已配置/填充数据

Output checklist

输出检查清单

Optional dimensions (include if relevant; else mark out of scope so the choice is conscious)

可选维度（相关则包含；否则标记超出范围以明确选择）

Lifecycle / state-transitions — per entity, statuses + the actions driving transitions; verify each transition the target implies, not just the initial state.
Non-functional — perf/SLA, concurrency/locking, security (token/CORS), audit/retention, accessibility, offline.

生命周期/状态转换——针对每个实体，记录状态+驱动转换的操作；验证目标隐含的每个转换，而非仅初始状态。
非功能性需求——性能/SLA、并发/锁、安全（令牌/CORS）、审计/保留、可访问性、离线支持。