gap-analysis

差异分析

通过全面比较、分析和差异识别，系统地找出文档化要求、规格说明与实际实现之间的差异，从而提升系统的完整性和准确性。

适用场景

在以下情况下使用此技能：

• 存在需求文档，但实现状态不明确
• 规格说明已演变，但文档尚未更新
• 代码已更改，但相应文档未同步更新
• 准备审计、合规检查或质量评估
• 为需要准确了解系统的新团队成员提供入职指导
• 规划重构或现代化工作
• 验证实现是否符合设计意图
• 识别未记录功能中的技术债务
• 评估未记录行为带来的风险

我能做什么

1. 文档分析

• 解析各种文档格式（Markdown、YAML、JSON、Confluence、Google Docs 导出文件）
• 从结构化和非结构化文本中提取需求和规格说明
• 识别文档中描述的功能、约束和行为
• 按类型分类需求（功能性、非功能性、业务、技术）
• 评估文档质量（完整性、清晰度、一致性、时效性）

2. 实现分析

• 分析源代码，识别已实现的功能和行为
• 检查 API 契约和接口，了解对外提供的能力
• 审查数据库架构和数据模型，了解持久化结构
• 检查配置文件，了解系统行为设置
• 分析部署产物，了解运行时特征

3. 差异识别

• 比较文档与实际实现的功能，识别不匹配之处
• 检测未记录的实现（有功能但没有文档）
• 识别未实现的文档内容（有文档但未构建）
• 发现行为差异（文档描述的行为与实际行为不同）
• 查找规格偏移，即实现偏离原始规格说明的情况

4. 差异分类与优先级排序

• 按类型分类差异（缺失、不完整、错误、过时）
• 评估差异严重程度（严重、高、中、低）
• 估算解决每项差异所需的工作量
• 根据影响、风险和工作量确定差异的优先级
• 对相关差异分组，以便高效解决

5. 建议与补救计划

• 针对每项已识别的差异生成解决建议
• 制定包含可执行步骤的补救计划
• 建议更新文档，使其与实际实现保持一致
• 提出实现变更，使其符合文档
• 设计验证策略，确认差异已消除

分析技术

文档解析模式

document_sources:
  requirements:
    patterns:
      - "As a [role], I want [feature] so that [benefit]"
      - "The system shall [requirement]"
      - "Must support [capability]"
      - "Should be able to [action]"
  
  specifications:
    patterns:
      - "### Feature: [name]"
      - "**Specification:** [details]"
      - "| Parameter | Type | Required | Description |"
      - "API endpoint: [method] [path]"
  
  architecture:
    patterns:
      - "Component: [name]"
      - "Responsibility: [description]"
      - "Interfaces: [list]"
      - "Data flow: [description]"

代码分析方法

def analyze_implementation(codebase_path):
    """
    Analyze code implementation for features and behaviors.
    """
    features = extract_features_from_code(codebase_path)
    apis = extract_api_endpoints(codebase_path)
    data_models = extract_data_models(codebase_path)
    configs = parse_configuration_files(codebase_path)
    
    return {
        'implemented_features': features,
        'api_endpoints': apis,
        'data_models': data_models,
        'configurations': configs,
        'behavioral_patterns': extract_behavioral_patterns(codebase_path)
    }

差异检测算法

class GapAnalyzer:
    def detect_gaps(self, documented, implemented):
        """
        Detect gaps between documented and implemented items.
        """
        gaps = {
            'undocumented_implementations': [],
            'unimplemented_documentation': [],
            'behavioral_mismatches': [],
            'specification_drift': []
        }
        
        # Find undocumented implementations
        for impl_item in implemented:
            if not self.is_documented(impl_item, documented):
                gaps['undocumented_implementations'].append(impl_item)
        
        # Find unimplemented documentation
        for doc_item in documented:
            if not self.is_implemented(doc_item, implemented):
                gaps['unimplemented_documentation'].append(doc_item)
        
        # Find behavioral mismatches
        for doc_item in documented:
            impl_item = self.find_matching_implementation(doc_item, implemented)
            if impl_item and not self.behaviors_match(doc_item, impl_item):
                gaps['behavioral_mismatches'].append({
                    'documented': doc_item,
                    'implemented': impl_item,
                    'differences': self.find_differences(doc_item, impl_item)
                })
        
        return gaps

