代码考古技能

概述

代码考古是一种系统性分析方法论，用于理解遗留代码库并提取可操作的现代化改造洞见。该技能提供了一系列工具与工作流，支持：

• 业务规则提取：从遗留代码中识别并文档化业务逻辑
• 技术规格生成：提取数据模型、API 合约及系统架构
• 安全风险评估：识别安全漏洞与技术债务
• 迁移规划：生成详尽的迁移需求与任务分解
• AI 计划生成器集成：将分析结果转换为 AI 可执行的上下文文档

统一目录结构

代码考古结果采用标准化目录结构组织：

{project}_code_archaeology/
├── results/                    # 主要分析输出（面向 AI 集成）
│   ├── {project}_api_analysis.md
│   ├── {project}_security_audit_results.md
│   ├── {project}_performance_analysis.md
│   ├── {project}_technical_debt_assessment.md
│   ├── {project}_optimization_recommendations.md
│   └── {project}_code_archaeology_final_report.md
├── process/                   # 详细分析产物（30+ 个文件）
│   ├── 01-system-constants-analysis.md
│   ├── 02-database-schema-analysis.md
│   ├── 03-business-domain-file-list.md
│   ├── {domain}-analysis.md（按业务域分别生成）
│   └── round2_progress.json
├── source/                    # 原始源代码引用
│   └── {project}/
└── {project}_archaeology_status.json  # 分析状态跟踪

核心能力

1. 多轮分析

• 第一轮：业务域映射与核心架构分析
• 第二轮：深度技术评估（安全、性能、优化）

2. 领域专属分析

• 财务管理：支付处理、开票、对账
• 客户管理：用户认证、档案管理
• 合同管理：合同生命周期、状态流转
• 供应链管理：库存、采购、物流

3. 安全风险识别

• 严重级：硬编码凭据、SQL 注入漏洞
• 高危级：弱密码存储、会话管理缺陷
• 中危级：XSS/CSRF 防护缺失、不安全的文件权限

4. 技术债务评估

• 架构层面：单体架构限制、缺乏分层设计
• 代码质量：代码重复、过时的语言特性使用
• 可维护性：缺失文档、测试覆盖率不足
• 性能层面：数据库查询优化、缓存机制

AI 计划生成器集成

代码考古结果可被 AI 计划生成器直接消费，用于生成：

• 活动文档（Campaign Documents）：边界清晰的战略性迁移计划
• 上下文文档（Context Documents）：AI 可执行的业务规则与技术规格
• 任务分解（Task Decomposition）：含优先级与依赖关系的详细实施任务
• 验证标准（Validation Standards）：全面的测试要求与验收准则

集成工作流

# 1. 执行代码考古分析
code-archaeology analyze legacy-project --output-dir legacy_project_code_archaeology

# 2. 基于考古结果生成 AI 计划生成器所需上下文  
ai-plan-generator generate-context-from-archaeology 
  /path/to/legacy_project_code_archaeology 
  context-documents 
  finance

# 3. 验证上下文文档完整性
ai-plan-generator analyze-completeness context-documents

# 4. 创建 ClawTeam 迁移团队
clawteam create --name "finance-migration" --description-file campaign.md

使用指南

适用场景

• 遗留系统现代化：规划从 PHP 5.x、传统 Java 等平台的迁移
• 业务逻辑文档化：提取未文档化的业务规则
• 安全修复：识别并优先处理安全漏洞
• 技术债务消减：系统性规划代码库改进

输入要求

• 源代码访问权限：完整访问遗留代码库
• 业务背景知识：对业务领域及需求具备充分理解
• 目标架构定义：明确的目标现代化架构愿景

输出产物

• 综合报告：面向管理层的摘要与面向技术人员的深度分析
• 可执行建议：已排序的改进与迁移任务清单
• 风险评估：安全与业务连续性风险评估
• 即插即用集成能力：结构化数据，供 AI 计划生成器直接消费

最佳实践

分析流程

1. 由面及点：先开展高层次业务域映射
2. 由浅入深：聚焦关键业务域（如财务、安全敏感模块）
3. 交叉验证：将分析结果与业务干系人进行比对确认
4. 持续迭代：依据反馈与新发现不断优化分析过程

文档规范

• 机器可读：结构化输出，便于 AI 消费
• 人类可理解：面向业务干系人提供清晰解释
• 以行动为导向：聚焦可落地的洞见与建议
• 版本受控：追踪分析过程随时间演进的历史

集成模式

• ClawTeam 编排：利用分析结果驱动多智能体协同
• 持续验证：定期将 AI 的解读结果与原始代码对照验证
• 反馈闭环：通过实施结果反哺并优化后续分析

典型用例

财务模块迁移

输入：存在硬编码凭据的遗留 PHP 财务系统
分析：识别支付处理逻辑、安全漏洞与数据模型
输出：包含安全修复与验证标准的完整迁移方案

用户认证现代化

输入：采用弱密码存储方式的自定义认证系统
分析：提取用户管理流程，识别安全缺口
输出：具备完善安全控制的现代认证实施方案

API 标准化

输入：多个模块间不一致的 RPC 风格 API
分析：梳理全部 API 端点、请求/响应格式与错误处理机制
输出：兼顾向后兼容性的 RESTful API 重构规范

代码考古将遗留代码的理解，从一门经验艺术转变为一套系统化、可复现的科学方法，为 AI 驱动的现代化进程提供坚实基础。

集成脚本

本技能附带用于将代码考古结果转换为 AI 计划生成器格式的集成脚本：

• convert-to-ai-plan-generator.cjs：主转换工具
• code-archaeology-integrator.cjs：核心解析与提取逻辑
• process-file-manager.cjs：文件定位与组织管理

使用方式

node convert-to-ai-plan-generator.cjs /path/to/archaeology-results output-dir domain