Back to Details

code-necromancer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Necromancer

Code Necromancer

Tagline: Raise dead codebases from the grave
Systematic framework for understanding, resurrecting, and modernizing legacy codebases.
标语: 从“坟墓”中唤醒遗留代码库
一套用于理解、复活并现代化遗留代码库的系统性框架。

When to Activate

适用场景

✅ Use when:
  • Inheriting a codebase with 5+ repos and no documentation
  • Resurrecting a product dormant for 2+ years
  • Joining a company with significant technical debt and tribal knowledge loss
  • Performing due diligence on acquired codebases
  • Modernizing legacy systems without breaking existing functionality
❌ NOT for:
  • Greenfield projects (start fresh instead)
  • Well-documented active codebases
  • Simple bug fixes in maintained systems
✅ 推荐使用场景:
  • 接手包含5个以上repo且无文档的代码库
  • 复活已停滞2年以上的产品
  • 加入存在大量技术债务且核心知识流失的公司
  • 对收购的代码库进行尽职调查
  • 在不破坏现有功能的前提下现代化遗留系统
❌ 不适用场景:
  • 新项目（建议从零开始）
  • 文档完善的活跃代码库
  • 维护中系统的简单Bug修复

The Three Phases

三个核心阶段

Phase 1: ARCHAEOLOGY

第一阶段：ARCHAEOLOGY（考古）

Objective: Create a complete map before touching anything.
OutputDescription
repo-inventory.json
All repos with metadata, languages, activity
dependency-graph.mmd
Inter-repo and external dependencies
architecture-diagram.mmd
Visual system topology
tech-stack-matrix.md
Language/framework versions per repo
maturity-assessment.md
Code quality, test coverage, docs quality
missing-pieces.md
Gaps, orphaned repos, broken integrations
Process: Inventory → Deep Scan → Cross-Reference → Visualize → Assess
→ See 
references/archaeology-guide.md
for detailed techniques.
目标: 在修改代码前，先完成完整的代码库映射。
输出物描述
repo-inventory.json
包含所有repo及其元数据、开发语言、活跃度的清单
dependency-graph.mmd
repo间及外部依赖关系图
architecture-diagram.mmd
可视化系统拓扑图
tech-stack-matrix.md
各repo对应的语言/框架版本矩阵
maturity-assessment.md
代码质量、测试覆盖率、文档质量评估报告
missing-pieces.md
存在的缺口、孤立repo、失效集成的记录
流程: 清单梳理 → 深度扫描 → 交叉验证 → 可视化呈现 → 成熟度评估
→ 详见 
references/archaeology-guide.md
获取详细技术指南。

Phase 2: RESURRECTION

第二阶段：RESURRECTION（复活）

Objective: Get the system running in development.
OutputDescription
dependency-audit.md
Outdated packages, vulnerabilities, breaking changes
environment-variables.md
All required env vars with defaults
secrets-needed.md
API keys, certs, OAuth credentials
infrastructure-status.md
Cloud resources, what exists vs deleted
resurrection-blockers.md
Critical issues preventing launch
integration-tests/
Tests verifying components work and communicate
Process: Audit Dependencies → Map Environment → Check Infrastructure → Write Tests → Document Blockers
→ See 
references/integration-test-patterns.md
for resurrection test patterns.
目标: 让系统能在开发环境中正常运行。
输出物描述
dependency-audit.md
过时包、漏洞、破坏性变更的审计报告
environment-variables.md
所有必要环境变量及默认值清单
secrets-needed.md
API密钥、证书、OAuth凭证等敏感信息清单
infrastructure-status.md
云资源现状记录（已存在/已删除）
resurrection-blockers.md
阻碍系统启动的关键问题清单
integration-tests/
验证组件正常运行及通信的集成测试用例
流程: 依赖审计 → 环境映射 → 基础设施检查 → 编写测试 → 记录阻碍因素
→ 详见 
references/integration-test-patterns.md
获取复活阶段测试模式。

Phase 3: REJUVENATION

第三阶段：REJUVENATION（复兴）

Objective: Modernize while maintaining feature parity.
OutputDescription
security-recommendations.md
Vulnerability fixes, compliance
modernization-roadmap.md
Prioritized upgrades with effort estimates
architecture-improvements.md
Scalability, performance, maintainability
Process: Security First → Infrastructure (containerize, CI/CD) → Code Quality → Architecture
目标: 在保持功能一致性的前提下实现代码现代化。
输出物描述
security-recommendations.md
漏洞修复、合规性相关建议
modernization-roadmap.md
带有工作量估算的优先级升级路线图
architecture-improvements.md
关于可扩展性、性能、可维护性的架构优化建议
流程: 安全优先 → 基础设施优化（容器化、CI/CD）→ 代码质量提升 → 架构重构

Key Commands

关键命令

bash
undefined
bash
undefined

List all repos in org

列出组织内所有repo

gh repo list ORG --limit 1000 --json name,primaryLanguage,pushedAt
gh repo list ORG --limit 1000 --json name,primaryLanguage,pushedAt

Dependency analysis

依赖分析

npm audit && npm outdated # Node.js pip list --outdated && safety check # Python go mod graph # Go
npm audit && npm outdated # Node.js pip list --outdated && safety check # Python go mod graph # Go