差异类型

1. 文档缺失

症状：代码中存在某项功能，但没有相关文档
影响：形成知识孤岛，维护困难，增加入职所需时间
示例：已实现 API 端点，但未在 API 文档中说明

2. 实现缺失

症状：代码中找不到文档描述的功能
影响：无法满足预期、承诺无法兑现、客户不满
示例：文档说明支持“导出为 PDF”，但实际并未实现

3. 行为不匹配

症状：文档描述的行为与实际实现不同
影响：出现错误、集成问题和意外行为
示例：文档称支持“不区分大小写的搜索”，但实际实现区分大小写

4. 文档过时

症状：文档提及已弃用的功能或旧接口
影响：造成困惑、使用不当、浪费开发时间
示例：文档展示的是旧版 API 1.0，但实际实现为 2.0

5. 文档不完整

症状：存在文档，但缺少重要细节 影响：理解不全面、需要猜测、实现出错 示例：记录了 API，但缺少错误响应或速率限制

6. 文档过度细化

症状：文档描述的细节与实现不符 影响：降低实现灵活性，增加维护负担 示例：文档指定了确切的算法，但实现采用了不同的方法

示例

# Analyze gaps between requirements docs and implementation
npm run gap-analysis:analyze -- --requirements requirements.md --code src/ --output gaps.json

# Compare API documentation with actual implementation
npm run gap-analysis:compare -- --api-docs api.md --code src/api/ --output api-gaps.yaml

# Identify undocumented features
npm run gap-analysis:undocumented -- --code src/ --docs docs/ --output undocumented-features.md

# Check for unimplemented requirements
npm run gap-analysis:unimplemented -- --requirements specs/ --code src/ --output missing-features.json

# Generate remediation plan
npm run gap-analysis:remediate -- --gaps gaps.json --output remediation-plan.md

# Continuous gap monitoring
npm run gap-analysis:monitor -- --watch --requirements docs/ --code src/ --alert-on-gap

输出格式

差距分析报告：

Gap Analysis Report
───────────────────
System: User Management Service
Analysis Date: 2026-02-26
Documents Analyzed: 3 (requirements.md, api-spec.yaml, architecture.md)
Code Analyzed: 42 files, 8,567 lines

Summary:
✅ Documented & Implemented: 28 features (70%)
⚠️  Documented but Not Implemented: 6 features (15%)
⚠️  Implemented but Not Documented: 4 features (10%)
❌ Behavioral Mismatches: 2 features (5%)

Gap Details:

1. CRITICAL: Missing Implementation
   • Feature: "User password reset via email"
   • Location: requirements.md:45
   • Impact: Security feature missing
   • Effort: Medium (3-5 days)
   • Recommendation: Implement password reset flow

2. HIGH: Missing Documentation
   • Feature: "User session invalidation on role change"
   • Location: src/auth/session.js:123
   • Impact: Undocumented security behavior
   • Effort: Low (2 hours)
   • Recommendation: Document in security.md

3. MEDIUM: Behavioral Mismatch
   • Documented: "Search returns max 100 results"
   • Implemented: "Search returns max 50 results"
   • Location: api.md:89 vs src/search.js:45
   • Impact: Performance vs functionality tradeoff
   • Effort: Low (configuration change)
   • Recommendation: Align implementation with docs or update docs

4. LOW: Outdated Documentation
   • Documented: "API version 1.2"
   • Implemented: "API version 2.0"
   • Location: api.md:1 (header)
   • Impact: Confusion for API consumers
   • Effort: Low (documentation update)
   • Recommendation: Update API documentation

Priority Matrix:
┌─────────────┬─────────┬─────────┬──────────────┐
│ Priority    │ Count   │ Effort  │ Risk         │
├─────────────┼─────────┼─────────┼──────────────┤
│ Critical    │ 1       │ 3-5 days│ Security     │
│ High        │ 2       │ 1 day   │ Compliance   │
│ Medium      │ 3       │ 2 days  │ User Experience│
│ Low         │ 6       │ 3 days  │ Maintenance  │
└─────────────┴─────────┴─────────┴──────────────┘

Remediation Plan:
1. Week 1: Address critical security gap (password reset)
2. Week 2: Document undocumented security features
3. Week 3: Align behavioral mismatches
4. Week 4: Update outdated documentation
5. Ongoing: Implement gap monitoring to prevent recurrence

差距分析 JSON 输出：

{
  "analysis": {
    "system": "user-management",
    "timestamp": "2026-02-26T19:00:00Z",
    "documents_analyzed": ["requirements.md", "api-spec.yaml"],
    "code_analyzed": ["src/", "lib/"],
    "summary": {
      "total_features": 40,
      "documented_and_implemented": 28,
      "documented_not_implemented": 6,
      "implemented_not_documented": 4,
      "behavioral_mismatches": 2,
      "gap_percentage": 30
    }
  },
  "gaps": [
    {
      "id": "gap-001",
      "type": "missing_implementation",
      "severity": "critical",
      "description": "User password reset via email not implemented",
      "document_reference": "requirements.md:45",
      "code_reference": null,
      "impact": "Security feature missing, violates compliance requirements",
      "effort_estimate": "3-5 days",
      "recommendation": "Implement password reset flow with email verification",
      "owner": "security-team",
      "due_date": "2026-03-05"
    },
    {
      "id": "gap-002",
      "type": "missing_documentation",
      "severity": "high",
      "description": "User session invalidation on role change not documented",
      "document_reference": null,
      "code_reference": "src/auth/session.js:123",
      "impact": "Undocumented security behavior, audit finding risk",
      "effort_estimate": "2 hours",
      "recommendation": "Add to security documentation and API docs",
      "owner": "documentation-team",
      "due_date": "2026-03-01"
    }
  ],
  "remediation_plan": {
    "phases": [
      {
        "phase": 1,
        "name": "Critical Security Gaps",
        "duration": "1 week",
        "gaps": ["gap-001"],
        "deliverables": ["Password reset implementation", "Security review"]
      },
      {
        "phase": 2,
        "name": "Documentation Cleanup",
        "duration": "1 week",
        "gaps": ["gap-002"],
        "deliverables": ["Updated security docs", "API documentation"]
      }
    ],
    "total_effort": "2 weeks",
    "priority_order": ["gap-001", "gap-002"],
    "success_criteria": ["All critical gaps closed", "Documentation coverage > 90%"]
  }
}

差距监控仪表板：

Gap Monitoring Dashboard
────────────────────────
Status: ACTIVE
Last Analysis: 2026-02-26 19:00:00
Next Analysis: 2026-02-27 07:00:00

Trends:
┌──────────────────────────────────────┐
│ Gap Trend (Last 30 Days)            │
│                                      │
│ 40 ┤                                │
│    │                                │
│ 30 ┤                █               │
│    │               █ █              │
│ 20 ┤              █   █             │
│    │             █     █            │
│ 10 ┤           █       █           │
│    │          █         █          │
│  0 ┼───────────█─────────█─────────│
│     1   5   10   15   20   25   30 │
│              Days                  │
└──────────────────────────────────────┘

Current Gaps by Type:
• Missing Documentation: 4 (33%)
• Missing Implementation: 3 (25%)
• Behavioral Mismatch: 3 (25%)
• Outdated Documentation: 2 (17%)

Gap Age Distribution:
• < 1 week: 6 gaps
• 1-4 weeks: 4 gaps
• 1-3 months: 2 gaps
• > 3 months: 0 gaps

Alert Status:
✅ No critical gaps
⚠️  2 high-priority gaps aging > 2 weeks
✅ Documentation coverage: 85%
✅ Implementation coverage: 90%

Recommended Actions:
1. Address 2 high-priority gaps aging > 2 weeks
2. Improve documentation for 4 undocumented features
3. Schedule review for 3 behavioral mismatches

备注

• 差距分析不是追责活动——应专注于改进系统，而非归咎于谁
• 定期进行差距分析可防止问题累积——频繁进行小规模分析，胜过偶尔进行大规模分析
• 尽可能实现自动化——持续检测差距可以及早发现问题
• 让相关方参与进来——开发人员、产品经理和技术文档撰写人员应协作解决差距
• 根据影响确定优先级——并非所有差距都同等重要
• 跟踪差距的弥合情况——衡量随时间推移缩小差距的进展
• 主动开展差距分析——不仅用于发现问题，也用于提升质量
• 融入开发工作流——差距分析应为规划和优先级排序提供依据
• 记录分析流程——以便重复执行并持续改进
• 庆祝差距缩小——肯定系统完整性和准确性的提升