Find env vars in code

在代码中查找环境变量

grep -rn 'process.env|os.environ' --include=".js" --include=".py"

→ See `references/framework-detection.md` for framework/stack identification.
→ See `references/infrastructure-mapping.md` for cloud resource discovery.
→ See `references/dependency-patterns.md` for dependency detection.
grep -rn 'process.env|os.environ' --include=".js" --include=".py"

→ 详见 `references/framework-detection.md` 获取框架/技术栈识别方法。
→ 详见 `references/infrastructure-mapping.md` 获取云资源发现指南。
→ 详见 `references/dependency-patterns.md` 获取依赖检测方法。

Anti-Patterns to Avoid

需规避的反模式

1. Premature Resurrection

1. 过早复活

What it looks like: Running 
npm install
before reading any code Why it's wrong: You'll fix the same bug 5 times; dependencies have changed Fix: Complete archaeology first; understand before touching
表现: 还没阅读任何代码就运行
npm install
危害: 会重复修复同一个Bug；依赖关系已发生变化 解决方法: 先完成考古阶段；先理解再动手

2. Scope Creep

2. 范围蔓延

What it looks like: "Let's also refactor while we're here" Why it's wrong: Scope explosion; never actually resurrect Fix: Strict phase separation; refactoring is Phase 3
表现: “既然我们在这里，顺便重构一下吧” 危害: 范围失控；永远无法完成复活 解决方法: 严格区分各阶段；重构属于第三阶段

3. Big Bang Updates

3. 一次性大更新

What it looks like: Update all dependencies in one commit Why it's wrong: Something breaks, no idea what Fix: Update incrementally; test after each
表现: 一次提交就更新所有依赖 危害: 出现问题后无法定位根源 解决方法: 增量更新；每次更新后都进行测试

4. Ignoring Tests

4. 忽略测试

What it looks like: "It runs, ship it" Why it's wrong: Regression city; no baseline for changes Fix: Write resurrection tests as you go; they prove progress
表现: “能运行就行，上线吧” 危害: 回归问题频发；没有变更基准 解决方法: 边复活边编写测试；测试是进度的证明

5. Undocumented Changes

5. 无文档变更

What it looks like: "I fixed it but forgot what I changed" Why it's wrong: Tribal knowledge returns; next person is you in 6 months Fix: Document everything you learn and change
表现: “我修复了问题，但忘了改了什么” 危害: 核心知识再次流失；6个月后的你会重蹈覆辙 解决方法: 记录所有学到的信息及做出的变更

6. Trusting Old Documentation

6. 轻信旧文档

What it looks like: Following README from 2019 Why it's wrong: APIs change, services get deprecated Fix: Verify every instruction; documentation lies
表现: 遵循2019年的README操作 危害: API已变更、服务已废弃 解决方法: 验证每一条指令；文档可能过时

Success Metrics

成功指标

Archaeology Complete When:

考古阶段完成标志:

  • All repos cataloged with metadata
  • Dependency graph visualized
  • Architecture diagram created
  • Core vs peripheral repos identified
  • Missing pieces documented
  • 所有repo已完成元数据编目
  • 依赖关系图已可视化
  • 架构图已完成
  • 已识别核心与外围repo
  • 已记录所有缺失部分

Resurrection Complete When:

复活阶段完成标志:

  • All services start locally
  • Services can communicate with each other
  • Integration tests pass
  • At least one full user flow works
  • 所有服务可在本地启动
  • 服务间可正常通信
  • 集成测试全部通过
  • 至少一个完整用户流程可正常运行

Rejuvenation Complete When:

复兴阶段完成标志:

  • No critical security vulnerabilities
  • All dependencies reasonably current
  • CI/CD pipeline working
  • Documentation current
  • Team can develop new features
  • 无严重安全漏洞
  • 所有依赖均保持在合理的最新状态
  • CI/CD流水线正常运行
  • 文档已更新至当前状态
  • 团队可基于该代码库开发新功能

References

参考资料

→ 
references/archaeology-guide.md
- Deep code archaeology techniques → 
references/dependency-patterns.md
- Dependency detection across ecosystems → 
references/framework-detection.md
- Framework/stack identification → 
references/infrastructure-mapping.md
- Cloud resource discovery → 
references/integration-test-patterns.md
- Resurrection test patterns
→ 
references/archaeology-guide.md
- 深度代码考古技术指南 → 
references/dependency-patterns.md
- 跨生态系统依赖检测方法 → 
references/framework-detection.md
- 框架/技术栈识别指南 → 
references/infrastructure-mapping.md
- 云资源发现指南 → 
references/integration-test-patterns.md
- 复活阶段测试模式

Templates

模板

→ 
templates/repo-inventory.json
- Repository catalog → 
templates/archaeology-report.md
- Phase 1 output → 
templates/resurrection-plan.md
- Phase 2 output → 
templates/rejuvenation-roadmap.md
- Phase 3 output
→ 
templates/repo-inventory.json
- 代码库编目模板 → 
templates/archaeology-report.md
- 第一阶段输出报告模板 → 
templates/resurrection-plan.md
- 第二阶段计划模板 → 
templates/rejuvenation-roadmap.md
- 第三阶段路线图模板